32 lines
2.5 KiB
Markdown
32 lines
2.5 KiB
Markdown
# Email
|
|
|
|
Agreement mail is sent with SendGrid after the database change is committed. A delivery failure is stored on `email_log` and does not change the application status.
|
|
|
|
## Domain authentication
|
|
|
|
In the SendGrid dashboard, authenticate the sending domain before using a live `MAIL_FROM` address.
|
|
|
|
1. Add the domain under Settings, then Sender Authentication.
|
|
2. Publish the SPF record SendGrid provides. It authorizes SendGrid to send for that domain.
|
|
3. Publish the DKIM CNAME records SendGrid provides. They sign each message.
|
|
4. Add a DMARC TXT record at `_dmarc.your-domain`. Start with `v=DMARC1; p=none; rua=mailto:dmarc@your-domain` and tighten the policy after reports look healthy.
|
|
|
|
The webhook endpoint is `POST /api/webhooks/sendgrid`. In SendGrid, enable the signed event webhook and paste the verification key into `SENDGRID_WEBHOOK_VERIFICATION_KEY`. Delivered, bounce, and dropped events update `email_log.status`.
|
|
|
|
## Environment
|
|
|
|
| Variable | Purpose |
|
|
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
| `SENDGRID_API_KEY` | SendGrid API key. When it is empty, development and test keep the link in the server log and do not call SendGrid. |
|
|
| `MAIL_FROM` | From address. The display name is the `mail_from_name` setting, or `Chest Research and Training`. |
|
|
| `SENDGRID_SANDBOX_MODE` | `true` calls SendGrid with sandbox mode, so the API accepts the message and does not deliver it. |
|
|
| `SENDGRID_WEBHOOK_VERIFICATION_KEY` | Public key for the event webhook signature. |
|
|
| `ADMIN_NOTIFY_EMAILS` | Comma-separated admin addresses notified when a physician submits. |
|
|
| `APP_BASE_URL` | Public site origin used in resume, survey, and admin links. |
|
|
|
|
## Testing without delivery
|
|
|
|
Set `SENDGRID_SANDBOX_MODE=true` with a real API key and `MAIL_FROM`. SendGrid validates the request and returns a message id, and the recipient does not receive the email.
|
|
|
|
With no `SENDGRID_API_KEY`, a development server logs the resume or survey URL and writes `email_log.status` as `logged`.
|