# Testing Sign-Up Email Verification

Check that sign-up sends a confirm-your-address email, and that its link or code really verifies the account.

To test sign-up email verification, create an inbox, sign up with its address, and wait for the confirmation email from `inbox.createdAt`. Open the link from `email.links`, or submit the code that `waitForOtp()` returns, then check that the account is verified, and that it was not before. The examples below call your app over HTTP; the browser guides do the same through the UI.

## What to Cover

- **Delivery**: the email reaches the address the user typed, from the sender and with the subject you expect.
- **The gate**: the account is not verified until the link or code is used.
- **Verification**: the link or code verifies the account.
- **Edge cases**: resending, expired or reused links, wrong codes.

## Install

TypeScript

```bash
npm install --save-dev @receiverdotemail/sdk
```

Python

```bash
pip install receiverdotemail httpx pytest-asyncio
```

Both SDKs read `RECEIVER_API_KEY`. The TypeScript tests run in Jest or Vitest; the Python tests need `asyncio_mode = auto`, as in [Pytest Integration](https://www.receiver.email/docs/guides/pytest).

## A Link Helper

An email can list the same link twice, once with `&amp;` in place of `&`, or with a trailing full stop from the text body. [Testing Magic-Link Login](https://www.receiver.email/docs/guides/magic-links) explains why. These helpers return the first link to a path, cleaned up:

```typescript
export function findLink(links: string[], path: string) {
  for (const raw of links) {
    const link = raw
      .replace(/&amp;/g, "&")
      .replace(/[.,;:!?)]+$/, "");
    const { pathname } = new URL(link);
    if (pathname.startsWith(path)) return link;
  }
  throw new Error(`No ${path} link in ${links}`);
}
```

```python
import html
import re
from urllib.parse import urlsplit

def find_link(links, path):
    for raw in links:
        link = html.unescape(raw)
        link = re.sub(r"[.,;:!?)]+$", "", link)
        if urlsplit(link).path.startswith(path):
            return link
    raise AssertionError(f"no {path} link in {links}")
```

## Verify With a Link

Sign up, check that login is refused, follow the link, check that login works. Replace the endpoints and status codes with your app's:

```typescript
import { ReceiverClient } from "@receiverdotemail/sdk";
import { findLink } from "./links";

const receiver = new ReceiverClient();
const APP = "https://staging.your-app.com";
const PASSWORD = "S3cure-test-pass";
const post = (path: string, body: object) =>
  fetch(APP + path, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

test("the link verifies the account", async () => {
  const inbox = await receiver.inboxes.create();
  const user = { email: inbox.address, password: PASSWORD };

  await post("/api/signup", user);
  const before = await post("/api/login", user);
  expect(before.status).toBe(403); // not verified yet

  const email = await receiver.emails.waitFor({
    recipient: inbox.address,
    since: inbox.createdAt,
    subject: "Confirm",
    timeout: 60,
  });
  expect(email.sender).toBe("[email protected]");

  const link = findLink(email.links, "/verify-email");
  expect((await fetch(link)).ok).toBe(true);

  const after = await post("/api/login", user);
  expect(after.status).toBe(200);
}, 90_000);
```

```python
import httpx
from receiverdotemail import ReceiverClient
from links import find_link

APP = "https://staging.your-app.com"
PASSWORD = "S3cure-test-pass"

async def test_link_verifies_account():
    async with ReceiverClient() as receiver, \
            httpx.AsyncClient(base_url=APP) as http:
        inbox = await receiver.inboxes.create()
        user = {"email": inbox.address,
                "password": PASSWORD}

        await http.post("/api/signup", json=user)
        res = await http.post("/api/login", json=user)
        assert res.status_code == 403  # not verified yet

        email = await receiver.emails.wait_for(
            recipient=inbox.address,
            since=inbox.created_at,
            subject="Confirm",
            timeout=60,
        )
        assert email.sender == "[email protected]"

        link = find_link(email.links, "/verify-email")
        res = await http.get(link, follow_redirects=True)
        assert res.is_success
        res = await http.post("/api/login", json=user)
        assert res.status_code == 200
```

## Verify With a Code

```typescript
test("the code verifies the account", async () => {
  const inbox = await receiver.inboxes.create();
  const user = { email: inbox.address, password: PASSWORD };
  await post("/api/signup", user);

  const otp = await receiver.emails.waitForOtp({
    recipient: inbox.address,
    since: inbox.createdAt,
    codeLength: 6,
    timeout: 60,
  });

  const res = await post("/api/verify-email", {
    email: inbox.address,
    code: otp.code,
  });
  expect(res.status).toBe(200);
}, 90_000);
```

```python
async def test_code_verifies_account():
    async with ReceiverClient() as receiver, \
            httpx.AsyncClient(base_url=APP) as http:
        inbox = await receiver.inboxes.create()
        user = {"email": inbox.address,
                "password": PASSWORD}
        await http.post("/api/signup", json=user)

        otp = await receiver.emails.wait_for_otp(
            recipient=inbox.address,
            since=inbox.created_at,
            code_length=6,
            timeout=60,
        )

        res = await http.post("/api/verify-email", json={
            "email": inbox.address,
            "code": otp.code,
        })
        assert res.status_code == 200
```

## When Sign-Up Sends Two Emails

A welcome email and a confirmation email often leave together. `waitFor()` returns the newest matching email received after `since`, which may be the welcome email, so filter on `subject` (a case-insensitive substring) or `sender` (the exact From address). `waitForOtp()` takes the same filters; add `codeLength` so a year or an order number in the other email is not taken for the code.

## Resending, Expiry and Reuse

For "Resend email", wait again from the first email's `receivedAt`, so only the new email can match. If your app invalidates the old link, check that as well:

```typescript
const first = await receiver.emails.waitFor({
  recipient: inbox.address,
  since: inbox.createdAt,
  subject: "Confirm",
});
await post("/api/verify-email/resend", { email: inbox.address });

const second = await receiver.emails.waitFor({
  recipient: inbox.address,
  since: first.receivedAt,
  subject: "Confirm",
});
expect((await fetch(findLink(first.links, "/verify-email"))).ok).toBe(false);
expect((await fetch(findLink(second.links, "/verify-email"))).ok).toBe(true);
```

For expiry, give the test environment a short link lifetime instead of waiting it out. For reuse, open the same link twice and expect the second attempt to fail. For a wrong code, submit one that differs from `otp.code`.

## Checking the Email Itself

`waitFor()` returns the subject, the sender, the plain-text body (`textBody`, `text_body` in Python) and the links, enough to assert on the wording. For the HTML body, headers or attachments, fetch the whole email with `receiver.emails.get(email.id)` and read `htmlBody` (`html_body`).

## In the Browser

The same steps work through your sign-up page. Each browser guide has a test with a code and one with a link: [Playwright](https://www.receiver.email/docs/guides/playwright), [Cypress](https://www.receiver.email/docs/guides/cypress) and [Selenium](https://www.receiver.email/docs/guides/selenium).

## Next Steps

- [Testing Magic-Link Login](https://www.receiver.email/docs/guides/magic-links): picking links, one-time links and tracking redirects
- [Testing OTP / 2FA](https://www.receiver.email/docs/guides/otp-verification): resending codes and choosing between them
- [Concepts](https://www.receiver.email/docs/concepts#since): how `since` works, and why waiting from `createdAt` is safe

---

Source: https://www.receiver.email/docs/guides/email-verification
