Documentation
Delivery errors.
A 200 OK means Mailtruss accepted your request, not that the message arrived. This is what can happen next, and what to do about each case.
Two kinds of failure
An API error means the request was refused before anything was sent: a bad field, a missing key, a limit reached. Those are listed with their fixes in the API reference. A delivery problem means the request was accepted and the message then failed on its way to the inbox. Every message's page in the dashboard shows what happened and, for the cases below, a plain-language diagnosis and whether a retry is safe.
Delivery problems
- BouncesThe receiving server refused the message: the address does not exist, the mailbox is full, the receiver blocked you. Includes every status code Mailtruss recognises.
- Spam complaintsThe recipient reported the message as spam. The address is suppressed and must not be mailed again.
- Rate limits and quotas429 rate_limit_exceeded, the daily cap, the monthly limit, and throttling of bursts.
The sending domain is not verified
If the sender's domain has not completed verification, the message is refused. The API answers 403 domain_not_verified when it knows up front; the delivery network can also refuse it later. Publish the DKIM, SPF and return-path records the domain's page shows, re-check the domain, and retry once it shows Verified. A retry is safe. See Domains, and the full guide to domain_not_verified.
The message is too large
The encoded message is bigger than the 40 MB limit. It is rejected and the error recorded. Remove or shrink attachments, or link to hosted files. A retry as is will fail the same way.
The outcome is unknown
If the request to the delivery network times out after it may already have accepted the message, the message is marked Unknown. Mailtruss does not retry it automatically, because that could deliver it twice. Check whether the recipient received it, and send again by hand only if it did not arrive. Using an idempotency key on your own requests keeps your side safe in the same way: see Idempotency. The full guide to an unknown outcome says how to check.
Related: webhooks tell your code about each outcome as it happens, and send email by language shows how to handle errors in your own language.