otp[] and links[]. Wait returns both, so most tests read them straight from the wait result.
Read the code and the link
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:
receive with the action that makes your app send the email.
message.listOtp() and message.listLinks() in TypeScript, list_otp() and list_links() in Python, and GET …/messages/<message-id>/otp and …/links over REST.
How codes are found
Each entry is{value, source}, where source is the part the code was found in: text or html.
- Codes are deduplicated by value across the two parts.
- Codes next to a label such as “code” or “verification code” are found. Do not rely on a bare number being found.
- The order of entries across the text and HTML parts is not fixed.
otp[0] when the email has one code. When it has several, match on the value, for example mail.otp?.some((c) => c.value === expected), never on the position.
How links are found
Each entry inlinks[] is {href, text}, where text is the visible link text, when there is any.
- Links are deduplicated by
href. When two links share one, the first link’stextis kept. hrefis the link target with HTML escapes decoded, so?token=abc&user=42in the HTML is?token=abc&user=42on the message. Tracking redirects are not followed or unwrapped.
new URL(href).hostname === "app.example.com"). Text survives URL changes in your template, and host and path survive copy changes. Avoid links[0]: logos, footers, and unsubscribe links are links too.
Click tracking
Mail providers with click tracking, such as SendGrid and Postmark, rewrite every link to their own redirect host.links[] then holds the tracking URL, and a match on your app’s host finds nothing. Pick one:
- Turn click tracking off in the test environment. SendGrid: send with
tracking_settings.click_tracking.enableset tofalse. Postmark: send withTrackLinks: "None". The links then arrive as your app wrote them. - Match the link by its text, then request the tracking URL without following redirects and read the
Locationheader. The request registers a click with your provider.
TypeScript
When the code is not in otp[]
If your template shows the code without a label, match it on text or html. Wait and get both fill those fields, clipped at 256 KB.
source() is the RFC 822 text when you need the original message. It is clipped at 256 KB.
Troubleshooting
otp is empty or holds the wrong code
otp is empty or holds the wrong code
The code has no label, or the email has several codes and the test used
otp[0]. Match by value, or read the body as shown above. Log subject and receivedAt to check you have the right message.The link opens with an invalid or missing token
The link opens with an invalid or missing token
href is already unescaped. If the token is missing, the link was rewritten by click tracking or the template put the token somewhere other than the query string.No link matches my app's host
No link matches my app's host
Click tracking rewrote the links. Turn tracking off in the test environment, or match by
text and read the redirect.text and html are null
text and html are null
The message came from a wait or a list. GET it by id. In Python, use
source().Next steps
Wait for an email in a test
The wait that returns the message these fields come from.
How testing mailboxes work
Addresses, inject, and what each message stores.
Test a sign-up email flow
Playwright signs up, reads the code, and submits it.
Wait for a webhook in a test
The same wait semantics for webhook inboxes.
Test in CI
One address per test, cleanup, and the wait budget.
Limits, quotas, and errors
Body clipping, size limits, and error codes.