Most email APIs return 202 Accepted and a message ID. That is useful, but it is
also where a lot of confusion starts. A 202 does not mean the message was
delivered. It does not mean the recipient saw it. It does not even mean the
recipient’s mail server knows the message exists.
It means the platform accepted responsibility for the message.
That distinction is the difference between an email API that helps you operate a sending system and one that just moves JSON into a queue.
Three different successes
It helps to separate three events that are often collapsed into the word “sent”:
| Event | What it means | What it does not mean |
|---|---|---|
| Accepted | The platform committed the message and its per-recipient deliveries durably | The remote server has seen it |
| Delivered to MX | A remote mail exchanger returned a 2xx response for the recipient | The message reached the inbox |
| Inbox placement | The receiver’s filters placed the message where the recipient can see it | Anything about future messages |
A 202 belongs to the first row. It should be a promise that a process crash,
a network blip or a deploy will not lose the message. It should not be dressed
up as delivery.
This matters because the failure modes after acceptance are where most deliverability work actually happens: deferrals, retries, hard bounces, complaints, suppression and reputation.
What a 202 should guarantee
A useful acceptance response should be backed by a durable transaction. At minimum:
- The message is stored.
- One delivery record exists per recipient.
- The idempotency key is recorded.
- The outbox event is committed.
- Usage/quota accounting is updated.
Only then should the API return 202. If any of those steps fail, the client
should get an error and be able to retry safely.
Idempotency is part of the same contract. A retry with the same key and the same body should return the original message ID, not create a second send. A retry with the same key and a different body should fail with a conflict rather than silently doing something surprising.
Where accepted mail can still fail
Once the platform owns the message, a lot can happen before a recipient sees it.
Temporary failures
A remote server may return a 4xx response such as:
451 4.7.1 Try again later
That is a deferral, not a bounce. The right response is to back off, retry, and keep the message in the queue until it succeeds or reaches an age limit. The retry schedule should add jitter; synchronized retries from many senders are their own kind of denial-of-service.
Permanent failures
A 5xx response is a hard failure. A 550 5.1.1 for an unknown mailbox usually
means the address should be suppressed. A 550 5.7.1 policy rejection may mean
the message looked abusive, the sending domain is not authenticated, or the
receiver has blocked the IP.
Those are not interchangeable. Treating every 5xx as “bad address” hides infrastructure problems. Treating every 5xx as “retry later” wastes queue space and damages reputation.
Complaints and bounces
Feedback loops and ARF complaints are not delivery failures in the SMTP sense, but they are operational signals. A complaint means a recipient marked the message as spam. A hard bounce means the address is not usable. Both should feed suppression immediately.
Silent filtering
The remote MX can accept the message and the receiver can still put it in spam, quarantine it, or discard it later. No SMTP response tells you that. This is why “delivered” should never be marketed as “inbox.”
Authentication is not deliverability
SPF, DKIM and DMARC answer a narrow question: did this message legitimately come from the domain it claims?
- SPF authorizes sending IPs for the envelope domain.
- DKIM signs the message so receivers can verify it was not altered.
- DMARC tells receivers what to do when SPF or DKIM alignment fails, and gives domain owners aggregate reports.
Authentication is necessary. It is not sufficient. A perfectly authenticated message can still be unwanted, repetitive, poorly segmented or sent from an IP with no reputation.
A useful platform should show you the authentication state and the SMTP outcome separately. “SPF passed” and “the recipient’s MX accepted the message” are different facts, and both are worth recording.
What to measure instead of “sent”
If you want to know whether email is working, track the stages:
- Accepted — did the API commit the message?
- Attempted — did the scheduler try an MX?
- Delivered to MX — did the remote server return 2xx?
- Deferred — how often, and for which provider/reason?
- Bounced — hard or soft, and what enhanced code?
- Complained — feedback-loop and ARF complaints.
- Suppressed — did policy prevent a send?
- Inbox placement — from seed testing or provider tools, if you have it.
The ratios matter more than the raw counts. A 2% bounce rate on a small list can be noise. A 0.3% complaint rate on a large list is a serious signal. Deferrals that cluster around one provider usually mean a throttle or reputation issue, not a code bug.
A practical checklist for evaluating an email API
When you compare providers, ask:
- Does
202mean the message and all recipient deliveries committed in one transaction? - Is there an idempotency key with conflict detection?
- Are retries durable across restarts and deploys?
- Can you see the actual SMTP code, enhanced code and MX host?
- Are bounces classified by source (DSN, ARF, in-band) rather than guessed?
- Is suppression checked at intake and again immediately before submission?
- Can you scope webhooks to specific domains?
- Does the platform distinguish acceptance, delivery to MX and inbox placement?
- Can you export the event history, or is it trapped in a dashboard?
If the answer to the first three is “no,” the rest does not matter much. Those are the properties that keep a sending system from losing mail during normal operations.
Where Transmitly fits
Transmitly is built around the distinction above. A message is accepted only after the message, deliveries, idempotency key, usage ledger and outbox event commit. Delivery events carry the remote response. “Delivered to MX” is reported as exactly that, not as inbox placement.
That is a narrower promise than “we deliver your email.” It is also a more useful one, because it gives you something you can debug.
This is the first post on the Transmitly blog. Future posts will go deeper into authentication, provider throttles, inbound routing and the operational side of running an email system.