Documentation
What a 200 OK tells you.
It tells you the request was accepted. Here is everything that happens after that, and what each stage proves.
200 OK means accepted, not delivered
When you send an email through an API, the answer comes back in milliseconds, long before any recipient's mail server has seen the message. A 200 OK and a message ID mean one thing: the service accepted your request. Whether the message arrives is decided later, by a different system, and email gives the sender very little information about it. Treating the 200 as “delivered” is the most common mistake in email code.
The stages
Every message moves through some of these stages, and Mailtruss records each one as an event with the time it happened.
| Stage | What happened | What it proves |
|---|---|---|
| Accepted | The request was valid: the fields parsed, the from address is on a verified domain, your plan has room, and the message was stored. You get its ID back. | Nothing yet about the recipient. This is the moment the API answers 200. |
| Queued or scheduled | The message is waiting its turn, or waiting for the time you set with scheduled_at. | That it has not been tried yet. |
| Handed off | The message was given to the delivery network, which carries it to the recipient's mail server (the sent event). | That our side finished. The recipient's server has not answered yet. |
| Delivered | The recipient's mail server accepted the message. | That their server took responsibility for it. It does not mean the message reached the inbox: it may have been filtered to spam, and receivers do not report inbox or spam placement back to senders. |
| Delayed | The receiving server could not take the message yet. The delivery network keeps trying for a while (the delivery_delayed event). | That it is not lost, and not delivered either. |
| Bounced | The receiving server refused the message, for good (permanent) or for now (temporary). | That the message did not arrive. The reason is in the status code and the server's own words. |
| Complained | The recipient told their mailbox provider it was spam. | That this person does not want your mail. Never send to them again. |
| Failed or unknown | Something went wrong before or during the hand-off, or the answer was lost. | Unknown means the request timed out and the message may or may not have been accepted: it is not retried, so it cannot be delivered twice. |
What “delivered” does and does not mean
In email, delivered means the receiving server replied with a success code. After that, the message is theirs: their spam filter, their rules, their user's settings decide whether it lands in the inbox, the spam folder or nowhere. No sender can see that, which is why a service that claims to know inbox placement for every recipient is claiming more than it can know. What you can know is whether it was accepted, and, when it was refused, exactly why.
When it does not arrive
A refusal comes with a status code and a sentence from the receiving server. The code's first digit tells you whether to try again (4 is temporary, 5 is permanent), and the rest says why: a mailbox that does not exist, a full mailbox, a policy block, a failed authentication check. Each common case has its own guide: why an email bounced, spam complaints, an unknown outcome.
What to do in your own code
- Store the message ID the API returns. It is how you ask what happened later, and what to quote when you need help.
- Send with an idempotency key, so repeating a request after a timeout can never deliver the message twice. See Idempotency.
- Do not treat the 200 as delivery. Use webhooks to be told about each delivery, bounce and complaint as it happens.
- Act on bounces and complaints: stop sending to addresses that hard-bounce or complain. Mailtruss suppresses them for you, but your own lists should be cleaned too.
Check any message
Open the message under Emails in the dashboard to see its timeline, or ask the API. The events endpoint returns every recorded event with a plain statement of what it proves and, when something went wrong, a diagnosis that says whether a retry is safe and what to do next.
To see every outcome without sending real mail, send to delivered@mailtruss.test, bounced@mailtruss.test, complained@mailtruss.test or suppressed@mailtruss.test. These run through the real pipeline, so the events, the diagnosis and your signed webhooks all fire, but nothing is handed to a mail server and nothing counts toward your plan. See Sending.