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.
Sign in and create the app's inbox
- Open app.mailstest.com, enter your email, and follow the sign-in link that
login@mailstest.comsends you. The link works once, within 15 minutes. - 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 to ask for access.
- 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.
- 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
.envsnippet: 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
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
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:
SMTP_HOST=smtp.mailstest.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=<username>
SMTP_PASS=<password>A nodemailer transport that reads them:
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 or the SendGrid door 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
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:
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
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:
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:
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
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:
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
Install the SDK beside Playwright. It needs Node 20.19+ or 22.12+ and @playwright/test 1.64 or later.
npm install -D @mailstest/playwright @playwright/testAdd the fixtures. Each test gets the app's inbox and an address that no other test shares:
// 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:
// 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:
// 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:
toReceiveEmailasserts 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 withwaitForEmail, as above.- An app that refuses
@example.com. A fixture address ends in@example.comunlessmailstestConfigsetsaddressDomain, such asaddressDomain: '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
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:
# .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 testAn 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
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:
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:
{
"mcpServers": {
"mailstest": {
"type": "http",
"url": "https://app.mailstest.com/mcp",
"headers": { "Authorization": "Bearer ${MAILSTEST_API_KEY}" }
}
}
}Codex.
codex mcp add mailstest --url https://app.mailstest.com/mcp --bearer-token-env-var MAILSTEST_API_KEYOr in ~/.codex/config.toml, with a tool timeout above the 55 seconds wait_for_email can hold one call:
[mcp_servers.mailstest]
url = "https://app.mailstest.com/mcp"
bearer_token_env_var = "MAILSTEST_API_KEY"
tool_timeout_sec = 90Cursor. In .cursor/mcp.json for the project, or ~/.cursor/mcp.json for every project:
{
"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:
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.