Skip to main content
A custom domain lets your app send test mail to addresses on a hostname you own, such as signup@test-mail.example.com. Publish two DNS records, verify them, and every local part on the domain becomes an inbox.

Before you start

  • Plan: custom domains need the Team testing plan or above. On Free and Developer, create returns 403 INBOUND_CUSTOM_MX_PLAN_REQUIRED; use the assigned domain instead.
  • Domain cap: the plan’s domain limit counts every domain in the organization, across workspaces, including the assigned domain and disabled domains. Over it, create returns 403 INBOUND_EMAIL_DOMAIN_LIMIT_REACHED. See limits.
  • DNS access to the zone that holds the hostname.
Export an API key. When the organization has one workspace, leave the workspace unset: the API uses that workspace, and the CLI and SDKs omit x-phelm-workspace-id. When it has more than one, export the workspace ID as well.
The CLI and Python SDK read DEVHELM_API_TOKEN. The TypeScript SDK takes the key in its constructor and reads DEVHELM_WORKSPACE_ID when it is set. With curl, send the workspace header only when you set the variable:

Use a subdomain

An MX record applies to one exact name. Put the testing domain on a subdomain that receives no other mail, such as test-mail.example.com. An MX on test-mail.example.com does not change delivery for example.com, so your real mail keeps flowing to your current provider, and your app keeps sending from its usual domain. Never point the MX of a domain that receives real mail at DevHelm: every message would land in a testing mailbox that any workspace member can read. A name under devhelmmail.com is refused with 400 INBOUND_DOMAIN_IN_ASSIGNED_ZONE.

Set it up

1

Create the domain

The domain starts in pending_dns with a verificationToken, and dnsRecords lists the records to publish.
2

Publish the two records

Many DNS providers append the zone to the name you type. In the example.com zone, enter _devhelm-verification.test-mail and test-mail, or you get test-mail.example.com.example.com.The TXT check also accepts the bare token as the value. The MX check passes when mx.devhelmmail.com is among the name’s MX records, but do not add other MX hosts: senders prefer the lowest priority, and that mail never reaches DevHelm.
3

Check the records resolve

An empty answer means the record is not published or has not propagated. Add @1.1.1.1 to skip your local cache.
4

Verify

When both records pass, status becomes active and verifiedAt is set. Otherwise the domain stays pending_dns and verificationError says why. REST and CLI JSON output also give each record found (true, false, or null before the first check) and lastCheckedAt; the SDK types do not include those two fields.
5

Get addresses on it

Wait, inject, list, and clear work as on the assigned domain. See wait for an email.
Leave both records in place after verification. DevHelm rechecks them in the background.

Domain states

A wait never checks the domain’s state. On a domain that cannot receive, it times out with 408.
  • pending_dns to active: a verify, manual or from the background recheck, finds both records.
  • pending_dns to verification_failed: the domain was not verified within 168 hours of createdAt. The change happens on the next verify or recheck. Background rechecks then stop, but a manual verify still activates the domain once the records are right.
  • active to pending_dns: a check confirms a record is wrong or missing, and real mail is refused until a verify passes. A failed DNS lookup, such as a resolver timeout, records an error but keeps the state.
  • To disabled: a member disables the domain. Stored messages stay.
  • disabled to active: run verify. If both records pass, the custom domain turns back on. A PATCH to active works only for assigned domains, and the CLI’s --status accepts only disabled.

Delete a domain

Deleting a domain deletes every message on it and frees a slot in the domain cap. Remove the MX record afterwards so senders stop delivering to it.
CLI
This page covers email testing domains. For a status page on your own hostname, see status page commands.

Troubleshooting

  • INBOUND_CUSTOM_MX_PLAN_REQUIRED: the organization’s testing plan is Free or Developer. Testing plans are separate from monitoring plans.
  • INBOUND_EMAIL_DOMAIN_LIMIT_REACHED: the organization holds as many domains as the plan allows, counting every workspace, the assigned domain, and disabled domains. Delete one you no longer use.
  • INBOUND_DOMAIN_NAME_INVALID: the name is not a valid hostname.
  • INBOUND_DOMAIN_NAME_TAKEN: another workspace or organization registered it. Names are unique across DevHelm.
  • INBOUND_DOMAIN_IN_ASSIGNED_ZONE: the name is under devhelmmail.com.
Run the dig checks. A doubled zone name is the most common mistake. The TXT token must come from this domain; a recreated domain has a new token. Then wait out the record’s TTL and verify again.
A check found a record changed or removed, often after a DNS cleanup or zone migration. Restore the records and run verify.
Inject also works on pending_dns and verification_failed domains; real mail does not. Check that status is active, then check your provider’s delivery log.

Next steps

Wait for an email in a test

Block a test on an address at your domain.

How testing mailboxes work

Addresses, inject, and what each message stores.

Wait for a webhook in a test

The same wait semantics for webhook inboxes.

Test in CI

Isolation, secrets, and cleanup in CI.

Limits, quotas, and errors

Domain caps per plan and every error code.