Skip to main content
Give each test its own address and wait. Omit receivedAfter and the server looks back 60 seconds, which includes mail that arrived just before the call. The API holds the request until a matching message is stored and returns it, or answers 408 when the timeout passes.

Setup

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:
Install the SDK and a test runner: npm install --save-dev @devhelm/sdk vitest or pip install devhelm pytest. The TypeScript SDK is ESM only.

Complete example

The test injects the email so it runs without a mail provider. In your suite, replace receive with the action that makes your app send mail, such as submitting the sign-up form.
  • The Vitest timeout (90 s) is longer than the wait (60 s), so a miss surfaces as the wait’s 408. A longer runner timeout does not extend the HTTP call; a shorter one cuts it off.
  • A REST wait returns {"message": {...}} with no data wrapper. The CLI prints the bare message.

What wait does

Omit receivedAfter on a fresh address. The server then matches mail from the last 60 seconds, including a message that arrived before the wait call. A reused address can still return an older message from that window, so give each test its own address. To read the next message, pass the previous receivedAt plus 1 ms.

Full address or local part

Addresses are case-folded, so an upper-case to matches the same inbox.

Wait for a second email

Passing the first message’s receivedAt returns the first message again, because the match is inclusive. Add 1 ms to get the next one.
Do not list messages right after a wait to find later ones. Storage is asynchronous, so the list can lag. Use one wait per message.

Assert that no email was sent

Expect the 408. Give the wait enough time to cover your app’s send latency plus a few seconds of storage lag. Each negative assertion spends one wait call and its full timeout.

Handle a timeout and the rate limit

A timeout is HTTP 408:
Neither SDK has a timeout error class: the 408 is a DevhelmApiError with status 408 and code "WAIT_TIMEOUT". A 429 is a DevhelmRateLimitError with retryAfter in seconds. Neither SDK retries on its own. The CLI prints the error and exits non-zero.
Every wait call in the organization shares one budget of 40 per minute: email and webhook waits, every workspace, every CI job. Use one wait with a longer timeoutMs per expected email instead of a loop of short waits; a timed-out wait costs a call too. See testing in CI for parallel jobs.

Troubleshooting

  • receivedAfter was set after the trigger, so the message is older than the cursor. Omit it on a fresh address.
  • The address differs from the one your app sent to. user+tag@ is its own inbox.
  • subjectContains does not match. Drop it to check.
  • Your provider did not deliver. A 250 from the provider means it accepted the message. Check its activity log and that sandbox mode is off.
  • The monthly event cap was hit. An inject accepted at the cap can be dropped after its 202. Check usage against your plan.
Wait does not consume. For the next message, pass the previous receivedAt plus 1 ms. For stale matches, use a fresh address per test.
A list row is a preview and leaves text and html null. Wait and get fill them, clipped at 256 KB. source() is the RFC 822 text when you need the original message.
The organization’s 40 waits per minute are spent, possibly by other jobs. Back off for retryAfter seconds and reduce parallel waits.
The workspace ID is wrong, or the organization has more than one workspace and DEVHELM_WORKSPACE_ID is unset. With one workspace, leave it unset. See setup.

Next steps

Read OTP codes and links

Pull the code or link out of the message you waited for.

How testing mailboxes work

Domains, 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, teardown, and the shared wait budget.

Limits, quotas, and errors

Every limit and error code.