Email Delivery System Design Template

System Design: [Email delivery platform name]

Reference design for a multi-tenant transactional email platform: an API that accepts messages, per-destination queues and SMTP delivery (RFC 5321), sender authentication with SPF (RFC 7208), DKIM (RFC 6376) and DMARC (RFC 9989, May 2026, which obsoletes RFC 7489), IP and domain reputation, bounce and complaint processing, suppression lists and one-click unsubscribe (RFC 8058). It follows the structure of the System Design Document template, adds a 45-minute interview path, access-pattern and failure-mode tables and a cited "How real systems do it" box, and is pre-filled with a worked design to adapt. Replace every [bracketed] value and every row marked Example; values marked Example are assumptions, not benchmarks. Section 2.4 names email marketing laws as dated examples; this is a design format, not legal advice.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Product teams send password resets, receipts and account notices through a shared SMTP relay. Last quarter one tenant imported an old address list, the bounce rate on the shared IPs passed 9% in an hour, and a large mailbox provider deferred all our mail for six hours. Password reset codes arrived after they had expired, support tickets tripled, and nobody could tell which messages had been delivered, bounced or were still queued.]

1.2 Proposed solution

[Example: Tenants send through an HTTPS API that validates, deduplicates and stores each message, then places it on a queue by message class. A scheduler groups messages by destination (mailbox provider and MX host) and releases them at the rate each destination accepts for each sending IP. Delivery agents sign with the tenant's DKIM key and speak SMTP with TLS. Replies are classified into delivered, deferred (retry) and bounced (suppress). Feedback loops and one-click unsubscribe requests update a suppression list that every send checks first. One-time codes use a separate high-priority queue and IP pool with short expiry. Reputation is measured per tenant, per IP and per sending domain, and a tenant that crosses bounce or complaint thresholds is paused automatically before it harms others.]

1.3 Decisions requested from reviewers

1.4 45-minute interview path

Use this order when the document serves an interview or a short design review. The written sections below are the long form of each step.

Start the default deep dive with the naive answer, one FIFO queue and a pool of workers that send as fast as they can. Show what happens when one large provider starts deferring: the workers fill with retries for that provider and a password reset for a different provider waits behind them. Then move to per-destination queues with token-bucket release and per-class priority.

2. Requirements

2.1 Core functional requirements

2.2 Non-functional requirements

2.3 Below the line (out of scope)

Name these explicitly so reviewers and interviewers do not pull the design toward them.

• [Example: campaign builder, audience segmentation and A/B testing (marketing product)]
• [Example: inbound mail receiving and parsing, except bounce and feedback mailboxes]
• [Example: SMS and push fallback (see Notification Service System Design (system-design/design-notification-service))]
• [Example: open and click tracking pixels (off by default; separate privacy review)]
• [Item deferred, with the release that will take it]

2.4 Legal and mailbox provider context (dated examples)

The platform carries mail for tenants, and tenants carry the legal duty for their content and consent. The platform still needs the mechanics that make compliance possible. The rules below are named as dated examples only; check the current official text and a qualified professional before relying on any of them. This is not legal advice.

The design consequence is that unsubscribe, suppression, DKIM alignment and complaint tracking are platform features, not tenant options.

3. Capacity estimation

3.1 Assumptions

3.2 Throughput

The API and queues are sized for the burst $B = 2\,000$ messages/s. Delivery agents have session headroom for the burst (3.3), but destination limits are sized for the peak hour, so a burst above about 1 042 messages/s queues. The reset storm in $B$ is code class mail, which is released first, so NFR-01 holds; other classes behind a burst that lasts more than about a minute can miss NFR-02, which is accepted and tracked as queue age (9.3).

3.3 Concurrent SMTP sessions

By Little's law, sessions in flight equal arrival rate times time in the system:

So a small fleet of delivery agents (for example 8 agents at about 125 sessions each in the burst) is enough; the hard limit is how many sessions each destination accepts per IP, which the scheduler enforces (7.2).

3.4 Storage

The MIME store is object storage with a 3-day lifecycle; the queue holds only message IDs and scheduling state, so a 60 GB backlog is a metadata problem of 1.5 million small rows, not a disk problem.

3.5 IPs and warm-up

Peak-hour mail to the largest provider is $3.75 \times 10^{6} \times 0.4 = 1.5 \times 10^{6}$ messages/h. At the observed $r_{ip} = 50\,000$ messages/h per IP:

Daily, that provider receives $3 \times 10^{7} \times 0.4 = 1.2 \times 10^{7}$ messages, or 400 000 per IP per day across 30 IPs. A new IP that starts at 1 000 messages a day and grows by half each day reaches that level on day 16 (table in 7.5). Consequence: IPs are provisioned and warmed weeks before the volume arrives, and the warm-up plan is part of capacity planning.

3.6 Summary

4. API design

4.1 Endpoints

The Idempotency-Key request header follows the pattern of the IETF draft draft-ietf-httpapi-idempotency-key-header-08 (22 October 2026, an Internet-Draft, not an RFC). A repeated key with the same body returns the original message ID; with a different body it returns 422 with a problem details body (RFC 9457).

4.2 Request example

{"from": {"address": "receipts@mail.shop.example.com", "name": "Example Shop"}, "to": [{"address": "ana@example.net"}], "class": "receipt", "template_id": "order-receipt-v3", "data": {"order_id": "ORD-104233", "total": "49.90"}, "tags": ["orders"], "send_at": null}

Response:

{"message_id": "msg_01J9ZK7Q4R", "status": "accepted", "suppressed": false}

4.3 Headers the platform adds

The platform adds the list headers for subscribed classes and signs them with DKIM, because RFC 8058 requires the DKIM signature to cover both List-Unsubscribe and List-Unsubscribe-Post:

From: Example Shop <news@mail.shop.example.com>
Message-ID: <msg_01J9ZK7Q4R@mail.shop.example.com>
List-Unsubscribe: <https://u.mail.shop.example.com/u/9f2c7d1e>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
DKIM-Signature: v=1; a=rsa-sha256; d=shop.example.com; s=em2026a;
  h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
  bh=[base64 body hash]; b=[base64 signature]

4.4 Delivery events

Events go to the tenant's webhook (signed, retried) and to the event API. Each event carries the message ID, tenant ID, recipient hash, type, timestamp (RFC 3339), and for failures the SMTP reply code and enhanced status code (RFC 3463).

{"event_id": "evt_8812", "message_id": "msg_01J9ZK7Q4R", "type": "bounced", "bounce_type": "permanent", "smtp_code": 550, "enhanced_code": "5.1.1", "occurred_at": "2026-10-30T09:14:03Z"}

5. Data model

5.1 Entities

A message belongs to one tenant and has many delivery attempts; suppressions are scoped to a tenant, plus one global list for hard bounces.

5.2 Storage choices

5.3 Access patterns

6. High-level design

7. Detailed design

The deep dives in this section, each with options, choice and reason:

7.1 Message classes

The class is declared by the tenant and checked: a receipt that is mostly promotion is a known abuse pattern, so content rules and complaint rates per class are monitored (9.2).

7.2 Destination scheduling

Mail is grouped by destination: the recipient domain is resolved to MX hosts and then mapped to a destination group (one large provider owns many domains and MX hosts). Each (class, destination group, sending IP) has a token bucket for messages per hour and a cap on concurrent sessions. The scheduler releases the oldest message whose bucket has a token, highest class first.

When a destination replies with a temporary failure that signals rate pressure, the scheduler halves the bucket rate for that IP and destination and raises it again by 10% every 15 minutes without deferrals (additive increase after multiplicative decrease, as in TCP congestion control). Codes never wait behind receipts, and a destination that defers everything slows only its own queue.

7.3 Retries and bounce classification

RFC 5321 (section 4.5.4.1) says a sender must wait before retrying a destination, that the retry interval should generally be at least 30 minutes, that the give-up time generally needs to be at least 4 to 5 days, and that experience favours two attempts in the first hour and then one every two or three hours. The design follows that for long-lived classes and expires short-lived ones instead of retrying.

Reply classification uses the basic code first and the enhanced status code (RFC 3463) second:

Some providers return 5yz for reputation blocks that are temporary in practice. Treating those as hard bounces would wipe valid addresses, which is why 5.7.x is kept separate.

7.4 Authentication and alignment

DMARC moved from RFC 7489 to RFC 9989 in May 2026. Among the changes, the pct tag is removed (RFC 9989 Appendix A.6), a DNS tree walk replaces the Public Suffix List for finding the organisational domain (section 4.10), and the np tag for non-existent subdomains, first defined in RFC 9091, is now part of the core specification. Review your record parsing and your tenants' DMARC checks against the new text.

Key rotation: each tenant domain has two selectors (for example em2026a and em2026b). The platform publishes the new key under the idle selector, waits for DNS TTL plus a margin, switches signing, and retires the old key after 7 days so mail in retry still verifies.

7.5 Reputation, IP pools and warm-up

Reputation lives at three levels: sending IP, sending domain, and the tenant that causes both. Pools separate classes and tenant tiers:

Automatic controls per tenant over a rolling 24-hour window (Example thresholds; set yours from provider guidance and history):

Warm-up of a new IP (Example: start at 1 000 messages a day and grow by half each day until the 400 000/day target from 3.5; the excess goes through already warm IPs in the same pool):

Send the earliest warm-up volume to the most engaged recipients, watch deferrals per provider, and hold the step (do not grow) on any day with rising 4.7.x deferrals. Complaint feedback loops, where providers offer them, arrive in the Abuse Reporting Format (RFC 5965) and are treated as an unsubscribe for that tenant.

7.6 Suppression and one-click unsubscribe

Every send checks the suppression list before rendering. Entries come from hard bounces (global), complaints, unsubscribes and tenant uploads (tenant scope). Addresses are normalised (lower-case domain; local part kept as is, because RFC 5321 says it may be case-sensitive) and stored as hashes.

One-click unsubscribe follows RFC 8058: the message carries a List-Unsubscribe header with one HTTPS URL and a List-Unsubscribe-Post: List-Unsubscribe=One-Click header, both covered by the DKIM signature. The mail client sends a POST with that key-value body, without cookies or authorisation, and the endpoint must not redirect.

The token in the URL is an opaque, signed reference to (tenant, list, address hash); it never contains the address in clear text, and a replayed token is harmless because the operation is idempotent.

7.7 Duplicates and delivery semantics

SMTP delivery is at-least-once. If the connection drops after the final . of DATA but before the 250 reply arrives, the sender cannot know whether the receiver accepted the message (RFC 1047 describes this window), and a retry may duplicate it. The design reduces duplicates in three places: the idempotency key at accept time, a stable Message-ID across retries so receivers that dedupe can do so, and short SMTP timeouts on the DATA reply balanced against the risk of resending large messages. NFR-05 accepts a small residual rate.

7.8 How real systems do it

How real systems do it (paraphrased, not copied). The Amazon SES Developer Guide page "Warming up dedicated IP addresses (standard)" (checked 2026-10-30) explains that mailbox providers trust IPs with a history of good mail, that warm-up can take from about two to six weeks depending on the provider, and that early volume should go to the most active recipients while bounces and throttling are watched. SES warms new dedicated IPs automatically by splitting a customer's mail between the new IPs and IPs that are already warm (a shared pool for a first dedicated IP, the customer's existing dedicated IPs otherwise), shifting the share over 45 days on a time basis. After warm-up it suggests keeping roughly 1 000 messages a day per provider per IP to hold the reputation, and avoiding sudden jumps. The overflow-to-warm-IPs approach in 7.5 is the same idea. Read the original in 12.3; this box keeps only the general idea.

8. Scalability and performance

Latency budget for the code class (target p99 5 s to first attempt):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security, abuse and privacy

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Move traffic per class and per destination group from the relay to the own fleet in steps of 10%, following the warm-up table. Rollback sends the class back to the relay by configuration within 5 minutes; messages already queued finish on whichever path holds them.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on the IETF specifications cited in 12.3 (RFC 5321, RFC 6376, RFC 7208, RFC 8058 and the DMARC RFCs 9989 to 9991, published May 2026) and on common industry practice for transactional email. The legal and mailbox provider rules in 2.4 are dated examples, not legal advice; check the current official text and a qualified professional. The Amazon SES page is paraphrased in 7.8 only; no text was copied, and all volumes, thresholds and warm-up figures are illustrative examples. Original text written for this collection. Template licence: MIT.