# Guide: Testing Emails in Cypress

To test emails in Cypress, register `cy.task` handlers in `cypress.config.ts` that call the Receiver.email SDK in Node, then call them from your spec to get a fresh address, the emailed code or a link.

## How to Test Emails in Cypress

Cypress specs run in the browser, but your API key and the SDK belong in Node. `cy.task` bridges the two: the task creates an inbox or waits for an email server-side and returns plain JSON (an address, a code, a URL) to the spec.

```bash
npm install --save-dev cypress @receiverdotemail/sdk
export RECEIVER_API_KEY="recv_live_..."
```

## Register the Tasks

```typescript
import { defineConfig } from "cypress";
import { ReceiverClient } from "@receiverdotemail/sdk";

type WaitArgs = { address: string; since: string };

export default defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
    taskTimeout: 90_000, // longer than the waits below
    setupNodeEvents(on) {
      const receiver = new ReceiverClient(); // reads RECEIVER_API_KEY

      on("task", {
        // Returns { address, prefix, projectId, createdAt }
        createInbox(prefix: string) {
          return receiver.inboxes.create({ prefix });
        },

        // Returns the code as a string
        async waitForOtp({ address, since }: WaitArgs) {
          const otp = await receiver.emails.waitForOtp({
            recipient: address,
            since,
            timeout: 60,
          });
          return otp.code;
        },

        // Returns the first link whose path starts with pathPrefix
        async waitForLink({ address, since, pathPrefix }: WaitArgs & { pathPrefix: string }) {
          const email = await receiver.emails.waitFor({
            recipient: address,
            since,
            timeout: 60,
          });
          const link = email.links.find((l) => new URL(l).pathname.startsWith(pathPrefix));
          if (!link) throw new Error(`No ${pathPrefix} link in "${email.subject}": ${email.links.join(", ")}`);
          return link;
        },
      });
    },
  },
});
```

## Example: Sign-Up Verification Code

```typescript
import type { Inbox } from "@receiverdotemail/sdk";

describe("sign-up", () => {
  it("verifies the account with the emailed code", () => {
    cy.task<Inbox>("createInbox", "signup").then((inbox) => {
      cy.visit("/signup");
      cy.get("input[name=email]").type(inbox.address);
      cy.contains("button", "Send code").click();

      cy.task<string>("waitForOtp", { address: inbox.address, since: inbox.createdAt })
        .then((code) => {
          cy.get("input[name=code]").type(code);
          cy.contains("button", "Verify").click();
          cy.location("pathname").should("eq", "/dashboard");
        });
    });
  });
});
```

## Example: Password Reset Link

```typescript
import type { Inbox } from "@receiverdotemail/sdk";

describe("password reset", () => {
  it("resets the password from the emailed link", () => {
    cy.task<Inbox>("createInbox", "reset").then((inbox) => {
      // Create the user first (seed task, API call or UI sign-up)
      cy.request("POST", "/api/test/users", { email: inbox.address, password: "old-Pa55word!" });

      cy.visit("/forgot-password");
      cy.get("input[name=email]").type(inbox.address);
      cy.contains("button", "Send reset link").click();

      cy.task<string>("waitForLink", {
        address: inbox.address,
        since: inbox.createdAt,
        pathPrefix: "/reset-password",
      }).then((link) => {
        cy.visit(link);
        cy.get("input[name=password]").type("new-Pa55word!");
        cy.contains("button", "Save").click();
        cy.contains("Password updated").should("be.visible");
      });
    });
  });
});
```

Magic link login works the same way: wait for the link with `waitForLink` and `cy.visit()` it. See [Testing Magic Link Login](https://www.receiver.email/docs/guides/magic-links).

## Tips

- **Task timeout**: `cy.task` fails after `taskTimeout` (60 seconds by default). Keep it above the SDK `timeout`, or pass `{ timeout: 90000 }` as the third argument to `cy.task`.
- **Return JSON**: a task must return something serializable and not `undefined`. Return the code or the URL, not the SDK client.
- **Other origins**: if the link points at a different domain than `baseUrl`, wrap the steps that follow in `cy.origin()`.
- **Unique inboxes**: `createInbox` adds random characters to the prefix, so parallel runs and retries never read each other's mail.
- **CI**: set `RECEIVER_API_KEY` as a secret in the environment that runs `cypress run`. See [CI/CD Integration](https://www.receiver.email/docs/guides/ci-cd).

## Next Steps

- [Testing Emails in Playwright](https://www.receiver.email/docs/guides/playwright): fixtures instead of tasks
- [Testing OTP / 2FA](https://www.receiver.email/docs/guides/otp-verification): resends and multiple codes
- [Testing Password Resets](https://www.receiver.email/docs/guides/password-reset): the full reset flow
- [TypeScript SDK Reference](https://www.receiver.email/docs/sdks/typescript)

---

Source: https://www.receiver.email/docs/guides/cypress
