DEV Community: Thanh Ho Van

Receive email OTP codes in Playwright tests without mocking

Thanh Ho Van — Thu, 08 Oct 2026 08:46:00 +0000

Most sign-up flows send an email at some point. A six-digit code, a "confirm your address" link, a magic login link. And most end-to-end suites quietly skip that step: they stub the mailer, read the code from the database, or add a test-only backdoor that marks the user as verified.

That works until it doesn't. A mock won't notice that the template lost the code during a refactor, that the link points at localhost in staging, or that a config change means the email never goes out at all. Those are exactly the bugs users hit first.

This post shows a setup where the test reads the email your app actually sent. No mocks, no database peeking, and no sleep(10000).

The idea

Point a domain you control at a catch-all inbox, so any address at that domain receives mail.
Generate a new address for every test run, like signup-1728000000000@yourdomain.com.
Let the app send its normal email through its normal provider.
Ask an API for the code at that address, and have the request wait until the email arrives.

I'll use Free Domain Mail for steps 1 and 4 because that's the service I build (disclosure at the end). The patterns apply to any inbox API with long-polling.

Setup: a catch-all domain and an API key

Add a domain you own as a custom domain, publish the TXT ownership record (host _maildock-verify), and set its MX record to mx.freedomainmail.com with priority 10. After that, every address at the domain receives mail. There is nothing to create per test, which is the whole point.

Use a domain or subdomain that doesn't already receive mail you care about, since changing MX moves all of its mail. A spare domain or something like qa.yourcompany.com works well.

Then create an API key and store it as a CI secret:

FDM_API_KEY=your-api-key

Every request sends it as Authorization: Bearer <key>. The key only reads domains connected to its own account.

Playwright: wait for the code

GET /api/v1/code takes the address and a wait value in seconds (up to 60). The request stays open until a message arrives at that address, then returns the extracted code along with message_id, from, subject and received_at. If nothing arrives within wait, you get a 404, so always check res.ok before reading the body.

// tests/email.ts
const API = "https://freedomainmail.com/api/v1";

function authHeaders() {
  const key = process.env.FDM_API_KEY;
  if (!key) throw new Error("FDM_API_KEY is not set");
  return { Authorization: `Bearer ${key}` };
}

export function newAddress(prefix = "signup") {
  const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
  return `${prefix}-${id}@yourdomain.com`;
}

export async function waitForCode(address: string): Promise<string> {
  const params = new URLSearchParams({ address, wait: "60" });
  const res = await fetch(`${API}/code?${params}`, { headers: authHeaders() });
  if (!res.ok) throw new Error(`No code for ${address}: HTTP ${res.status}`);
  const { code } = await res.json();
  return code;
}

And the test:

// tests/signup.spec.ts
import { test, expect } from "@playwright/test";
import { newAddress, waitForCode } from "./email";

test("sign up with an email code", async ({ page }) => {
  // The default test timeout (30s) is shorter than a 60s wait.
  test.setTimeout(120_000);

  const address = newAddress();

  await page.goto("https://your-app.example/signup");
  await page.getByLabel("Email").fill(address);
  await page.getByRole("button", { name: "Send code" }).click();

  const code = await waitForCode(address);

  await page.getByLabel("Verification code").fill(code);
  await page.getByRole("button", { name: "Verify" }).click();
  await expect(page.getByText("Welcome")).toBeVisible();
});

Two details matter here. First, test.setTimeout(120_000) is longer than the 60-second wait. If your test timeout is shorter than the wait, Playwright kills the test before the API has had its chance to answer, and you get a confusing timeout instead of a clear "no code" error. Second, the address is unique per run, which I'll come back to in the flakiness section.

When the email has other numbers in it

By default the API detects the code on its own, which is fine for most templates. But if your email says something like "Order 48213. Your code is 912044. Expires in 10 minutes," you want to be explicit.

Pass pattern with the literal text around the code and exactly one placeholder: {code} for any code, or {digits} when it's digits only. The pattern needs some literal text besides the placeholder. Build the query with URLSearchParams so the braces and spaces get encoded:

export async function waitForExactCode(address: string): Promise<string> {
  const params = new URLSearchParams({
    address,
    wait: "60",
    pattern: "Your code is {digits}",
  });
  const res = await fetch(`${API}/code?${params}`, { headers: authHeaders() });
  if (!res.ok) throw new Error(`No code for ${address}: HTTP ${res.status}`);
  const { code } = await res.json();
  return code;
}

If your app sends more than one kind of email to the same address, you can also narrow by from or subject.

Magic links

For "click to log in" or "confirm your email" links, use GET /api/v1/links with the same address and wait. It returns primary, the main verification link, plus links with the other verification links it found.

export async function waitForLink(address: string): Promise<string> {
  const params = new URLSearchParams({ address, wait: "60" });
  const res = await fetch(`${API}/links?${params}`, { headers: authHeaders() });
  if (!res.ok) throw new Error(`No link for ${address}: HTTP ${res.status}`);
  const { primary } = await res.json();
  return primary;
}

test("log in with a magic link", async ({ page }) => {
  test.setTimeout(120_000);
  const address = newAddress("login");

  await page.goto("https://your-app.example/login");
  await page.getByLabel("Email").fill(address);
  await page.getByRole("button", { name: "Email me a link" }).click();

  await page.goto(await waitForLink(address));
  await expect(page.getByText("Signed in")).toBeVisible();
});

If you need to assert on the whole email (subject line, a footer, the sender), /api/v1/messages lists and reads full messages.

Cypress variant

In Cypress, cy.request does the same job. Set its timeout above the 60-second wait so Cypress doesn't give up first. cy.request already fails the test on a non-2xx response, so a 404 for a missing email shows up as a clear failure without extra code.

// cypress/e2e/signup.cy.js
it("signs up with an email code", () => {
  const address = `signup-${Date.now()}@yourdomain.com`;

  cy.visit("/signup");
  cy.get("input[name=email]").type(address);
  cy.contains("button", "Send code").click();

  cy.request({
    url: "https://freedomainmail.com/api/v1/code",
    qs: { address, wait: 60 },
    headers: { Authorization: `Bearer ${Cypress.env("FDM_API_KEY")}` },
    timeout: 70000,
  })
    .its("body.code")
    .then((code) => {
      cy.get("input[name=code]").type(code);
    });

  cy.contains("button", "Verify").click();
});

Pass the key in with CYPRESS_FDM_API_KEY=... in CI, or in cypress.env.json locally (and keep that file out of git).

Keeping it from getting flaky

Email tests have a reputation for flakiness. Most of it comes from a few habits that are easy to avoid.

Use a unique address per run. The API returns the newest matching message for an address. If every run uses test@yourdomain.com, a retry can pick up the code from the previous attempt, which is already expired. A timestamp plus a short random suffix is enough. If you really must reuse an address, pass since with the time the test started (ISO 8601 or Unix time) so older messages are ignored.

Wait, don't sleep. A fixed sleep is wrong in both directions: too short when your email provider is slow, wasted time when it's fast. A long-poll returns the moment the email lands.

Keep timeouts larger than the wait. Test timeout, cy.request timeout and any HTTP client timeout should all be above 60 seconds if you use wait=60. Otherwise your tooling fails before the API does.

Limit parallel email tests. Each key allows 60 requests per minute, and a single long-poll covers one email, so you don't need to poll in a loop. A key can also hold only a few waiting requests at the same time; extra concurrent waits get HTTP 429. If you run a big parallel suite, put the email tests in their own project with fewer workers, or tag them and run them serially:

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  projects: [
    { name: "default", testIgnore: /email\/.*\.spec\.ts/ },
    { name: "email", testMatch: /email\/.*\.spec\.ts/, fullyParallel: false },
  ],
});

Then run that project with a small worker count, for example npx playwright test --project=email --workers=2.

Treat a 404 as a real failure. When the wait expires with nothing, the useful question is "did the app send the email?" That's a bug you want the test to catch, not retry around.

What this doesn't cover

The inbox is receive-only. It won't send or forward mail, so it's for verifying what your app sends, not for testing replies. And the API reads only custom domains you've connected, not the public temp mail addresses on the homepage.

API reference: freedomainmail.com/docs/api. There's also a longer walkthrough of how catch-all works: catch-all email guide.

If you test OTP flows a different way, I'd like to hear how in the comments.

Disclosure: I build Free Domain Mail – Temp Mail, the service used in this post.

How to Set Up Custom-Domain Email with SPF, DKIM, and DMARC

Thanh Ho Van — Thu, 10 Sep 2026 08:16:47 +0000

Setting up email on a domain you own is mostly a DNS task. The confusing part is that several records solve different problems: receiving mail, proving domain ownership, authorizing senders, signing messages, and publishing an anti-spoofing policy.

This guide explains the five record groups used by Free Domain Mail, a lightweight browser-based mailbox service for freelancers, developers, solo founders, personal projects, and small teams with low email volume.

What you need before starting

You need:

A domain that you own
Access to its authoritative DNS provider
A Free Domain Mail account
A few minutes for DNS caches to refresh

You do not need to transfer your domain or operate your own mail server.

1. Verify domain ownership with TXT

The first TXT record proves that you control the domain. Its value is generated specifically for your setup.

Add the exact host and value shown in the setup screen. Do not remove unrelated TXT records already used for site verification or other services.

After publishing the record, run the verification check again. DNS propagation may be fast, but some providers and resolvers cache results longer.

2. Route incoming email with MX

An MX record tells other mail systems where messages for your domain should be delivered.

Before changing MX, review any existing records. Replacing the current MX records will change where new mail is delivered. If the domain already uses another email provider, plan the migration instead of editing records blindly.

The priority number matters when multiple MX records exist: a lower number normally has higher priority.

3. Authorize sending with SPF

SPF is a TXT policy that lists the services allowed to send mail for the domain.

A domain should normally publish one SPF record. If one already exists, merge the required authorization into the existing policy. Publishing two independent records beginning with v=spf1 can cause SPF evaluation errors.

SPF helps receiving systems detect unauthorized infrastructure, but it does not cryptographically sign the message.

4. Authenticate messages with DKIM

DKIM adds a cryptographic signature to outgoing messages. Receiving systems use DNS to obtain the public key and verify that the signed parts of the message were not altered.

Free Domain Mail displays the required DKIM CNAME records during setup. Copy each hostname and target exactly. Some DNS dashboards automatically append the domain name, so check the final public record if verification fails.

5. Publish a DMARC policy

DMARC connects SPF and DKIM results to the domain visible in the From address. It also tells receivers what to do when authentication fails.

A cautious starting policy is often:

v=DMARC1; p=none; rua=mailto:dmarc@example.com

Replace the reporting address with a mailbox you control. A monitoring policy does not directly reject mail. Move toward quarantine or reject only after reviewing legitimate sending sources and alignment.

Verify the public result

After saving all records, check what the public DNS actually returns—not only what the provider dashboard displays.

The free DNS Checker inspects MX, SPF, DMARC, A, AAAA, and nameserver records. You can also follow the complete five-step setup guide.

Common causes of failed verification include:

Checking before caches have refreshed
Adding the full domain twice in the hostname field
Publishing multiple SPF records
Leaving an old MX record active
Copying whitespace or punctuation incorrectly
Editing DNS at a provider that is not authoritative for the domain

What Free Domain Mail currently provides

Free Domain Mail is currently a free beta with a simple webmail interface. It stores received and sent messages and supports reading, composing, replying, manual forwarding, archiving, spam marking, and deletion.

Current free limits include up to three mailboxes per domain, five sent messages per domain per day, and ten received messages per domain per day. No credit card is required.

It is designed for low-volume personal and small-business use. It does not currently provide IMAP, SMTP/POP3 client access, aliases, catch-all addresses, shared mailboxes, automatic forwarding, mobile apps, attachments, or bulk sending. Sending availability is also subject to Amazon SES service restrictions.

These limits are intentional: the product focuses on guided DNS setup, a minimal browser inbox, and strong anti-abuse controls—not marketing campaigns or cold outreach.

Final checklist

Before creating your first mailbox, confirm that:

Domain ownership TXT passes
MX points to the intended inbound service
Only one valid SPF policy is published
Every DKIM CNAME resolves correctly
DMARC exists at _dmarc.yourdomain.com
Existing website A, AAAA, and CNAME records remain unchanged

Once all five record groups pass, the domain is ready for a custom-domain web mailbox.

Have you encountered a DNS-provider-specific issue while configuring email authentication? Share the provider and the symptom in the comments—without posting private tokens or account credentials.

How to Set Up SPF, DKIM and DMARC for a Custom Domain

Thanh Ho Van — Wed, 09 Sep 2026 07:03:32 +0000

Email authentication can look like a collection of unrelated DNS records. In practice, each record answers a different question:

SPF: Which servers may send mail for this domain?
DKIM: Was this message signed by an authorized sender, and did it change in transit?
DMARC: Does the visible From domain align with SPF or DKIM, and what should receivers do when authentication fails?

This guide shows a safe, provider-neutral setup sequence for a custom domain.

The DNS values below are examples. Always copy the actual hostnames, selectors, and targets supplied by your email provider.

Before changing DNS

Confirm three things first:

You control the domain's authoritative DNS zone.
You know every service that currently sends mail for the domain.
You have saved a copy of the existing MX and TXT records.

Do not delete website A, AAAA, or CNAME records while configuring email. Email DNS and website DNS normally coexist.

You can inspect the records currently visible on the public internet with the Free Domain Mail DNS Checker.

Step 1: Configure MX for incoming mail

MX records tell other mail systems where to deliver messages addressed to your domain.

A simplified example looks like this:

Type: MX
Name: @
Priority: 10
Value: inbound.mail-provider.example

The @ symbol usually means the root domain, but DNS dashboards differ. Some expect a blank name, while others expect the complete domain.

Important rules:

Use the exact MX destination supplied by the receiving provider.
Lower priority numbers are tried first.
Remove an old MX record only when you intentionally stop using the old receiver.
Do not point MX to an ordinary website IP address.
If you use Cloudflare, mail hostnames generally need to remain DNS only.

MX controls receiving. It does not authorize outgoing mail.

Step 2: Publish one SPF policy

SPF is stored as a TXT record. It lists the infrastructure allowed to send using a particular envelope domain.

Example:

Type: TXT
Name: @
Value: v=spf1 include:spf.mail-provider.example -all

The most common SPF mistake is publishing two records such as:

v=spf1 include:service-a.example -all
v=spf1 include:service-b.example -all

That does not create two valid policies. It normally produces an SPF permanent error. Combine legitimate senders into a single record instead:

v=spf1 include:service-a.example include:service-b.example -all

Also remember:

SPF has a DNS-lookup limit.
An include authorizes another provider's policy; it is not a redirect.
~all is a soft-fail qualifier and -all is a hard-fail qualifier.
Changing to -all before identifying every sender may break legitimate mail.
SPF alone may not satisfy DMARC when the authenticated envelope domain does not align with the visible From domain.

Step 3: Enable DKIM signing

DKIM adds a cryptographic signature to outgoing messages. The sending service holds the private key, while DNS publishes the public key or a CNAME pointing to it.

A provider may give you records like:

Type: CNAME
Name: selector1._domainkey
Value: selector1.dkim.mail-provider.example

Some services provide one selector; others provide several. Publish every record shown in the provider dashboard.

Common DKIM problems include:

Entering the whole hostname when the DNS dashboard automatically appends the domain.
Checking default._domainkey when the provider uses another selector.
Creating a TXT record when the provider requested a CNAME.
Copying a target with missing characters.
Assuming that a published key means the sender has started signing.

After DNS verification, send a real test message and inspect its headers. Look for dkim=pass and verify that the signing domain aligns with the From domain.

For a more detailed walkthrough, see this DKIM setup guide.

Step 4: Start DMARC in monitoring mode

DMARC is a TXT record at _dmarc.yourdomain.com.

A sensible starting policy is:

Type: TXT
Name: _dmarc
Value: v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com

With p=none, receivers can send aggregate reports without being asked to quarantine or reject failures. This gives you time to find forgotten senders and alignment problems.

A safe rollout is usually:

Begin with p=none.
Review reports and fix legitimate failures.
Move a small percentage to p=quarantine.
Increase enforcement gradually.
Use p=reject only when authorized mail is consistently aligned.

The reporting address must be able to receive and process DMARC aggregate reports. These are XML files and can arrive in significant volume.

Step 5: Verify alignment, not only individual passes

A message can show spf=pass and still fail DMARC if SPF authenticated a different organizational domain. Likewise, DKIM must pass with an aligned signing domain.

DMARC passes when at least one aligned mechanism passes:

SPF passes and the authenticated SPF domain aligns with the From domain, or
DKIM passes and the DKIM signing domain aligns with the From domain.

This distinction matters with ticketing systems, newsletters, transactional platforms, and forwarding services.

Useful DNS checks

Replace the example domain and selector:

dig +short MX example.com
dig +short TXT example.com
dig +short TXT _dmarc.example.com
dig +short CNAME selector1._domainkey.example.com

If results differ between tools, query the authoritative nameserver directly. That helps distinguish a bad record from a resolver cache that has not refreshed yet.

DNS changes can appear quickly or take longer depending on TTL values and resolver caches. Repeatedly saving the same record does not make propagation faster.

Final validation checklist

Before declaring the configuration complete:

[ ] The intended MX destinations are publicly visible.
[ ] There is exactly one SPF record at each sending hostname.
[ ] Every legitimate sender is included in the SPF design.
[ ] All provider-issued DKIM selectors resolve.
[ ] Test messages show DKIM signatures.
[ ] DMARC exists at _dmarc, not at the root.
[ ] SPF or DKIM passes with DMARC alignment.
[ ] Bounce and complaint handling is active.
[ ] DMARC reports are being reviewed.
[ ] No API keys, SMTP passwords, or private keys were published.

A practical order of operations

For a new domain, I prefer this order:

Verify ownership with the email provider.
Publish DKIM.
Configure SPF for known senders.
Point MX to the receiving service.
Add DMARC with p=none.
Send and receive test messages.
Review headers and reports.
Tighten the DMARC policy gradually.

This order reduces the chance of enforcing a policy before authentication is actually working.

If you want a concise version you can keep beside your DNS dashboard, the public email DNS checklist on GitHub contains provider-neutral examples and an Amazon SES-specific companion guide.

What DNS provider or email service are you configuring? Share the record types—not credentials—in the comments, and I can help identify the usual pitfalls.