Testing SendGrid emails

A newsletter built in Single Sends and a password reset sent through /v3/mail/send can leave the same SendGrid account and still arrive as quite different emails, which matters for a spam test. Marketing Campaigns always tries to add unsubscribe headers, while the API adds them only if you asked it to, so decide which of the two you are testing before you send anything.

The receiving end is the same for both. Email Spam Tester gives you a temporary address, no account needed. Only the first message that arrives within the hour counts, and it gets a report covering authentication, SpamAssassin and Rspamd verdicts, content, the Bulk sender rules that Gmail and Yahoo set, and 21 blocklists queried with your sending IP.

Single Sends: the test button and its prefix

The built-in test lives at Marketing > Single Sends. Open the Single Send, find Test Your Email, type the test address and click Send Test Message. SendGrid wants a sender and a subject before it lets you test, and a subject with Handlebars needs Test Data filled in. On the way out, SendGrid puts Test - in front of the subject line.

For the real thing, send the Single Send to a list. Single Sends go to lists or segments, so make a list with the test address as its only contact and pick it under Recipients. Now the headers, the unsubscribe link and the tracked links are the ones a subscriber gets. If you also took the inbox test, its provider inboxes can join that list.

The API and SMTP: one curl command

Trimmed from SendGrid's getting-started example, with the test address as recipient:

curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \
  --header 'Authorization: Bearer <<YOUR_API_KEY>>' \
  --header 'Content-Type: application/json' \
  --data '{"personalizations":[{"to":[{"email":"test-xxxxxxxxxxxxxxxxxxxx@t.email-spam-tester.com"}],"subject":"Hello, World!"}],"content":[{"type":"text/plain","value":"Heya!"}],"from":{"email":"you@yourdomain.com","name":"Your Name"}}'

When the inbox test is on, your provider inboxes go into the same to array and the marker goes into subject, so the one request also tells you which folder Gmail, Outlook, Yahoo and other providers put the email in.

Paste in your own test address and a From that SendGrid has verified, through single sender verification or domain authentication. Better still, send the message your app actually sends, with its real HTML, because the content checks will grade what's in the body.

If your application talks SMTP, nothing changes except the transport. The host is smtp.sendgrid.net, the username is literally the string apikey (not your key), and SSL runs on port 465.

There is also a test-send endpoint, POST /v3/marketing/test/send_email. It takes up to 10 addresses but works only with Dynamic Transactional Templates, so for most API mail the plain Mail Send call above is the honest test.

Unsubscribe headers depend on the path you chose

Marketing Campaigns tries to add List-Unsubscribe headers every time. Mail sent through the API or SMTP gets them only when Subscription Tracking is switched on under Settings > Tracking. In that case SendGrid inserts List-Unsubscribe with an HTTPS link and List-Unsubscribe-Post: List-Unsubscribe=One-Click.

Without Subscription Tracking you add the headers yourself in the request:

"headers": {
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  "List-Unsubscribe": "<mailto:unsubscribe@yourdomain.com>, <https://yourdomain.com/unsubscribe>"
}

SendGrid asks for both the mailto and the https part, and warns against unsubscribing anyone on a plain GET to that link. Be careful copying from SendGrid's support article on these headers. Its second sample sets List-Unsubscribe-Post to URLs, which is wrong. The value is always List-Unsubscribe=One-Click. Our List-Unsubscribe fix page has the rest.

If the message is a password reset or a receipt and carries no list headers, the report marks the Bulk sender rules group as skipped instead of failing it. A newsletter sent through the API doesn't get that pass.

Reading the authentication results

On an account without domain authentication, recipients see "via sendgrid.net" after your From address, and SendGrid's docs say domain authentication removes it. The report goes further than the tag. Look at the DKIM and SPF alignment lines. If the signature or the return path belongs to a SendGrid domain rather than yours, DMARC can't pass for your From, and the plan should point you to domain authentication. Sending From a gmail.com or yahoo.com address is worse. SendGrid's DMARC page says both SPF and DKIM fail for those, and the console itself warns that such messages might fail a DMARC check.

Domain authentication lives in Settings > Sender Authentication. With automated security on, which is the default, SendGrid gives you four records:

• a CNAME at em[0000], which covers SPF and becomes your return path;
• CNAMEs at s1._domainkey and s2._domainkey for DKIM;
• a TXT at _dmarc with v=DMARC1; p=none;.

With automated security off, you get an MX and an SPF TXT (v=spf1 include:sendgrid.net ~all) at em[0000], plus a DKIM TXT at m1._domainkey, and you look after the SPF record yourself. If your DNS provider rejects CNAME names that contain _, that is the only option. And if another service already uses the selector s, SendGrid lets you pick a custom one. Check the result with the DKIM checker (selector s1) and the SPF checker, which also counts DNS lookups if your SPF record is getting crowded.

Links, IPs and the rest of the report

Click tracking rewrites every link. If your link text is itself a URL, the visible address and the real target stop matching, and the report's link mismatch check will flag it. SendGrid's deliverability page points out the same problem. Use words as link text, or set up link branding so the tracked links run through your own domain, which has to match your From domain.

Trial and Essentials plans send from shared IP pools, which SendGrid notes can change without notice if your reputation changes, so a blocklist hit on one of them concerns everyone in that pool. The blocklist checker lets you look the IP up again later. Reverse DNS is configurable only with a dedicated IP, which comes with Pro Email API and Advanced Marketing Campaigns.