# Mailiator API

> Email testing API. Send to any @mailiator.dev address, receive real emails, and fetch them via REST API. Built for E2E tests, CI pipelines, and AI agents. One-time browser verification required.

Base URL: https://mailiator.dev/api

## Quick Start for AI Agents

No signup, no OAuth. Get started in 5 steps (one-time browser verification required):

Step 1 — Register (one-time, no auth):
  POST /api/register
  Body: {"name": "my-agent"}
  Response: {"api_key": "ml_xxx", "status": "pending", "verification_url": "https://mailiator.dev/verify?token=abc123", "message": "Open the verification URL in a browser to activate your API key.", "expires_in": 3600, ...}

Step 2 — Verify (human opens verification_url in browser):
  The verification page presents a challenge.
  Once completed, the API key is automatically activated.
  IMPORTANT: Present the verification_url to the user and ask them to open it in a browser.

Step 3 — Use any @mailiator.dev address or generate a random one:
  GET /api/generate-email
  Response: {"email": "gentle-fox-42@mailiator.dev"}
  Note: You can also use any address directly (e.g. my-test@mailiator.dev) — no registration needed for the address itself.

Step 4 — Wait for email (long polling, no loop needed):
  GET /api/inbox/gentle-fox-42@mailiator.dev?wait=10
  Headers: Authorization: Bearer ml_xxx
  Response: Array of emails (waits up to N seconds for arrival, returns immediately when email arrives)
  The ?wait parameter is in seconds (0-60). Adjust to suit your test — shorter waits keep tests fast.

Step 5 — Read email content:
  GET /api/emails/{id}
  Headers: Authorization: Bearer ml_xxx
  Response: Full email with html_content, text_content, and attachment metadata

## Authentication

Protected endpoints require an API key:
  Authorization: Bearer ml_xxx

Get a key: POST /api/register (no auth required, browser verification needed)
Key format: ml_ followed by 32 hex characters
Plans:
  Free: 50 requests/day, 7-day key expiry ($0)
  Starter: 500 requests/day, no key expiry ($9/mo or $90/yr)
  Pro: 3,000 requests/day, no key expiry ($19/mo or $190/yr)
Key status: pending (before verification) → active (after verification)

Error codes for key issues:
  KEY_PENDING (403) — Key not yet verified. Open the verification URL.
  KEY_EXPIRED (401) — Key expired. Register a new one.
  INVALID_KEY (401) — Key does not exist.

## Endpoints

### Register (Public, No Auth)
POST /api/register
Body: {"name": "optional-label"}
Returns: {"api_key": "ml_xxx", "status": "pending", "verification_url": "https://mailiator.dev/verify?token=...", ...}
Rate limit: 5 per hour per IP

### Generate Email (Public, No Auth)
GET /api/generate-email
Returns: {"email": "gentle-fox-42@mailiator.dev"}
Note: You can also send to any address @mailiator.dev directly — this endpoint just generates a random one.

### Check Inbox (Requires API Key)
GET /api/inbox/{email}
GET /api/inbox/{email}?wait=10    ← long polling (0-60 seconds)
Headers: Authorization: Bearer ml_xxx
Returns: Array of email summaries with id, recipient, sender, subject, received_at
The ?wait parameter (seconds) holds the connection until email arrives or timeout. No polling loop needed. Adjust the value to suit your test.

### Get Email by ID (Requires API Key)
GET /api/emails/{id}
Headers: Authorization: Bearer ml_xxx
Returns: Full email with html_content, text_content, attachments metadata
404 if not found

### Download Attachment (Requires API Key)
GET /api/attachments/{id}
Headers: Authorization: Bearer ml_xxx
Returns: Raw file content with appropriate Content-Type header

### Delete Emails (Requires API Key)
DELETE /api/emails/{email}
Headers: Authorization: Bearer ml_xxx
Deletes all emails for the given address

### Account Info (Requires API Key)
GET /api/account
Headers: Authorization: Bearer ml_xxx
Returns: {"plan": "free", "name": "my-agent", "requests_used": 42, "requests_limit": 50, "expires_at": "...", "created_at": "...", "subscription_status": null}

### Create Checkout (Requires API Key)
POST /api/checkout
Headers: Authorization: Bearer ml_xxx
Body: {"plan": "starter", "period": "monthly"}
Returns: {"checkout_url": "https://checkout.stripe.com/..."}
Opens a hosted payment page. After payment completes, the plan is activated automatically via webhook.
plan: "starter" or "pro". period: "monthly" or "annual" (annual saves ~17%).

### Billing Portal (Requires API Key)
POST /api/billing/portal
Headers: Authorization: Bearer ml_xxx
Returns: {"portal_url": "https://billing.stripe.com/..."}
Manage subscription: upgrade, downgrade, cancel, update payment method. Requires an active subscription.

### Health Check (Public)
GET /api/health
Returns: {"status": "ok"}

## Typical AI Agent Flow

1. POST /api/register {"name":"my-agent"} → get API key + verification URL
2. Present verification_url to user → user opens in browser → completes challenge → key activated
3. GET /api/generate-email → get a random address (or use any @mailiator.dev address)
4. Use the address in your E2E test (e.g., fill in a signup form)
5. GET /api/inbox/{email}?wait=10 → wait for email to arrive (no polling loop!)
6. GET /api/emails/{id} → read full content, extract verification link/code
7. DELETE /api/emails/{email} → clean up (optional — emails auto-delete after 30 min)

## MCP Server (Model Context Protocol)

AI agents that support MCP (Claude Code, Cursor, VS Code Copilot, etc.) can connect directly:

MCP endpoint: https://mailiator.dev/mcp
Transport: Streamable HTTP (POST/GET/DELETE)

Available tools:
- generate_email — Generate a random @mailiator.dev address (no auth)
- check_inbox(email, api_key, wait?) — Check inbox with optional long polling (0-60s)
- get_email(id, api_key) — Get full email content by ID
- delete_emails(email, api_key) — Delete all emails for an address
- register(name?) — Register for an API key (returns pending key + verification URL)
- checkout(api_key, plan, period?) — Create checkout session for paid plan (returns checkout_url)
- billing_portal(api_key) — Create billing portal session (returns portal_url)
- account_info(api_key) — Get account info, plan, quota, subscription status

MCP config example (for Claude Code, Cursor, etc.):
  {
    "mcpServers": {
      "mailiator": {
        "type": "streamable-http",
        "url": "https://mailiator.dev/mcp"
      }
    }
  }

## OpenAPI Spec

Full OpenAPI 3.0 specification: https://mailiator.dev/api/openapi.json
AI plugin manifest: https://mailiator.dev/.well-known/ai-plugin.json