Transactional email: the complete guide for developers

A message is transactional when it is generated by a specific event tied to a specific person, and when the recipient would reasonably expect it as a consequence of that event. The test is not the content or the tone — it is the trigger. Nobody subscribes to a password reset. They request one, implicitly, by clicking "forgot password."

This matters legally as well as technically. Most anti-spam regimes — CAN-SPAM in the United States, PECR and the UK GDPR in Britain, CASL in Canada — carve out messages whose primary purpose is to facilitate an already-agreed transaction or provide information about an existing relationship. Those carve-outs are narrower than people assume: adding a promotional block to a receipt can move the whole message into the commercial category, taking its consent and unsubscribe obligations with it.

The last row is the boundary case. Notification email is transactional in mechanism — one trigger, one recipient — but it is discretionary in a way a receipt is not. Users can and do mark notification mail as spam when the volume outruns their interest, which is exactly why notification preferences belong in your product and why high-volume notification streams are often worth separating from critical mail.

Most delivery problems are diagnosed badly because the sender has an incomplete mental model of the path. There are five distinct stages, and each one fails in a different way with a different remedy.

Between February 2024 and May 2025, the three largest consumer mailbox providers converted a decade of "best practice" into enforced policy. The practical consequence is that authentication is no longer a deliverability optimisation — it is an admission requirement, and failing it produces an SMTP rejection rather than a spam-folder placement.

Two details in that table trip up teams who believe they are already compliant. The first is alignment: it is not sufficient for SPF to pass. The domain that SPF or DKIM authenticated has to match the domain in the visible From: header, or DMARC fails regardless. The second is that the volume threshold counts messages to that provider, not messages in total — a product with a consumer user base can cross 5,000 daily Gmail messages long before it feels like a "bulk sender."

The one-click unsubscribe requirement applies to marketing and subscribed messages, not to genuine transactional mail. Adding List-Unsubscribe to a password reset is not merely unnecessary; it invites a user to unsubscribe from mail they cannot function without. Send the header where it belongs and leave it off where it does not.

The naive implementation calls the email API inline, inside the request handler that produced the event. It works until the day the email provider is slow, at which point your checkout endpoint is slow too. Five patterns separate a durable implementation from a fragile one.

Enqueue a job; do not call the mail API from the handler that serves the user. This decouples your latency from the provider's, gives you a natural retry surface, and means a provider incident degrades email rather than degrading checkout. The exception is genuinely interactive mail — a magic link the user is sitting and waiting for — where an inline call with a short timeout and a queued fallback is defensible.

Any queue that guarantees at-least-once delivery will eventually run your send twice. Without an idempotency key, the customer gets two receipts. With one, the second attempt returns the original message id and sends nothing. Derive the key from the domain event — the order id, the reset token — not from a random value generated at send time, or retries will produce a fresh key each attempt and defeat the mechanism.

When an address hard bounces or a recipient files a complaint, sending to it again is actively harmful: repeated delivery attempts to invalid mailboxes are one of the clearest spam signals available to a receiving provider. A suppression list closes that loop automatically, and a good provider enforces it on your behalf at send time rather than trusting you to check.

Webhooks are how you learn what happened after acceptance. At minimum, subscribe to delivery, bounce, and complaint events, verify the signature on each payload, and write the outcome back against your own record. The payoff is that "did the customer get their receipt?" becomes a database query instead of a support conversation.

Marketing metrics translate badly to transactional mail. Open rate on a receipt tells you little about health, and click rate on a password reset is a function of how many people forgot their password, not how good your email is. The metrics that indicate whether the system is working are narrower.

Two of those deserve comment. Time to inbox is measured from your domain event, not from your API call — if a message sits in your own queue for four minutes, that is your outage, and measuring only the provider leg hides it. And complaint rate should be tracked per stream: a blended figure across receipts and product announcements will look acceptable right up until the announcements get your receipts filtered.

Beyond your own instrumentation, register every sending domain in Google Postmaster Tools and Microsoft SNDS. These are the only sources that report on reputation and spam rate from the receiving side. Your provider can tell you a message was accepted; only the receiver can tell you what it thought of you.

Everything above is within your control. The part that is not is whose reputation your mail inherits. Mailbox providers score the sending IP and the sending domain, and on a shared pool the IP portion of that score is a shared asset — built by every sender on the pool and damaged by any one of them.

This is the uncomfortable arithmetic of transactional email: you can hold a perfect complaint rate, authenticate flawlessly, and still see delivery degrade because an unrelated customer on the same infrastructure ran a bad campaign. The failure is invisible to you, it arrives without warning, and there is no lever on your side to pull.

The mitigations are structural rather than tactical. Send transactional mail from a subdomain with its own DKIM key so domain reputation is scored separately. Choose infrastructure whose other tenants resemble you — a pool that carries only paying transactional senders behaves very differently from one that carries free-tier signups and marketing blasts. And above a certain volume, stop sharing the IP layer at all.

That last row is the one enterprise buyers raise first and most providers answer worst. When a customer's security team asks which IP addresses your mail arrives from so they can allowlist it, "a shared range that may change" is not an answer that survives a procurement review.

SuperSend TX is built around this distinction. Production mail runs on a transactional-only pool carrying paying customers exclusively — no free-tier signups, no marketing campaigns, no cold outbound. When you need genuine isolation, Dedicated provisions your own mail servers and IP addresses, which we build, warm through the full ramp, and operate. The API contract is identical either way, so moving between them is a billing change rather than a migration.