Deliverability, tracking and safe testing

Who this is for. Whoever takes a site's email to production, and anyone testing a job that sends mail. Afterwards you can launch mail that arrives, report opens and clicks honestly, and test without mailing a customer.

Before the first real send

Mail goes out through the client's own SendGrid account when its key is set in the Mailer settings (SendGrid API Key), and through the platform's shared account when the field is blank. On the shared account, messages go out under the platform's shared sender identity, which is not authenticated for the client's domain, so a From address on that domain can fail the receiving server's checks. The pre-launch checks, in order:

1. The client's own SendGrid key is set in the Mailer settings on production. The key is shared by every site of the client.
2. The sending domain is authenticated in that SendGrid account: the DNS records it gives you (DKIM, and the return-path record SPF uses) are published and verified.
3. The domain has a DMARC record, starting at p=none with reports, tightened once the reports show only your own mail.
4. The sender is an address on that domain: Default sender email and Default sender name in the Mailer settings, and the Sender of each Send Email action that sets its own. Replies go to a mailbox someone reads.
5. A test to a mailbox at each of the big providers lands in the inbox, not in spam, and its headers show DKIM and SPF passing.
6. Every link and image is absolute and on the production hostname.

Opens and clicks

Delivery reports, opens and clicks come back from SendGrid's event webhook, which must be set in the SendGrid account to post to https://<production hostname>/cdna-api/sendgrid-event. Each report is matched to its email by the provider's message id:

Each email has its open and click counts, and each mailer batch counts how many of its emails were opened or clicked at least once, through GET /cdna-api/mailer/emails/{batch id} and /cdna-api/mailer/batches. The endpoint reads one event per request, and SendGrid can group several events into one post: check that interactions are arriving in the mailer's records before you promise a client open and click figures. Open counts are estimates anyway, because many mail clients load images through a proxy or not at all; clicks are the number to report.

Testing safely

The platform's redirect. On a non-production environment the mailer sends every recipient that does not match the Development email whitelist (a regular expression) to the single Development email address, both in the Mailer settings. The switch is the server's environment, not a site setting, so the same site configuration redirects on a development server and delivers for real on production. Set the development address to your team's test inbox and narrow the whitelist to it: the default whitelist lets through a set of domains belonging to the platform team.

A redirect of your own. Because the platform's redirect depends on where the site runs, add one that depends on data you control. Site data does not travel with an export or a deploy, so a key that exists only on test environments is a reliable marker. In every Send Email, write the recipient as:

and set mail-redirect-to in site data (System › Sites › Site Data) on every environment except production. A redirected message is addressed to a plain address rather than the person, so its %firstName% comes out empty, which is itself a visible sign that the redirect worked.

Prove the redirect before trusting it. Neither redirect shows in the job: the run log records only that the mail was queued, and the platform's redirect happens later, as it is sent.

1. Trigger the flow on the test environment for a test record whose email is an address you control that is not whitelisted.
2. The message arrives in the test inbox, and not at the address on the record.
3. The mailer's email record shows status sent or delivered.
4. Repeat after every copy of production data onto the test environment, which brings real customers' addresses with it.

The rest of the procedure for testing a job applies too: narrow the trigger to a test record, and send the first real message on production to yourself (Testing a job without touching live data).