Set up
Export an API key. When the organization has one workspace, leave the workspace unset: the API uses that workspace, and the CLI and SDKs omitx-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:
Your workspace domain
Each workspace gets an assigned domain underdevhelmmail.com the first time it needs one: on POST /api/v1/email/domains with an empty body, or on the first call to the address helper. The name comes from the workspace name plus four random characters, for example defaultworks-4j4n.devhelmmail.com. Read it from the API; do not build it yourself.
active, with its MX record in place, as soon as it exists.
- The domain cap counts the whole organization, disabled domains included. On the Free and Developer testing plans, a second workspace that asks for a domain gets 403
INBOUND_EMAIL_DOMAIN_LIMIT_REACHED. - Keep the domain. Delete it and call the address helper again, and you get a new random name. Every stored address stops receiving.
- To receive on a hostname you own, see custom domains.
Addresses
There is no mailbox to create. Any local part on the domain is an inbox. Local parts are case-folded, soSignup@ and signup@ are the same inbox. Plus addressing gets no special handling: user+a@ is a separate inbox from user@.
The address helper returns {email, domain, localPart}. The local part is your label plus 8 random hex characters, so each call gives a new, empty inbox. It makes no API call for the address itself; it only looks up the assigned domain and creates it if missing. Pass domain to use a custom domain. Use one address per test.
Two ways to get mail in
Both paths store the same fields and run the same OTP and link extraction.
Real mail.
devhelmmail.com has a wildcard MX record to mx.devhelmmail.com, so any address on an assigned domain accepts mail from the internet. A 250 from your own mail provider means the provider accepted the message, not that it arrived. Assert on the wait.
Inject. DevHelm builds the MIME message from your JSON and stores it as if it had arrived by SMTP.
- Inject returns 202 with
{eventId, receivedAt, inbox}: accepted, not yet stored. Read the message back with wait. - Only the local part of
tois used. The message lands in that inbox on the domain in the URL. headers(a fixedMessage-IDorDate, for example) work through the SDKs and REST and appear in the stored headers and raw message.devhelm email receivehas no headers flag.- Inject cannot add attachments. On a disabled domain it returns 400
INBOUND_INJECT_DOMAIN_DISABLED.
What each message stores
Wait and GET fill
text and html. A list row is a preview and leaves them null.
Read messages
List and search
List an address’s messages, newest first.q is a case-insensitive substring match on the subject, the sender, and the local part, not the body.
nextCursor back as cursor while hasMore is true. limit is 1–100, default 50. Over REST, leaving out inbox lists every address on the domain.
Get the body, source, and raw message
textandhtmlon get and wait are clipped at 256 KB, andbodyTruncatedis thentrue. A list row leavestextandhtmlnull.sourcereturns the RFC 822 text as{source, truncated}, also clipped at 256 KB.rawreturns{url, expiresAt, filename, contentType, sizeBytes}, a signed link to the full.emlthat expires after 60 seconds. The file’s SHA-256 matches the message’ssha256.- The HTML is not sanitized. Render it only in a sandboxed frame.
Clear an address
Clearing deletes every message sent to one address. Do it in test teardown; retention does not clean up for you.message.delete(), DELETE …/messages/<message-id>); the CLI does not. Deleting a domain deletes all of its messages.
24-hour activity
Activity returns{hour, messageCount} buckets per domain for the last 24 UTC hours: devhelm email domains activity --id <domain-id>, client.email.domains.activity([...]) in both SDKs, or GET /api/v1/email/domains/activity?domainIds=<domain-id>.
Plan quotas
Quotas apply per organization. Captured webhook events and received emails share the monthly event count. Testing plans are separate from monitoring plans.
Every received email, real or injected, counts toward the monthly events. Rate limits, size limits, and error codes are in limits.
Who can read the mail
Anyone can send to an address on your domain. Reading needs an API key or a member login for the workspace, and every member and key can read, inject, and delete. Stored headers are visible to all of them. Do not use testing addresses for real accounts or customer data. See security and data. A testing mailbox receives mail your app sends. The email alert channel is different: it sends DevHelm incident alerts to your team. Reference: CLIdevhelm email, TypeScript client.email, Python client.email, and the Email Testing API.
Next steps
Wait for an email in a test
Block a test until the message arrives, without sleeps or stale matches.
Read OTP codes and links
Pull the code or the verification link from the message.
Your first test email
Get an address, inject, wait, and assert, with no mail provider.
Receive on your own domain
Use a hostname you own instead of the assigned domain.
What is email testing?
Testing mailboxes, public inbox services, and real delivery.
Test in CI
One address per test, secrets, cleanup, and the shared wait budget.