# MailFixture

> MailFixture is a receive-only email and SMS inbox API for automated testing. Test suites and AI agents create private inboxes, trigger an application's real email flow, wait for delivery, and consume OTPs, links, message content, attachments, authentication verdicts, and spam scores as structured data.

MailFixture is designed for testing software you own or are authorized to test. It does not send, relay, reply to, or forward customer email or SMS.

Every public page on this site has a Markdown twin: append `.md` to the page URL (for example https://mailfixture.com/pricing.md; the root is https://mailfixture.com/index.md). Dead paths answer a real HTTP 404 whose body (for non-browser clients) is a Markdown map back to this file, the sitemap, and the docs.

## When to use MailFixture

Reach for MailFixture when a task needs to RECEIVE an email or SMS that another system sends, and read it back programmatically. Best-fit jobs:

- Completing a signup, login, password-reset, magic-link, or email-verification flow in a test or agent run that needs the one-time code or the link from an email the application under test just sent.
- Asserting in CI that a transactional email was delivered with the expected content, classified links, attachments, SPF/DKIM/DMARC results, or SpamAssassin verdict.
- Receiving an SMS one-time code on a dedicated, receive-only US phone number during an automated run (paid plans).
- Capturing the webhooks an application under test emits (capture hooks) and asserting on them with the same long-poll.
- Giving an AI agent a private, expiring address it owns for the duration of a task, so an email-verification wall stops the run no longer.

Not a fit: sending or relaying mail, registering accounts on services you do not control or are not authorized to test, receiving personal or production mail, or long-term mailbox storage (messages expire per the plan's retention).

## How an agent should call MailFixture

1. Authenticate with an API key (`mfx_…`) created in the dashboard at https://mailfixture.com/app/keys (a human signs up at https://mailfixture.com/signup; the free tier needs no card). Keep the key server-side — never in browser-run test code.
2. REST: send `Authorization: Bearer mfx_…` to https://api.mailfixture.com/v1. Typical loop: `POST /v1/inboxes` → drive the flow under test at the returned `email_address` → `GET /v1/inboxes/{id}/messages?wait=45` (the server holds the request until a message arrives) → read `extracted.otp.best` or `extracted.links[]`. SMS: `POST /v1/phone-numbers` then `GET /v1/phone-numbers/{id}/messages?wait=45`. Full contract: https://mailfixture.com/openapi.json; narrative: https://mailfixture.com/docs/api.
3. MCP: connect to https://mailfixture.com/mcp (Streamable HTTP, same Bearer key; server card at https://mailfixture.com/.well-known/mcp/server-card.json), e.g. `claude mcp add --transport http mailfixture https://mailfixture.com/mcp --header "Authorization: Bearer mfx_…"`. Tool loop: `create_inbox` → `wait_for_otp` / `wait_for_link` / `wait_for_message` (SMS and capture-hook equivalents exist); see https://mailfixture.com/docs/mcp.
4. Self-throttle on the `RateLimit` / `RateLimit-Policy` response headers; on 429 honor `Retry-After`. Errors are RFC 7807 `application/problem+json`; a 401 carries a `WWW-Authenticate: Bearer` challenge.

## Start here

- [Product overview](https://mailfixture.com/): Core capabilities and positioning
- [Guides](https://mailfixture.com/guides): Practical guides organized by framework and test flow
- [Automated email testing](https://mailfixture.com/guides/automated-email-testing): How mocked mailers, local SMTP capture, and real inbound inboxes divide the testing job
- [Playwright quickstart](https://mailfixture.com/docs): Create an inbox and complete an OTP test
- [Cypress quickstart](https://mailfixture.com/docs/cypress): Keep API credentials in Node and wait through cy.task
- [pytest quickstart](https://mailfixture.com/docs/pytest): Use a function-scoped inbox fixture
- [Pricing](https://mailfixture.com/pricing): Current plans, quotas, retention, SMS allowances, and overage rules

## Core capabilities

- Create isolated, expiring email inboxes through an authenticated REST API.
- Wait server-side for matching messages instead of using fixed sleeps or client polling loops.
- Extract ranked one-time-password candidates and classify verification, reset, and unsubscribe links.
- Follow an extracted verification link through an HTTPS-only, SSRF-guarded server action.
- Inspect rendered HTML, plain text, headers, raw MIME, and attachments.
- Assert SPF, DKIM, and DMARC results plus a SpamAssassin content score.
- Receive signed webhook notifications for message, SMS, and domain events.
- Capture the app-under-test's own outbound webhooks on public hook URLs and assert on them with the same long-poll.
- Use a customer-controlled test subdomain through custom MX records.
- Provision receive-only US phone numbers for SMS testing on eligible plans.
- Give AI agents the same testing workflow through a remote MCP server.

## Developer resources

- [MailFixture REST API reference](https://mailfixture.com/docs/api): Human-readable endpoint documentation — authentication, errors, rate limits, every /v1 resource
- [MailFixture OpenAPI 3.1 document](https://mailfixture.com/openapi.json): Machine-readable REST API description; the canonical Bearer-authenticated API origin is https://api.mailfixture.com/v1
- [MailFixture API authentication](https://mailfixture.com/docs/api#auth): Bearer API keys (`mfx_…`), created in the dashboard, shown once, hashed at rest
- [MailFixture API catalog](https://mailfixture.com/.well-known/api-catalog): RFC 9727 linkset pointing at the API, its OpenAPI description, and the MCP server
- [MailFixture JavaScript/TypeScript SDK](https://www.npmjs.com/package/mailfixture): npm package `mailfixture` (Node 18+, zero runtime dependencies)
- [MailFixture Python SDK](https://pypi.org/project/mailfixture/): PyPI package `mailfixture` (stdlib-only, Python 3.9+)
- [MailFixture changelog](https://mailfixture.com/changelog): What changed and when
- [Concepts: inboxes and TTLs](https://mailfixture.com/docs/concepts/inboxes): Inbox lifecycle and isolation
- [Concepts: messages and long-polling](https://mailfixture.com/docs/concepts/messages): Waiting, matching, retention, and message fields
- [Concepts: extraction](https://mailfixture.com/docs/concepts/extraction): OTP, link, authentication, and spam-score fields
- [Concepts: custom domains](https://mailfixture.com/docs/concepts/custom-domains): TXT verification and MX setup
- [Concepts: attachments](https://mailfixture.com/docs/concepts/attachments): Attachment metadata and indexed downloads
- [Concepts: webhooks](https://mailfixture.com/docs/concepts/webhooks): Events, signatures, retries, and payload boundaries
- [Concepts: capture hooks](https://mailfixture.com/docs/concepts/hooks): Inbound webhook capture — ingest URLs, matching, hard caps
- [Security](https://mailfixture.com/security): Data handling, rendering isolation, retention, and responsible disclosure
- [Service status](https://mailfixture.com/status): Current component status and incident history
- [Contact](https://mailfixture.com/contact): Support, abuse reports, security disclosures, privacy requests, and legal

## AI agents and MCP

- [MCP quickstart](https://mailfixture.com/docs/mcp): Connect an MCP client with a MailFixture API key
- [MailFixture MCP server](https://mailfixture.com/mcp): Streamable HTTP transport with Bearer authentication (41 tools covering the whole REST surface plus server-side wait loops)
- [MailFixture MCP server card](https://mailfixture.com/.well-known/mcp/server-card.json): Machine-readable server metadata (v1 Server Card schema; also served at https://mailfixture.com/.well-known/mcp-server-card and https://mailfixture.com/mcp/server-card)
- [AI agent email testing](https://mailfixture.com/guides/ai-agent-email-testing): Inbox ownership and agent workflow
- [Playwright OTP testing with MCP](https://mailfixture.com/guides/playwright-mcp-otp): Exploratory agent run followed by a deterministic CI test

## Testing guides

- [Parallel email testing](https://mailfixture.com/guides/parallel-email-testing)
- [Fake SMTP servers vs. a real test inbox](https://mailfixture.com/guides/fake-smtp-vs-test-inbox)
- [Playwright email testing](https://mailfixture.com/guides/playwright-email-testing)
- [Cypress email testing](https://mailfixture.com/guides/cypress-email-testing)
- [pytest email testing](https://mailfixture.com/guides/pytest-email-testing)
- [Selenium email testing](https://mailfixture.com/guides/selenium-email-testing)
- [Email OTP and 2FA flows](https://mailfixture.com/guides/otp-testing)
- [Email verification links](https://mailfixture.com/guides/email-verification-testing)
- [Magic-link login](https://mailfixture.com/guides/magic-link-testing)
- [Password-reset flows](https://mailfixture.com/guides/password-reset-testing)
- [Login-alert emails](https://mailfixture.com/guides/login-alert-testing)
- [SMS OTP flows](https://mailfixture.com/guides/sms-otp-testing)
- [Phone verification with vendor-sent SMS](https://mailfixture.com/guides/phone-verification-testing)
- [Transactional email testing](https://mailfixture.com/guides/transactional-email-testing)
- [SPF, DKIM, and DMARC in CI](https://mailfixture.com/guides/email-auth-testing)
- [Spam-score testing](https://mailfixture.com/guides/spam-score-testing)
- [Email attachment testing](https://mailfixture.com/guides/email-attachment-testing)
- [HTML email content testing](https://mailfixture.com/guides/html-email-testing)
- [Shared-domain blocklists and custom test domains](https://mailfixture.com/guides/disposable-email-detected)
- [Webhook testing with capture hooks](https://mailfixture.com/guides/webhook-testing)
- [Consuming signed email-event webhooks](https://mailfixture.com/guides/email-webhook-testing)

## Product boundaries

- MailFixture receives messages sent by the application under test; it is not an outbound email provider or SMTP sandbox relay.
- Shared test domains are intended for evaluation and may appear on disposable-email blocklists. Custom test subdomains remove dependence on a shared domain's reputation.
- Message and SMS data expire automatically according to the current plan's retention policy.
- Message bodies and SMS text are customer data and are intentionally excluded from webhook payloads.
- API and MCP access require a MailFixture API key. Never expose the key in browser-side test code.

## Comparisons

- [MailFixture vs Mailosaur](https://mailfixture.com/vs/mailosaur)
- [MailFixture vs MailSlurp](https://mailfixture.com/vs/mailslurp)
- [MailFixture vs Mailinator](https://mailfixture.com/vs/mailinator)
- [MailFixture vs Mailpit](https://mailfixture.com/vs/mailpit)
- [MailFixture vs Mailtrap](https://mailfixture.com/vs/mailtrap)