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.
x-phelm-workspace-id. When it has more than one, export the workspace ID as well.
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 astest-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
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
@1.1.1.1 to skip your local cache.4
Verify
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
Domain states
A wait never checks the domain’s state. On a domain that cannot receive, it times out with 408.
pending_dnstoactive: a verify, manual or from the background recheck, finds both records.pending_dnstoverification_failed: the domain was not verified within 168 hours ofcreatedAt. 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.activetopending_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. disabledtoactive: run verify. If both records pass, the custom domain turns back on. A PATCH toactiveworks only for assigned domains, and the CLI’s--statusaccepts onlydisabled.
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
Troubleshooting
403 when creating the domain
403 when creating the domain
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.
400 when creating the domain
400 when creating the domain
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 underdevhelmmail.com.
Verify keeps returning pending_dns
Verify keeps returning pending_dns
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.The domain went from active back to pending_dns
The domain went from active back to pending_dns
A check found a record changed or removed, often after a DNS cleanup or zone migration. Restore the records and run verify.
Real mail does not arrive, but inject works
Real mail does not arrive, but inject works
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.