Your app's test emails are not arriving: check the sending side

You point a test subdomain at this site, open signup-01@test.example.com, trigger the sign-up in your app, and the mailbox stays empty. It is tempting to blame the mailbox. Usually the letter never left your side, or it left and was stopped on the way.

A letter from an app passes through five places before it shows up on the page. This guide goes through them in order, starting with a two-minute test that tells you which half of the path to look at.

Five stages a test email passes: your app, the mail setting of the environment, the mail provider, the DNS lookup of the recipient domain, and the mailbox page. Each stage has a check mark or a question mark.
Five places a test email can stop. Check them left to right.

First: send one letter by hand

From your ordinary mailbox (Gmail, Outlook, a work account), send a short letter to the same address your app was supposed to write to. Keep the mailbox page open.

Step 1. Did the app actually send anything?

Many "missing" emails were never sent at all. Look for the line in your application log that says a letter was sent. If there is no such line, one of these is likely:

Step 2. Where does this environment send mail?

Most frameworks let each environment choose what "send" means. On development and test servers it often means something other than delivery:

Check the mail settings of the exact environment you are testing, not the ones on your own machine. They often differ.

Step 3. What does the mail provider say?

If your app hands letters to a mail provider, the provider keeps a delivery log. It is the single most useful place in this whole guide: it records whether the letter was accepted, delivered, delayed, bounced or dropped, usually with the reply of the receiving server.

What the log showsWhat it usually means
no entry at allthe letter never reached the provider — go back to steps 1 and 2
suppressed or droppedthe provider refused to send to this address, often because an earlier attempt bounced
deferred or delayedthe receiving side could not be reached yet; the provider will retry for a while
bouncedthe receiving server refused the letter; the reason is in the bounce message
deliveredthe letter was handed over; check that the address in the log is the one you opened

Two provider situations catch new projects again and again:

Step 4. Can the sending server find your domain?

A sending server looks up the MX record of the recipient domain. If you added the record a few minutes ago, the change may not have reached the DNS server your provider asks. DNS servers can also keep a "no such record" answer for a while. The provider then delays the letter and tries again later, sometimes for hours.

If the letter you sent by hand arrived, the record is fine and a short wait usually solves it. If it did not arrive, recheck the record itself: type MX, the right host, and the mail server spelled exactly as in the setup guide. The most common slip is typing the subdomain twice, which creates a record for the wrong name.

You can check the record yourself. In a terminal, run nslookup -type=mx test.example.com (or dig MX test.example.com) and look for the mail server named in the setup guide. No answer means the record is not visible yet, or sits under a different name.

Step 5. Are you looking at the right mailbox?

It sounds obvious, yet it explains a fair share of "lost" letters:

A quick order to remember

  1. Send a letter by hand. If it arrives, continue with the next step; if not, go to the last one.
  2. Find the "sent" line in the app log.
  3. Check the mail setting of that environment.
  4. Read the provider's delivery log, including the suppression list.
  5. Recheck the MX record, then the exact address.

Once letters arrive, the next job is checking what is inside them: links, expiry, time zones and attachments. That is covered in Test your project's emails before launch: a checklist.

← Back to all guides