An email did not arrive: how to find out why

"The customer says they received nothing." It is the most frequent support message, and the answer is rarely "Duva did not send it". Most of the time, the email was sent, then refused, delayed or filed elsewhere by the recipient's server. This article shows you how to find out what happened, and how not to confuse the three cases.

First, a principle: a sending service accepts your email, then hands it to the recipient's server. It is that server that accepts, files or rejects it. No service controls the inbox, the spam filter or the delays, and none can promise that an email will arrive. What you can do is read what the recipient's server answered.

Step 1: find the message

Every send through the API returns an identifier (msg_...). Keep it in your database, next to the order or the user concerned: it is the fastest way to answer a complaint. You can also add metadata to the send (an order number, for example), which comes back in events and webhooks.

Without an identifier, search for the message by recipient in the dashboard, or read the domain's event log.

Step 2: read the recipient's status

GET /v1/{domain}/messages/{id} gives the status of the message and of each of its recipients. A message is sent as one copy per recipient, and each has its own status:

A recipient never moves back a status. One exception: a bounce received after the fact can follow a delivered. Some servers accept the message, then send it back later as undeliverable.

Step 3: read the events

GET /v1/{domain}/events gives the detailed log. The types useful for a diagnosis:

• deferred: temporary failure. The sending server will retry. Several deferred events can precede the final event.
• expired: the sending server gave up after 24 hours of attempts.
• bounced: permanent refusal.
• complained: the person reported the message as spam.
• delivered: accepted by the recipient's server.

Bounce events carry the server's response code (for example 550 and an enhanced code such as 5.1.1) and the first line of its response. It is the best information in the diagnosis. Treat that text as external data: never interpret it as code or as HTML.

Reading a bounce code

The enhanced code (of the form 5.x.y) says why. The most common:

• 5.1.1, "mailbox does not exist": the address does not exist or has a typo. Fix it; stop writing to that address.
• 5.2.2, "mailbox full": the person cannot receive for the moment. Another try later may go through.
• 5.7.x, "refused for policy reasons": the server refuses the sender or the content, not the mailbox. It is often tied to authentication (SPF, DKIM, DMARC), the sender's reputation or the content. Read the text of the response; it often names the cause.
• 4.x.x: temporary. The server will retry; you have nothing to do.

A repeated 5.7.x across several recipients of the same provider (for example, all your messages to the same email service) points to your domain's authentication or to reputation, not to the addresses. Check your configuration first: see SPF, DKIM and DMARC: setting up a sending domain.

Delivered, but not received

delivered means the recipient's server accepted the message. It does not say where it filed it: inbox, "promotions" tab, spam folder, corporate quarantine, or a rule set by the person. It is not a measure of "inbox placement".

When a message is delivered and the person cannot find it:

1. Ask them to check the spam folder and the secondary tabs.
2. If it is a corporate address, there may be a quarantine managed by an administrator.
3. Check the subject and the content: an email that looks like a promotion or phishing is filed as such.
4. Send yourself the same message at a personal address with a large provider, and see what happens. "Show original" displays the SPF, DKIM and DMARC results.
5. If the message is transactional, avoid promotional phrasing in the subject ("Free!", "Limited offer") and images without text.

Suppressed

A suppressed recipient never received the message: Duva does not send to an address on the domain's suppression list, and it does not use up any quota. An address gets there after a bounce caused by the address itself (unknown recipient, 5.1.x), after a complaint, or because you added it. A reputation or content block (5.7.x) does not add the address.

Before removing it, ask yourself why it is there. Sending to an address that bounced or complained raises your bounce and complaint rates, which hurts your domain's reputation. Remove it only if you have reason to believe the problem is solved (the person fixed their mailbox, for example).

A message that stays in the queue

A queued message is normally sent within moments. Two situations can keep it longer:

• An unusual volume. A recent account that sends a lot, or a rate far above its habit, can cause a message to be held for review before it is sent. The API response is the same, and the message stays queued until a decision is made. A message that has not been released within 24 hours is abandoned (failed). To avoid it, ramp up volume gradually or write to us before a large send.
• Your plan's limits. Beyond a limit, sends are refused with a clear error.

Complaints: the signal to watch

A complained event means the person clicked "spam". The large providers watch that rate closely. Gmail, for example, asks you to keep the reported spam rate below 0.3% in its Postmaster tools. If you see complaints on transactional emails, it is almost always because the person did not expect that message: check who is subscribed to what, and do not mix promotion with transactional emails.

Duva's terms of use publish the complaint and bounce thresholds at which an account receives an alert, then a suspension.

When to contact support

Write to us (or to your provider) with:

• the message identifier (msg_...) and the approximate time;
• the recipient's status and the bounce code read in the events;
• what you have already checked (DNS, address, spam folder).

With those three elements, we almost always find the cause, or we know exactly who must act: you, the recipient, or their email provider.