> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Your First Test Email

> Get a DevHelm testing address, inject an email, wait for it, and assert on the OTP code, with no mail provider needed

By the end of this guide, you'll have a testing address that received an email, and a Vitest or pytest test that waits for it and reads the one-time code. Inject puts the message in the mailbox through the API, so no mail provider is needed.

> [accordion] Prerequisites
>
> * The CLI (`npm install -g devhelm`) or curl, plus `jq`, for the steps; `@devhelm/sdk` with Vitest (ESM only), or `devhelm` with pytest, for the test
> * Room for an email domain, or an assigned domain that already exists in the workspace. Domains are counted per organization: 1 on the Free and Developer testing plans
>
> 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.
>
> ```bash theme={null}
> export DEVHELM_API_TOKEN=dh_live_xxxxxxxx
> # Only when the organization has more than one workspace:
> export DEVHELM_WORKSPACE_ID=<workspace-id>
> ```
>
> 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:
>
> ```bash theme={null}
> -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
> -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID"
> ```

## Receive a message

**1. Get an address**

```bash CLI theme={null}
devhelm email address --label first-email -o json > address.json
ADDRESS=$(jq -r .email address.json)
```

```bash API theme={null}
DOMAIN=$(curl -s https://api.devhelm.io/api/v1/email/domains \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID" \
  | jq -r '[.data[] | select(.kind == "assigned" and .status == "active")][0].name')
if [ "$DOMAIN" = "null" ]; then
  DOMAIN=$(curl -s -X POST https://api.devhelm.io/api/v1/email/domains \
    -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
    -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID" \
    -H "Content-Type: application/json" \
    -d '{}' | jq -r .data.name)
fi
LOCAL_PART="first-email-$(openssl rand -hex 4)"
ADDRESS="$LOCAL_PART@$DOMAIN"
```

The address looks like `first-email-1a2b3c4d@defaultworks-4j4n.devhelmmail.com`. The first call in a workspace creates its assigned domain, and later calls reuse it. Read the domain from the helper or `devhelm email domains list`; do not build the name yourself. There is no mailbox to create: every local part on the domain is its own inbox. The helper adds a random 8-hex suffix, so each call gives a fresh address.

**2. Inject a message**

```bash CLI theme={null}
devhelm email receive --to "$ADDRESS" --from noreply@example.com \
  --subject "Your code" --text "Your verification code is 482913."
```

```bash API theme={null}
curl -s -X POST "https://api.devhelm.io/api/v1/email/domains/$DOMAIN/messages/inject" \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"to\": \"$ADDRESS\", \"from\": \"noreply@example.com\", \"subject\": \"Your code\", \"text\": \"Your verification code is 482913.\"}"
```

Inject stands in for your app's mail provider and runs the same parsing as real mail, including code and link extraction. It answers `202` with `{eventId, receivedAt, inbox}`: accepted, not yet stored. Injected messages count toward the monthly event quota.

**3. Wait and assert on the code**

```bash CLI theme={null}
devhelm email wait --to "$ADDRESS" -o json > message.json
jq -e '.otp[0].value == "482913"' message.json
```

```bash API theme={null}
curl -s -X POST https://api.devhelm.io/api/v1/email/wait \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"to\": \"$ADDRESS\", \"timeoutMs\": 30000}" \
  | jq .message > message.json
jq -e '.otp[0].value == "482913"' message.json
```

Wait blocks until a matching message is stored, then returns it. If nothing arrives within `timeoutMs` (default 30000), the API returns `408` with code `WAIT_TIMEOUT`. REST returns `{"message": {...}}` with no `data` wrapper. CLI `email wait --to` takes the full address.

`otp` is a list of `{value, source}`, where `source` is `text` or `html`. A code that appears in both parts is listed once. Use `otp[0]` when the email has one code, and match on `value` when it has several. Labelled codes are extracted, as in "verification code is 482913" or "Code: 482913"; years and phone numbers are ignored.

The message also carries `from`, `to`, `subject`, `headers`, `text`, `html`, `bodyPreview`, and `links` (`{href, text}`). `text` and `html` are clipped at 256 KB. A list row leaves them null. [Wait for an email in a test](https://docs.devhelm.io/testing/email/wait.md) shows both.

**4. Clear the address**

```bash CLI theme={null}
devhelm email clear --to "$ADDRESS" -y
```

```bash API theme={null}
curl -s -X DELETE "https://api.devhelm.io/api/v1/email/domains/$DOMAIN/inboxes/$LOCAL_PART" \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "x-phelm-workspace-id: $DEVHELM_WORKSPACE_ID"
```

Clearing deletes the address's messages. Leave the assigned domain in place: deleting it and calling the helper again gives the workspace a domain with a new name, which breaks any address you stored.

## Write the test

The same flow as one test file, with cleanup. `receive` stands in for the code under test: replace it with the call that makes your app send its email.

```typescript first-email.test.ts theme={null}
import { Devhelm } from "@devhelm/sdk";
import { expect, test } from "vitest";

const client = new Devhelm({ token: process.env.DEVHELM_API_TOKEN! });

test("reads the verification code", async () => {
  const address = await client.email.address({ label: "first-email" });
  try {
    await address.receive({
      from: "noreply@example.com",
      subject: "Your code",
      text: "Your verification code is 482913.",
    });

    const message = await address.wait({ timeoutMs: 30_000 });

    expect(message.subject).toBe("Your code");
    expect(message.otp?.[0]?.value).toBe("482913");
  } finally {
    await address.clear();
  }
}, 45_000);
```

```python test_first_email.py theme={null}
from devhelm import Devhelm

client = Devhelm()


def test_reads_verification_code():
    address = client.email.address(label="first-email")
    try:
        address.receive(
            from_="noreply@example.com",
            subject="Your code",
            text="Your verification code is 482913.",
        )

        message = address.wait(timeout_ms=30_000)

        assert message.subject == "Your code"
        assert message.otp, "no code extracted"
        assert message.otp[0].value == "482913"
    finally:
        address.clear()
```

Run it with `npx vitest run first-email.test.ts` or `pytest test_first_email.py`. One test passes.

The runner timeout (45 s) is longer than the wait timeout (30 s), so a missing email fails with the API's `408` instead of the runner killing the test. Each run gets a new address, so an earlier message cannot match.

## Send real mail from your app

The address also receives real mail. `devhelmmail.com` has a wildcard MX record, so your app's mail provider can deliver to the address like any other, and the same wait picks the message up. Point your sign-up form at an address from the helper and wait. [Test a sign-up email flow](https://docs.devhelm.io/guides/test-signup-email-flow.md) covers provider sandboxes and click tracking.

## Troubleshooting

> [accordion] The wait returns 408 WAIT\_TIMEOUT
>
> * `receivedAfter` was set after the inject. Omit it on a fresh address.
> * The address differs from the one you sent to. CLI `--to` takes the full address, not the local part.
> * Your organization hit its monthly event quota. Inject can still answer `202` and then drop the message. See [Limits, quotas, and errors](https://docs.devhelm.io/testing/limits.md).

> [accordion] 403 INBOUND\_EMAIL\_DOMAIN\_LIMIT\_REACHED
>
> The domain cap counts the whole organization. On Free or Developer, a domain in another workspace blocks creating one here. Use the workspace that has the domain.

> [accordion] otp is empty
>
> The code has no label near it. Put "code" or "verification code" next to it in your template, or read the body and match it yourself. See [Read OTP codes and links](https://docs.devhelm.io/testing/email/otp-and-links.md).

## Next steps

> [card] [How testing mailboxes work](https://docs.devhelm.io/testing/email/overview.md)
>
> Domains, stored fields, search, source, and raw downloads.

> [card] [Read OTP codes and links](https://docs.devhelm.io/testing/email/otp-and-links.md)
>
> Several codes, picking a link, and click-tracking redirects.

> [card] [Test a sign-up email flow](https://docs.devhelm.io/guides/test-signup-email-flow.md)
>
> Playwright signs up, your app sends real mail, the test reads the code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.