Test your project's emails before launch: a checklist

The emails a project sends are easy to forget until a real user complains. The sign-up link opens the staging site, the password reset works twice, the receipt shows the wrong time. None of this shows up in unit tests, because the bug is in the letter a person actually receives.

This guide walks through what to check in each kind of email, using a fake mail generator on a domain you control. Point a subdomain such as test.example.com at this site, and every address on it becomes a mailbox you can open in the browser: signup-01@test.example.com, reset-02@test.example.com, and so on. You do not create them first. The setup takes one DNS record and is described in Use your own domain in three steps.

Your app sends a letter to an address on test.example.com; the MX record of the subdomain points to this site; the letter appears in the mailbox page in your browser.
One MX record on a test subdomain, and every address on it opens here.

Why test on your own domain at all

You can test with random addresses on our domains, and for a quick look that is fine. A domain of your own helps in three ways:

Pick a naming scheme before you start

Since any name works, it is tempting to type whatever comes to mind. A short scheme pays off as soon as there are more than a handful of letters:

PartExampleWhat it tells you
flowsignup, reset, orderwhich email you were testing
date or build1119, b482which run or release it belongs to
casea, b, expiredwhich variant of the test

Put together, you get reset-1119-expired@test.example.com. Use a fresh address for every case. If two tests share an address, you will not know which letter belongs to which.

Sign-up confirmation

Password reset

Reset letters carry the most risk, so they deserve the most cases:

Changing the email address

Open two mailboxes, an old one and a new one, for example change-old@ and change-new@. A careful project sends a confirmation to the new address and a notice to the old one, so the owner learns if someone else made the change. Check both mailboxes.

Receipts, invoices and attachments

What the letter looks like

Keep the test practical

A few habits make the work faster:

What not to do

Before you go live

If the test subdomain will never carry real mail, you can leave its MX record in place for the next release. If you tested on the domain your users will actually write to, put your real mail server's MX record back before launch. Until you do, mail meant for you arrives in public mailboxes here. If you plan to retire the test domain one day, read When your domain expires first.

Test letters that never arrive at all are a separate problem, and the cause is usually on the sending side. See Your app's test emails are not arriving: check the sending side.

← Back to all guides