# Quickstart

mailstest catches the email your app sends and delivers it nowhere, so a test or an agent can read it. This page takes you from no account to a Playwright test that follows your app's sign-in link in CI, then to an agent reading the same mail. Every call the SDK offers is in the [SDK reference](/sdk).

## Sign in and create the app's inbox {#sign-in}

1. Open [app.mailstest.com](https://app.mailstest.com), enter your email, and follow the sign-in link that `login@mailstest.com` sends you. The link works once, within 15 minutes.
2. New accounts are by invitation for now. If your address is neither on the list nor invited, the link leads to a card saying that MailsTest is in private beta: write to [support@mailstest.com](mailto:support@mailstest.com) to ask for access.
3. Your first sign-in makes a workspace you own, on the Free plan: 1 inbox, which keeps its latest 100 emails for 7 days each, at most 5 MiB per message.
4. Click **Create your first inbox** and name it after your app. The reveal shows the inbox's SMTP credential, a username and a password, in a `.env` snippet: copy it now. The password is shown once; if you lose it, rotate the credential on the inbox page to get a new one.

The snippet's last line, `MAILSTEST_INBOX_ID`, is the inbox's id, which the test needs. It is also the last part of the inbox page's address, `/inboxes/<inbox id>`.

## Point the app at the inbox {#send}

Your app sends to mailstest instead of its usual provider, one path of three, each with the inbox's SMTP credential. Pick the one your app already uses. The recipient address routes nothing: the credential decides the inbox, and the mail goes no further.

### SMTP {#smtp}

The host is `smtp.mailstest.com`, on port 465 with implicit TLS. It offers no STARTTLS and requires AUTH. These are the reveal's SMTP lines:

```dotenv smtp-env
SMTP_HOST=smtp.mailstest.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=<username>
SMTP_PASS=<password>
```

A nodemailer transport that reads them:

```ts nodemailer
import nodemailer from 'nodemailer';

export const transport = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: Number(process.env.SMTP_PORT),
  secure: process.env.SMTP_SECURE === 'true',
  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
});
```

On a network that blocks 465, send through the [Resend door](#resend) or the [SendGrid door](#sendgrid) instead: each takes the same credential over HTTPS.

Port 2525 also takes mail, in plaintext, so the credential and every message cross the network unencrypted; use it only on a network you control.

### The Resend door {#resend}

The Resend door takes Resend's send calls, `POST /emails` and `POST /emails/batch`, at `https://capture.mailstest.com/`. Its key is the door token: the SMTP username and password joined by a dot. These are the reveal's Resend lines:

```dotenv resend-env
RESEND_BASE_URL=https://capture.mailstest.com/
RESEND_API_URL=https://capture.mailstest.com/
RESEND_API_KEY=<username>.<password>
```

The Node SDK reads `RESEND_BASE_URL` and `RESEND_API_KEY` itself, so `new Resend(process.env.RESEND_API_KEY)` needs no code change. The Python SDK reads its base URL from `RESEND_API_URL`. Keep the trailing slash.

### The SendGrid door {#sendgrid}

The SendGrid door takes `POST /v3/mail/send` at `https://capture.mailstest.com`. Its key is the door token behind `SG.`. These are the reveal's SendGrid lines:

```dotenv sendgrid-env
SENDGRID_BASE_URL=https://capture.mailstest.com
SENDGRID_API_KEY=SG.<username>.<password>
```

No SendGrid SDK reads its host from the environment, so the app sets it in code, after `setApiKey`, which resets it. In TypeScript:

```ts sendgrid
import client from '@sendgrid/client';
import sgMail from '@sendgrid/mail';

client.setApiKey(process.env.SENDGRID_API_KEY!);
client.setDefaultRequest('baseUrl', process.env.SENDGRID_BASE_URL!);
sgMail.setClient(client);
```

In JavaScript, `sgMail.setApiKey(process.env.SENDGRID_API_KEY)` followed by `sgMail.client.setDefaultRequest('baseUrl', process.env.SENDGRID_BASE_URL)` does the same. Keep that order: the other one sends the key to SendGrid.

**Templates are not rendered.** A Resend send with a `template`, or a SendGrid send with a `template_id`, lands with its variables attached and no body, and SendGrid's substitutions stay as written. A test finds no link in such an email, so for a sign-in test the app sends its own HTML or text. The doors take sends only: any other call of either API, such as SendGrid's `GET /v3/scopes` key check, answers 404.

## Issue a workspace API key {#api-key}

The test and the agent read the mail with a workspace API key, never with the SMTP credential. On the dashboard's **API Keys** screen, click **Issue your first key**, name it, and click **Issue key**. The reveal shows the key once, in these lines:

```dotenv api-key-env
MAILSTEST_BASE_URL=https://app.mailstest.com
MAILSTEST_API_KEY=<key>
```

Keep the key in your secret store, never in a committed file.

## Write the test {#test}

Install the SDK beside Playwright. It needs Node 20.19+ or 22.12+ and `@playwright/test` 1.64 or later.

```sh install
npm install -D @mailstest/playwright @playwright/test
```

Add the fixtures. Each test gets the app's inbox and an address that no other test shares:

```ts fixtures
// tests/fixtures.ts
import { test as base } from '@playwright/test';
import { mailstestFixtures } from '@mailstest/playwright/fixtures';

export const test = base.extend(mailstestFixtures);
export { expect } from '@mailstest/playwright';
```

Configure them from the environment. The test timeout stays above the 30-second mail wait, so a slow email fails on the wait, not on the test's clock:

```ts config
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import type { MailstestOptions } from '@mailstest/playwright/fixtures';

export default defineConfig<MailstestOptions>({
  timeout: 60_000, // above the 30-second mail wait
  use: {
    baseURL: 'http://localhost:3000',
    mailstestConfig: {
      baseUrl: process.env.MAILSTEST_BASE_URL!,
      apiKey: process.env.MAILSTEST_API_KEY!,
      inboxId: process.env.MAILSTEST_INBOX_ID!,
    },
  },
  // the app sends with the SMTP_* or RESEND_* lines in its environment
  webServer: { command: 'npm start', url: 'http://localhost:3000' },
});
```

The test signs in with the fixture's address, waits for the app's email to that address, and follows its link:

```ts sign-in-test
// tests/sign-in.spec.ts
import { expect, test } from './fixtures';

test('the sign-in link signs the user in', async ({ page, mailstest }) => {
  const { inbox, address } = mailstest;
  await page.goto('/login');
  await page.getByLabel('Email').fill(address);
  await page.getByRole('button', { name: 'Send sign-in link' }).click();

  const { message } = await inbox.recipient(address).waitForEmail(); // up to 30 s
  if (!message) throw new Error('no sign-in email arrived');
  const { links } = await inbox.getLinks(message.id);
  const link = links.find((l) => l.url.includes('/verify'));
  if (!link) throw new Error('the email carries no sign-in link');

  await page.goto(link.url);
  await expect(page.getByText('Signed in')).toBeVisible();
});
```

Swap the page steps, the button's name, the link's path and the last check for your app's own. Three things trip a first test:

- **`toReceiveEmail` asserts and returns nothing.** `await expect(inbox).toReceiveEmail({ to: address, subject: /Welcome/ })` passes once that email arrives, for a test that only checks an email was sent. A test that reads the email waits for it with `waitForEmail`, as above.
- **An app that refuses `@example.com`.** A fixture address ends in `@example.com` unless `mailstestConfig` sets `addressDomain`, such as `addressDomain: 'example.org'`. The domain only names the address: the credential routes the mail.
- **One inbox, shared.** On Free, every test of the suite shares the inbox's latest 100 emails. A run that sends more than 100 before its tests read them pushes out its own mail, and those tests time out.

## Run it in CI {#ci}

Put `MAILSTEST_BASE_URL`, `MAILSTEST_API_KEY` and `MAILSTEST_INBOX_ID` in the repository's Actions secrets, and `SMTP_USER` and `SMTP_PASS` for the app. A GitHub Actions job:

```yaml github-actions
# .github/workflows/e2e.yml
name: e2e
on: [push, pull_request]
jobs:
  e2e:
    runs-on: ubuntu-latest
    env:
      MAILSTEST_BASE_URL: ${{ secrets.MAILSTEST_BASE_URL }}
      MAILSTEST_API_KEY: ${{ secrets.MAILSTEST_API_KEY }}
      MAILSTEST_INBOX_ID: ${{ secrets.MAILSTEST_INBOX_ID }}
      SMTP_HOST: smtp.mailstest.com
      SMTP_PORT: '465'
      SMTP_SECURE: 'true'
      SMTP_USER: ${{ secrets.SMTP_USER }}
      SMTP_PASS: ${{ secrets.SMTP_PASS }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
```

An app on the Resend door takes `RESEND_BASE_URL` and a `RESEND_API_KEY` secret in place of the `SMTP_*` lines. The job needs egress to `app.mailstest.com:443` for the SDK, and for the app to `smtp.mailstest.com:465`, or to `capture.mailstest.com:443` for a door. A wait whose request the network cuts sends it again on its own, within the wait's own timeout (30 seconds unless you pass `timeout`); a cut that outlasts it raises a `MailstestApiError`, not a timed-out result.

## Let an agent read the mail {#mcp}

The MCP endpoint is `https://app.mailstest.com/mcp`, over Streamable HTTP, with the workspace API key as the bearer: `Authorization: Bearer <key>`. Each client below reads the key from `MAILSTEST_API_KEY` in its environment, so no file you commit holds it.

**Claude Code.** The key reveal prints this line with the key written in; with the key in your environment it reads:

```sh claude-code
claude mcp remove mailstest; claude mcp add --transport http mailstest https://app.mailstest.com/mcp --header "Authorization: Bearer $MAILSTEST_API_KEY"
```

The first command drops an earlier registration (on a first run it reports there is none, and the second runs anyway). `claude mcp add` stores the key itself in your local Claude Code settings, outside the project. A project that shares its servers commits a `.mcp.json` at its root instead, which Claude Code fills from the environment as it starts:

```json claude-code-json
{
  "mcpServers": {
    "mailstest": {
      "type": "http",
      "url": "https://app.mailstest.com/mcp",
      "headers": { "Authorization": "Bearer ${MAILSTEST_API_KEY}" }
    }
  }
}
```

**Codex.**

```sh codex
codex mcp add mailstest --url https://app.mailstest.com/mcp --bearer-token-env-var MAILSTEST_API_KEY
```

Or in `~/.codex/config.toml`, with a tool timeout above the 55 seconds `wait_for_email` can hold one call:

```toml codex-toml
[mcp_servers.mailstest]
url = "https://app.mailstest.com/mcp"
bearer_token_env_var = "MAILSTEST_API_KEY"
tool_timeout_sec = 90
```

**Cursor.** In `.cursor/mcp.json` for the project, or `~/.cursor/mcp.json` for every project:

```json cursor
{
  "mcpServers": {
    "mailstest": {
      "url": "https://app.mailstest.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MAILSTEST_API_KEY}" }
    }
  }
}
```

Cursor reads `MAILSTEST_API_KEY` from its own environment, so start it from a shell that has the key.

The endpoint declares ten tools. `list_inboxes`, `list_emails`, `get_email`, `get_email_content` and `wait_for_email` read; `clear_emails` clears one address's mail; `mint_run_key`, `create_inbox`, `delete_inbox` and `revoke_run_key` provision a run of the agent's own. A prompt that walks the shared-inbox flow:

```text agent-prompt
Find my app's inbox with list_inboxes. Sign up in my app at http://localhost:3000 with a fresh address, t-signup-<eight random characters>@example.com. Then wait_for_email on that inbox with to set to the address, read the email with get_email, and give me the link it carries. End with clear_emails for that address.
```
