Guide
Production-grade email systems
The full, production-oriented guide to building email systems: deliverability, transactional and marketing email design, compliance, reliability, webhooks and list hygiene. Ten chapters that take you from DNS authentication to a system mailbox providers trust.
Email Types: Transactional vs Marketing
The core distinction between mail a user is waiting for and mail you want them to read, plus the legal framing, the hybrid gray area, and how the split shapes your sending infrastructure.
Read chapterTransactional Email Catalog
A practical catalog of transactional emails by category, plus ready-made sets per app type: what to build, when to send and what each email must contain.
Read chapterDeliverability
The four pillars of reaching the inbox: SPF/DKIM/DMARC authentication, sender reputation, bounce & complaint handling, and DNS architecture that protects transactional mail.
Read chapterList Management
Keeping lists clean: suppression lists, automated hygiene, data retention, and separating transactional from marketing streams so you don't erode sender reputation.
Read chapterTransactional Email Design
How to build the mail users expect, clear, fast and action-oriented: subject lines, structure, mobile-first layout, OTP/CTA display and error handling.
Read chapterEmail Capture
Collecting addresses responsibly: client- and server-side validation, double opt-in verification, dark-pattern-free form design and proper consent capture.
Read chapterMarketing Emails
Running a consent-based program: how to collect opt-in, make unsubscribing painless, design valuable messages and keep the list healthy so mail keeps landing.
Read chapterCompliance
A summary of the key regimes (CAN-SPAM, GDPR, CASL and others): unsubscribe rules, consent records and the technical headers now required of bulk senders.
Read chapterSending Reliability
Sending as a distributed-systems problem: idempotency (no duplicates), retry with backoff, error-code handling and queuing decoupled from the request path.
Read chapterWebhooks & Events
The other half of the email story: event types, signature verification, non-negotiable idempotent processing, and reacting to bounces and complaints to keep suppression accurate.
Read chapterHow to use this guide
Four reading paths depending on where you are. Pick the one that matches your situation.
New app
Start with chapters 01 and 02 (which emails you need), then 03 (DNS authentication) before your first send.
Spam issues
Go straight to chapter 03 (Deliverability). The most common cause is gaps in authentication.
Marketing
Follow 06 (Email Capture) → 08 (Compliance) → 07 (Marketing Emails).
Production-ready
Work through 09 (Sending Reliability) → 10 (Webhooks & Events) → 04 (List Management).
Email system architecture
How the pieces fit together, from capture and consent through idempotent sending to webhook-driven list hygiene.
System architecture
List-hygiene loopCapture & consent
An address joins the list only after confirmation
Sending
Suppression is the gate before every send
Webhook events
The provider reports what happened to each email
List hygiene
Bounces and complaints update the suppression list
The feedback loop
The updated suppression list (stage 4) flows back into the suppression check (stage 2), blocking future sends to bounced and complained addresses. This is how webhook events keep the list healthy.
Every question this guide answers
Browse the full contents and jump straight to the answer you need.
Email Types: Transactional vs Marketing
- What is the difference between a transactional and a marketing email?
- Why does the transactional/marketing split matter so much?
- How do I tell which type an email is?
- What do the laws require for each type?
- When should I use each type?
- What about gray-area emails that feel like both?
- Which transactional emails does my app actually need?
- Why do I need separate subdomains for transactional and marketing?
- Subdomains, streams, and IP pools, what is actually being separated?
- Copy-paste DNS for two clean sending subdomains
- Verifying the setup with dig
- Optional but recommended: hardening beyond SPF/DKIM/DMARC
- What should I look for in an email service?
- What does a clean transactional send look like in code?
- What does a compliant marketing send look like in code?
- What is the implementation checklist?
- What are the most common mistakes to avoid?
- What should I read next?
Transactional Email Catalog
- How do I use this chapter?
- Which transactional emails does my app need?
- What does an authentication-focused app need?
- What does a newsletter or content platform need?
- What does an e-commerce or marketplace app need?
- What does a SaaS or subscription service need?
- What does a financial or fintech app need?
- What does a social or community platform need?
- What does a developer tools or API platform need?
- What does a healthcare or HIPAA-compliant app need?
- How do the essential sets compare at a glance?
- How critical is each email, and what does that imply for engineering?
- Full Email Catalog
- Authentication and security emails
- When and how do I send an email verification?
- What goes into an OTP / 2FA code email?
- What does a password reset email need?
- When should I send a security alert?
- Account management emails
- What should the welcome email contain?
- When do I send account update notifications?
- E-commerce and transaction emails
- What goes into an order confirmation?
- When do I send shipping notifications?
- What does an invoice or receipt email need?
- Subscription and billing emails
- What does a subscription confirmation need?
- When do I send a subscription renewal notice?
- How should I handle a payment failed notice?
- Notification and update emails
- When is a feature announcement transactional, not marketing?
- What about activity, mention, and digest notifications?
- Cross-cutting requirements for every email in this catalog
- Implementation checklist
- What should I read next?
Deliverability
- Why does my email go to spam instead of the inbox?
- Why is email authentication now non-negotiable?
- What is SPF and why do I need it?
- What is DKIM and how is it different from SPF?
- What is DMARC and what does "alignment" mean?
- DMARCbis (RFC 9989): what the latest standard changes
- How do I verify my SPF, DKIM, and DMARC setup?
- What is sender reputation and why does it matter?
- How do I warm a new IP or domain?
- How do I keep my reputation healthy once it is built?
- What is a bounce, and how should I handle hard versus soft bounces?
- What is a complaint, and what complaint rate is too high?
- What did the Gmail/Yahoo/Microsoft 2024 bulk-sender rules actually require?
- BIMI: showing your logo in the inbox
- ARC: surviving forwarding and mailing lists
- MTA-STS and TLS-RPT: enforcing transport encryption
- How should I structure my sending domains and subdomains?
- What DNS TTL should I use for email records?
- My emails are going to spam: what do I check, and in what order?
- What should I read next?
List Management
- What is a suppression list and why do I need one?
- Which addresses should I suppress, and which can I ever bring back?
- How do I store suppression entries in my database?
- How do I check suppression before every send?
- What is list hygiene and how is it different from suppression?
- How often should I run each cleanup task?
- Should I delete inactive subscribers or try to win them back first?
- How long should I keep each kind of email data?
- How do I implement a retention policy in code?
- Which metrics tell me my list is going bad?
- Should transactional and marketing lists be separate?
- What does a complete list-management checklist look like?
- What should I read next?
Transactional Email Design
- Why do transactional emails matter so much?
- What are the core principles for designing transactional emails?
- How should I write the subject line?
- What is the pre-header and how do I use it?
- How should I structure the body of the email?
- Why does mobile-first design matter, and how do I do it?
- How should I make transactional email accessible?
- What should the From, Reply-To, and sender fields be?
- How should I display OTP codes and action links?
- How do I send the email correctly from the backend?
- How do I handle the things that go wrong?
- How do I test a transactional template before it ships?
- Is there one checklist I can run before sending?
- What should I read next?
Email Capture
- Why capture is the highest-leverage point in the whole system
- How do I validate an email address?
- What is double opt-in?
- What does the double opt-in process look like?
- How do I generate and verify the token securely?
- What timing rules should the verification step follow?
- When should I use single opt-in instead of double opt-in?
- A decision table for which to use
- Why is double opt-in worth the friction?
- What happens to addresses that never confirm?
- How do I defend against subscription-bombing through my form?
- Double opt-in checklist
- How do I design a capture form that converts?
- How should the email input field behave?
- How do I collect valid marketing consent with checkboxes?
- What dark patterns must a consent form avoid?
- What consent metadata must I capture and store?
- How should the form be laid out?
- How do I stop bots without hurting real users?
- What are common form-design mistakes?
- Form design checklist
- How do I handle capture errors and abuse?
- What should I do when the email is invalid?
- How typo suggestion works
- What should I show when the email is already registered?
- Resubscribe and the re-consent case
- How do I rate-limit the form to stop abuse?
- A layered rate-limit design
- How do I distinguish a real bounce from an abuse signal after capture?
- Error-handling checklist
- How do I design a verification email people actually click?
- Common mistakes across the whole capture flow
- What should I read next?
Marketing Emails
- What is a marketing email, and how is it different from a transactional email?
- What are the core principles I should never break?
- What counts as valid consent, and what does not?
- How easy does my unsubscribe have to be?
- How do I write subject lines that get opened?
- How should I structure a marketing email?
- How do I make my emails work on mobile?
- How should I segment my list?
- How do I personalize without being creepy?
- How often and when should I send?
- How do I keep my list clean?
- What must every marketing email contain?
- What should I read next?
Compliance
- How compliance, deliverability, and authentication overlap
- Which laws apply to my email program?
- What does CAN-SPAM require in the US?
- What does GDPR require in the EU?
- What does CASL require in Canada?
- What about Australia, the UK, Brazil, and elsewhere?
- How fast must I process unsubscribes, and how long must the link work?
- Do I really need a List-Unsubscribe header?
- How do I implement RFC 8058 one-click unsubscribe correctly?
- What are the February 2024 (and May 2025) bulk-sender requirements?
- Can a preference center replace a one-click unsubscribe?
- What consent records must I keep?
- How long can I keep subscriber data?
- How do I handle data-subject requests (access, deletion, portability)?
- What must my privacy policy say?
- How do I stay compliant when sending across borders?
- What should I read next?
Sending Reliability
- Why does email need reliability engineering at all?
- How do I make sure I never send the same email twice?
- What exactly goes wrong without idempotency?
- How does an idempotency key work?
- What happens on the server side when a key repeats?
- How should I generate the key?
- Worked example: deriving a stable key from an event
- What is a common idempotency mistake to avoid?
- How long does an idempotency key stay valid?
- Idempotency checklist
- When should I retry a failed send?
- How do I react correctly to each kind of error?
- When do I need a queue instead of sending inline?
- How do I stay within provider rate limits and warm up sending?
- What about authentication, unsubscribe, and bulk-sender rules?
- What timeout should I set on an email API call?
- How do all of these fit together in one send?
- What should I read next?
Webhooks & Events
- What is a webhook, and why does my email system need one?
- Which event types will I receive?
- How do I set up a webhook endpoint correctly?
- How do I process each event type?
- How do I handle a bounce?
- What counts as a hard bounce versus a soft bounce?
- Read the SMTP enhanced status code, not just hard/soft
- A common mistake: mis-bucketing "mailbox full"
- How do I handle a complaint?
- Complaints arrive late and sometimes anonymized
- How do I handle a delivery confirmation?
- Beware out-of-order delivery
- Why does my webhook handler have to be idempotent?
- What happens when my endpoint returns an error?
- How do I test webhooks before going live?
- Should I store the full webhook history, or just the latest status?
- What should I read next?