Startup

doc/email.md

@@ -0,0 +1,45 @@
+# Email Delivery: Dev Mailcatcher & Production SendGrid
+
+This application uses Symfony Mailer. We separate development and production delivery:
+
+- Development: Mailpit (mailcatcher) via SMTP in Docker.
+- Production: SendGrid via API transport.
+
+## Development (Mailpit)
+
+- Service is defined in `compose.override.yaml` as `mailer` (axllent/mailpit).
+- Ports:
+  - SMTP: 1025 (mapped to host 1025)
+  - Web UI: 8025 (mapped to host 8025)
+- Default DSN for dev is set in `.env`:
+
+```
+MAILER_DSN=smtp://mailer:1025
+```
+
+- Usage:
+  1. Start stack: `docker compose up -d`
+  2. Send an email from the app.
+  3. Open http://localhost:8025 to view captured emails.
+
+## Production (SendGrid)
+
+Use the SendGrid API transport. Do not commit secrets.
+
+- Example configuration is in `.env.prod`:
+
+```
+MAILER_DSN=sendgrid+api://%env(resolve:SENDGRID_API_KEY)%@default
+```
+
+- Provide `SENDGRID_API_KEY` via:
+  - Real environment variable on the server/container, or
+  - Symfony secrets: `php bin/console secrets:set SENDGRID_API_KEY` (and dump for prod), or
+  - Orchestration secret stores (e.g., Docker/K8s).
+
+### Notes
+- No Mailpit container is defined in the base `compose.yaml`, only in `compose.override.yaml`. This ensures it is used in development only.
+- To test email locally without Docker, you can:
+  - Run Mailpit on your host (ports 1025/8025) and set `MAILER_DSN=smtp://127.0.0.1:1025` in `.env.local`.
+- If you need to use SendGrid SMTP instead of API, a DSN example:
+  `smtp://apikey:YOUR_SENDGRID_API_KEY@smtp.sendgrid.net:587`.