# MailSink

> Programmatic temporary email API. REST + MCP. Real receivable inboxes for QA tests and AI agents.

MailSink issues throwaway email addresses, catches verification mail, and extracts OTP codes or magic links. No IMAP, no browser automation, no SDK install. Designed to be called directly by test suites (Playwright, Cypress, Jest) and AI agents (Claude, ChatGPT, Cursor) over plain HTTP or via an MCP server.

## Base URL

`https://api.mailsink.dev`

## Auth

`Authorization: Bearer msk_...`

Provision a key at https://mailsink.dev/app/keys after GitHub OAuth.

## Core endpoints

- `POST /v1/inboxes` — create inbox. Returns `{ id, address, expires_at }`.
- `GET /v1/inboxes` — list active inboxes.
- `DELETE /v1/inboxes/{id}` — destroy inbox.
- `GET /v1/inboxes/{id}/messages` — list messages.
- `GET /v1/inboxes/{id}/latest-code` — extract latest OTP code.
- `GET /v1/inboxes/{id}/latest-link` — extract latest magic link.
- `GET /v1/inboxes/{id}/wait-for-code` — long-poll until OTP arrives.
- `GET /v1/messages/{id}` — full message body (JSON).
- `GET /v1/messages/{id}/raw` — raw .eml.
- `GET /v1/health` — liveness, no auth.

Anonymous tier (no signup, cookie-bound, single inbox per session): `POST /v1/anon/inbox`.

## Three-call quickstart

```bash
# 1. Create inbox
curl -X POST https://api.mailsink.dev/v1/inboxes \
  -H "Authorization: Bearer $MAILSINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"signup-test"}'

# 2. Send mail to the returned address (drive your flow under test).

# 3. Pull the OTP
curl https://api.mailsink.dev/v1/inboxes/inb_xxx/latest-code \
  -H "Authorization: Bearer $MAILSINK_API_KEY"
```

## MCP server

```bash
export MAILSINK_API_KEY=msk_...
npx -y @mailsink/mcp
```

Package: `@mailsink/mcp` on npm. Tools: `create_inbox`, `wait_for_email`, `get_verification_code`, `get_verification_link`, `list_messages`, `list_inboxes`, `get_message`, `delete_inbox`.

Repo: https://github.com/heocoi/mailsink-mcp

## Pricing

- Free — 50 inboxes/mo, 1h TTL, 60 req/min, 256 KB email size
- Pro $15/mo — 2,000 inboxes/mo, 24h TTL, 600 req/min, 1 MB, MCP
- Team $49/mo — 20,000 inboxes/mo, 7d TTL, 3,000 req/min, 5 MB, MCP

## Reference docs

- OpenAPI: https://mailsink.dev/docs/openapi.json
- HTML docs: https://mailsink.dev/docs/
- Markdown twin (homepage): https://mailsink.dev/index.md
- Blog (use cases, comparisons): https://mailsink.dev/blog/
- Changelog: https://mailsink.dev/changelog/
- Status: https://mailsink.dev/status/

## Agent-discovery endpoints (Level 5 Agent-Native, isitagentready.com 100/100)

- `/.well-known/agent-card.json` — A2A agent card
- `/.well-known/mcp/server-card.json` — MCP server card (SEP-1649)
- `/.well-known/agent-skills/index.json` — agent skills index
- `/.well-known/api-catalog` — RFC 9727 linkset
- `/.well-known/oauth-protected-resource` — RFC 9728
- `/.well-known/oauth-authorization-server` — RFC 8414

## Use cases

- Verify-code flows under Playwright / Cypress / Selenium / Puppeteer
- Stripe Checkout email verification in CI
- Magic-link login testing
- AI agents signing up to services they control to complete a task
- QA accounts on staging without rotating real inboxes

## Limits and honesty

- Extraction is "basic": ~70% accurate against common senders (Stripe, GitHub, Google, Clerk, Supabase, Auth0, Resend, AWS). Falls through to raw body otherwise.
- Free tier emails expire in 1 hour (TTL). Pro 24h, Team 7d. No backup copies.
- Outbound sending: not supported. Receive-only.
- Self-host: not yet. Hosted product first.
- Bring-your-own-domain: not yet shipped. Email `hello@mailsink.dev` for the waitlist.

## Contact

- Support / BYOD waitlist: hello@mailsink.dev
- Built on Cloudflare Workers + D1 + R2 by a small indie team.