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 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:
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, replacereceive 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 nodatawrapper. 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’sreceivedAt returns the first message again, because the match is inclusive. Add 1 ms to get the next one.
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: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.
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
408, but the email was sent
408, but the email was sent
receivedAfterwas 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. subjectContainsdoes not match. Drop it to check.- Your provider did not deliver. A
250from 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.
The wait returns the same message twice, or one from an earlier run
The wait returns the same message twice, or one from an earlier run
Wait does not consume. For the next message, pass the previous
receivedAt plus 1 ms. For stale matches, use a fresh address per test.text and html are null
text and html are null
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.429 from wait
429 from wait
The organization’s 40 waits per minute are spent, possibly by other jobs. Back off for
retryAfter seconds and reduce parallel waits.404 Workspace doesn't exist
404 Workspace doesn't exist
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.