Skip to main content
A testing mailbox is any address on a domain DevHelm receives mail for. Your app or your test sends to the address, and the test waits for the message and reads its subject, body, codes, and links.

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 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:

Your workspace domain

Each workspace gets an assigned domain under devhelmmail.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.
The assigned domain is 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, so Signup@ 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.
Over REST, put any local part in front of the domain name.

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 to is used. The message lands in that inbox on the domain in the URL.
  • headers (a fixed Message-ID or Date, for example) work through the SDKs and REST and appear in the stored headers and raw message. devhelm email receive has 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 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.
The response is a cursor page: pass 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

  • text and html on get and wait are clipped at 256 KB, and bodyTruncated is then true. A list row leaves text and html null.
  • source returns the RFC 822 text as {source, truncated}, also clipped at 256 KB.
  • raw returns {url, expiresAt, filename, contentType, sizeBytes}, a signed link to the full .eml that expires after 60 seconds. The file’s SHA-256 matches the message’s sha256.
  • 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.
The SDKs and REST also delete one message (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: CLI devhelm 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.