Skip to main content
Each stored message carries the codes and links DevHelm found in it, as otp[] and links[]. Wait returns both, so most tests read them straight from the wait result. 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:
The test injects a sign-up email with a code and a verification link, then reads both. In your suite, replace receive with the action that makes your app send the email.
The same arrays are also available on their own: 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.
Use 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. Each entry in links[] 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’s text is kept.
  • href is the link target with HTML escapes decoded, so ?token=abc&amp;user=42 in the HTML is ?token=abc&user=42 on the message. Tracking redirects are not followed or unwrapped.
Pick a link by its text, as in the example, or by host and path (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.enable set to false. Postmark: send with TrackLinks: "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 Location header. 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

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