PPPAIMT-Crest/docs/EMAIL.md

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.