# fixture.email — Email Testing API

> fixture.email is hosted email-testing infrastructure for developers and the AI agents that build with them: create disposable mailboxes on a real domain, send or trigger email, then assert on subjects, bodies, links, headers and SPF/DKIM/DMARC results. Drive it over this HTTP API or the fixture.email MCP server.

AI-native email testing, built for agents — the AI-first alternative to Mailosaur.

## Start here — connect your agent

- **MCP endpoint (recommended for agents)**: `https://mcp.fixture.email/mcp` — remote streamable HTTP, no transport session and no handshake. OAuth-capable clients can add this URL without a static header and sign in as the account owner; clients that accept explicit headers can use an org-scoped `X-API-Key`.
- **API-key clients, one command**: `claude mcp add --transport http fixture-email https://mcp.fixture.email/mcp --header "X-API-Key: $KEY"` (Cursor and Codex config below, under Getting Started).
- **This document (full HTTP API reference)**: https://fixture.email/llms.txt — public, no key required.
- **Human-readable docs**: https://fixture.email/docs

## About

fixture.email is programmable email-testing infrastructure for software teams and the AI agents that build with them: create disposable mailboxes on demand, trigger the emails your application sends, and assert on everything that arrives — subjects, bodies, links, and headers. Humans and autonomous agents onboard the same way — a human signs up through hosted checkout and pastes a starter prompt, and from there an agent drives the whole email-testing flow over this API and the customer MCP, with no human in the loop.

## Base URL

- **Current Environment**: https://send.fixture.email

## Authentication

All `/api/*` endpoints require authentication via the `X-API-Key` header:

```
X-API-Key: {your-api-key}
```

**It must be that header, and it is enforced at the edge — not by the application.** A request to `/api/*` carrying no `X-API-Key` (or one shorter than 32 characters) is rejected before it reaches the API, and the reply is Cloudflare's generic HTML error page with status `403` — **not** a JSON error from this service. If you get back HTML titled "Attention Required!", you are almost certainly sending the wrong header: this API does **not** use `Authorization: Bearer`. Add `X-API-Key` and you will reach the application, which answers in JSON.

That HTML `403` says nothing about your IP, your user agent, or bot detection, and retrying from a different network will not change it. Agents calling from datacenter IPs with non-browser clients are the expected audience here and are not blocked for being agents.

Keys are org-scoped. Mint one in your browser at the keys portal (the `keys` host the MCP's `whoami` links to — sign in with your SSO, Google, GitHub, or email) with a required name and expiry, or via `POST /api/keys` (optional `expiresIn`). A key is shown only once at creation, is never recoverable, and stays valid until it expires or you revoke it (the `revoke_api_key` MCP tool or `DELETE /api/keys/{keyId}`).

The following endpoints do NOT require authentication:
- `GET /health` - Health check
- `GET /llms.txt` - This documentation

### What is public, and what needs a key

**This document is the public API contract.** `GET /llms.txt` (https://fixture.email/llms.txt) and `GET /health` are the only unauthenticated endpoints; everything under `/api/*` needs your org-scoped `X-API-Key`.

That **includes the API description endpoints**: `GET /api/openapi.json` (the OpenAPI document) and `GET /api/docs` (its Swagger UI) are authenticated routes like any other. Being under `/api/*`, a keyless request to either is stopped at the edge and returns the HTML `403` described above — not a `401`, and not JSON. They are not a public discovery surface and are deliberately not advertised as one — our `/.well-known/api-catalog` and `Link: rel="service-doc"` header point at this document instead. So: build against the reference below, and read the OpenAPI document only once you hold a key and can send it.

### Check your credential before you do any work

`GET https://send.fixture.email/api/usage` is the **documented preflight for a CI run or an agent session**. Call it once at the start; branch on the status code:

| Status | Meaning | What to do |
|---|---|---|
| `200` | key valid, org entitled | proceed — and read `pressure.status`, below |
| `401` | the key is wrong, revoked or expired | stop; mint a new key |
| `402` | the org is unentitled | stop; the body names the checkout and portal URLs |
| HTML `403` | no `X-API-Key` header reached the edge at all | add the header — see Authentication above |

It is the cheapest gated call in the API: **read-only, no side effects, and it consumes no quota**, while still exercising the whole auth + entitlement path. One call names an unusable credential up front instead of letting it surface deep inside test setup after clone, install and provisioning.

The `200` body also tells you what is about to run out, on **both** axes — a trial ends at whichever ceiling arrives first:

- `pressure.status` — read this one field to decide whether to act. `ok` / `approaching_limit` / `exhausted`.
- `pressure.sends` and `pressure.trialWindow` — then read these to see *which* ceiling is closing.
- `trial.endsAt` with `trial.endsAtSource` — `confirmed` is safe to schedule against; `provisional` is our own checkout-time estimate and should be treated as an **upper** bound. A run already under way when `endsAt` passes is not cut off mid-execution: access continues for a short settle window after the end, so a preflight taken shortly past `endsAt` can still answer `200`. Do not read that as the trial having been extended — schedule against `endsAt`.
- `organizationId` — which org this key actually resolved to. Two keys for two different orgs are otherwise indistinguishable to their holder.

---

## Quick Reference - All Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /health | Health check (no auth) |
| GET | /llms.txt | This documentation (no auth) |
| GET | /api/openapi.json | OpenAPI document (X-API-Key required; not public) |
| GET | /api/docs | Swagger UI for that document (X-API-Key required; not public) |
| POST | /api/mailboxes | Create mailbox |
| GET | /api/mailboxes/{mailbox} | Get mailbox state (enabled, cleanup, domain, label) |
| DELETE | /api/mailboxes/{mailbox} | Disable mailbox (does not schedule cleanup) |
| POST | /api/mailboxes/{mailbox}/safe-cleanup | Schedule cleanup without disabling |
| POST | /api/mailboxes/{mailbox}/enable | Enable mailbox |
| POST | /api/mailboxes/{mailbox}/disable | Disable mailbox |
| POST | /api/mailboxes/{mailbox}/cancel-cleanup | Cancel scheduled cleanup |
| POST | /api/send | Send email (JSON payload) |
| POST | /api/send/upload | Send email (raw .eml upload) |
| POST | /api/attachments/upload | Upload large attachment |
| GET | /api/status/{uuid} | Check email status |
| GET | /api/messages | List messages with filters |
| GET | /api/messages/{emailId}/content | Get parsed email body |
| GET | /api/messages/{emailId}/raw | Get presigned URL for .eml download |
| GET | /api/usage | Get outbound send usage vs per-org quota |
| POST | /api/keys | Create an org-scoped API key |
| GET | /api/keys | List API keys (never the secret) |
| DELETE | /api/keys/{keyId} | Revoke an API key |
| POST | /api/callbacks | Register a signed webhook callback |
| GET | /api/callbacks | List callbacks (never the signing secret) |
| DELETE | /api/callbacks/{id} | Delete a callback |

---
## Getting Started

Two ways to drive this API:

1. **MCP (recommended for agents).** Point an MCP client at `https://mcp.fixture.email/mcp` for the tools (`create_mailbox`, `send_email`, `wait_for_message`, `wait_for_send_outcome`, `get_message`, `list_messages`, …). OAuth-capable clients follow the sign-in challenge and authenticate the single account owner without minting an API key or a seat. Local, automation, and other clients that accept explicit headers can instead send an org-scoped `X-API-Key`; use explicit API-key grants when access must be narrowed by category. **Over MCP you never write a polling loop:** `wait_for_message` returns the mail as soon as it arrives (and immediately if it already has), and `wait_for_send_outcome` returns a send's terminal outcome. The HTTP polling below is only for clients that are not using the MCP.
2. **HTTP API with an `X-API-Key`.** Direct HTTP remains key-authenticated. Mint a key in your browser at the keys portal (the `keys` host the MCP's `whoami` links to — sign in with your SSO, Google, GitHub, or email; required name + expiry, shown once), or via `POST /api/keys` once you already hold a key.

### Hello world — receive an email in 3 steps

```bash
KEY=your-api-key

# 1. Create a mailbox -> a unique inbox address
MAILBOX=$(curl -s -X POST https://send.fixture.email/api/mailboxes -H "X-API-Key: $KEY" | jq -r .mailbox)

# 2. Send anything to  test+$MAILBOX@fixture.email  (from your app, or via the API)
curl -s -X POST https://send.fixture.email/api/send -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"to":"test+'"$MAILBOX"'@fixture.email","subject":"hello","text":"hi"}'

# 3. Assert it arrived -> subject, body, links, headers
curl -s "https://send.fixture.email/api/messages?mailbox=$MAILBOX&status=received" -H "X-API-Key: $KEY"
```

### Connect your agent

The customer MCP is a remote streamable-HTTP server. In an OAuth-capable client, add `https://mcp.fixture.email/mcp` without a static header and complete the account-owner sign-in. OAuth creates no API key and no additional seat. For a client that accepts explicit headers, swap `$KEY` below for a real org-scoped key:

- **Claude Code**: `claude mcp add --transport http fixture-email https://mcp.fixture.email/mcp --header "X-API-Key: $KEY"`
- **Cursor** — `.cursor/mcp.json`:

```json
{ "mcpServers": { "fixture-email": { "url": "https://mcp.fixture.email/mcp", "headers": { "X-API-Key": "$KEY" } } } }
```

- **Codex** — `~/.codex/config.toml`:

```toml
[mcp_servers.fixture-email]
url = "https://mcp.fixture.email/mcp"
http_headers = { "X-API-Key" = "$KEY" }
```

### Generate a reusable email-testing skill

Once the flow round-trips, capture it as a reusable, portable skill in your repo so any teammate's agent repeats it — the file format is per-tool, the steps identical:

- **Claude Code**: a `.claude/skills/email-testing/SKILL.md` (a name, a "Load when …" description, and the steps).
- **Cursor**: a `.cursor/rules/email-testing.mdc` rule.
- **Codex**: an `AGENTS.md` section.

Record: create a mailbox, `send_email` an internal test message to its subaddress (off-quota, no app wiring), then a single `wait_for_message` (never a retry loop) and `get_message` to assert subject, body, links, and headers. Add `wait_for_send_outcome` when the test needs to prove the send itself reached `sent` / `failed`.

Full receive/send/internal-routing detail is in the sections below.

---

## Paying for Access

Every `/api/*` product route requires your organization to hold an **active subscription or a live trial**. A call from an org without one is rejected with **`402 Payment Required`** and a body naming why, and how to pay.

The usual case by far is a **trial that reached its end date**:

```json
{
  "error": "No active subscription or trial for this organization. Subscribe or update billing to continue.",
  "entitled": false,
  "reason": "trial_expired",
  "status": "trial_expired",
  "checkoutUrl": "https://fixture.email/api/billing/checkout",
  "billingPortalUrl": "https://fixture.email/api/billing/portal"
}
```

- `entitled` — always `false` on a 402. It is derived from the same decision that refused the call, so it can never disagree with the status code.
- `reason` — **the field to branch on.** A closed set naming which branch refused you:
  - `"trial_expired"` — the trial reached its end date and that end is confirmed — by far the most common lapse
  - `"no_active_subscription"` — the subscription is in a state that grants no access (`canceled`, `past_due`, `unpaid`, `incomplete`, `paused`, …), or the organization never had one
- `status` — the org's *effective* billing state, not a stored label: an expired trial reports `"trial_expired"` (never `"trialing"`), and a lapsed subscription reports what it actually is (`"canceled"`, `"past_due"`, `"unpaid"`, `"incomplete"`, `"paused"`, …). Informational and open-ended — do not switch on it.
- `checkoutUrl` — hosted checkout; open in a browser to subscribe with a card.
- `billingPortalUrl` — the billing portal to manage or restore a subscription.

A 402 never carries `"status": "active"` or `"status": "trialing"`; if you are matching on the old shape, match on the 402 status code or on `reason` instead.

Hosted checkout collects your card; your trial starts (or the subscription activates) on completion.

Billing routes are the only `/api/*` routes reachable while unentitled, so a lapsed org can always pay its way back in. After paying, retry your original call (or `GET https://send.fixture.email/api/usage`) — entitlement flips within seconds of the checkout being confirmed. The customer MCP server reports the same `entitled` / `reason` / `status` and the same `checkoutUrl` in its `payment_required` error.

---

## Core Concepts

### Email Address Format

All emails use **subaddress-based mailbox routing** (RFC 5233):

```
{anything}+{mailbox}@fixture.email
```

- **mailbox**: 16-character lowercase alphanumeric ID (e.g., `x7k2m9pqr3s4t5u6`)
- **{anything}**: Can be any valid local part - only the mailbox ID after `+` matters

Examples:
- `test+x7k2m9pqr3s4t5u6@fixture.email`
- `signup+x7k2m9pqr3s4t5u6@fixture.email`
- `newsletter+x7k2m9pqr3s4t5u6@fixture.email`

All three addresses route to the same mailbox (`x7k2m9pqr3s4t5u6`).

### Mailboxes

Mailboxes are isolated containers for email testing:
- Create via `POST /api/mailboxes` (returns random 16-char ID)
- Each mailbox has its own storage namespace
- Only registered mailboxes can receive emails
- Delete via `DELETE /api/mailboxes/{mailbox}` to clean up

**Mailbox Deletion (Soft Delete with Grace Period):**
- Mailboxes are **disabled** (enabled = 0) when deleted via API
- Workflow timer (CLEANUP_SLEEP_DURATION) handles grace period - not database
- During grace period: In-flight emails are rejected (mailbox is disabled)
- After grace period: Mailbox and all data are permanently deleted
- This prevents race conditions when tests delete mailboxes while emails are processing

### Email Statuses

- `queued` - Email is queued for sending (initial state after POST /api/send)
- `sent` - Email has been sent successfully to external recipient
- `received` - Email has been received:
  - Inbound emails from external senders
  - **Internal routing**: Emails sent to `{anything}+{mailbox}@fixture.email` are routed internally and marked `received` in the recipient's mailbox
- `failed` - Email processing failed:
  - Sending to non-existent mailbox on test domain
  - Workflow processing errors

---

## Receiving Emails (Inbound)

To receive emails for testing (e.g., verification emails, notifications):

1. **Create a mailbox**: `POST /api/mailboxes` returns `{ "mailbox": "x7k2m9pqr3s4t5u6" }`
2. **Use the email address**: Send emails to `anything+x7k2m9pqr3s4t5u6@fixture.email`
3. **Poll for received emails**: `GET /api/messages?mailbox=x7k2m9pqr3s4t5u6&status=received`

Emails sent to addresses with unregistered mailbox IDs are silently dropped.

### Receive Email Example

```bash
# 1. Create a mailbox
MAILBOX=$(curl -s -X POST https://send.fixture.email/api/mailboxes \
  -H "X-API-Key: $API_KEY" | jq -r '.mailbox')

# 2. Use this address in your application: test+$MAILBOX@fixture.email

# 3. Poll for received emails
curl -s "https://send.fixture.email/api/messages?mailbox=$MAILBOX&status=received" \
  -H "X-API-Key: $API_KEY"
```

---

## Sending Emails (Outbound)

### Method 1: API Creation (POST /api/send)

Build email from JSON payload:

```bash
curl -X POST https://send.fixture.email/api/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Test Email",
    "text": "Plain text body",
    "html": "<p>HTML body</p>"
  }'
```

**Smart `from` Address Handling:**

| You Provide | API Behavior | Result |
|-------------|--------------|--------|
| Nothing | Generate random local + create new mailbox | `r4nd0m+x7k2m9pqr3s4t5u6@fixture.email` |
| Just local (e.g., `newsletter`) | Use local + create new mailbox | `newsletter+x7k2m9pqr3s4t5u6@fixture.email` |
| Full address with valid mailbox | Validate mailbox exists, use as-is | `newsletter+x7k2m9pqr3s4t5u6@fixture.email` |
| Full address with unknown mailbox | Return 400 error | - |

### Method 2: Raw .eml Upload (POST /api/send/upload)

Upload a raw RFC 822 .eml file. Supports replaying external emails (e.g., saved from Gmail):

```bash
# Upload your own .eml file
curl -X POST https://send.fixture.email/api/send/upload \
  -H "X-API-Key: $API_KEY" \
  -F "file=@email.eml"

# Replay external .eml with overridden From/To
curl -X POST https://send.fixture.email/api/send/upload \
  -H "X-API-Key: $API_KEY" \
  -F "file=@saved-gmail.eml" \
  -F "from=sender@fixture.email" \
  -F "to=recipient@example.com"
```

**How External .eml Replay Works:**
- The original `.eml` file is stored **unmodified** (preserves source for audit/reuse)
- From/To overrides are stored as metadata
- At send time, the workflow extracts body, subject, attachments from the original `.eml`
- Rebuilds MIME message using the override From/To addresses
- External From addresses (e.g., `someone@gmail.com`) are transformed to `{local}+{mailbox}@fixture.email`
- Multiple recipients supported: `to=alice@example.com, bob@example.com`

### Large Attachments

For attachments >= 1MB, upload first then reference by ID:

```bash
# 1. Upload attachment
ATTACHMENT=$(curl -s -X POST https://send.fixture.email/api/attachments/upload \
  -H "X-API-Key: $API_KEY" \
  -F "file=@large-file.pdf" \
  -F "mailbox=$MAILBOX" | jq -r '.attachmentId')

# 2. Send email with attachment reference
curl -X POST https://send.fixture.email/api/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender+'$MAILBOX'@fixture.email",
    "to": "recipient@example.com",
    "subject": "Email with large attachment",
    "text": "See attached file",
    "attachments": [{
      "name": "large-file.pdf",
      "attachmentId": "'$ATTACHMENT'",
      "contentType": "application/pdf"
    }]
  }'
```

---

## Internal Routing (Test-to-Test)

When you send an email **to** an address on the test domain (`{anything}+{mailbox}@fixture.email`), the email is routed internally:

1. Email is NOT sent externally
2. Status becomes `received` (not `sent`)
3. Email appears in the **recipient's** mailbox (not sender's)

This enables end-to-end email testing without external delivery.

### Internal Routing Example

```bash
# Create RECIPIENT mailbox (this is where email will be delivered)
RECIPIENT_MAILBOX=$(curl -s -X POST https://send.fixture.email/api/mailboxes \
  -H "X-API-Key: $API_KEY" | jq -r '.mailbox')

# Send to the recipient's test domain address
EMAIL_ID=$(curl -s -X POST https://send.fixture.email/api/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test+'$RECIPIENT_MAILBOX'@fixture.email",
    "subject": "Internal Test",
    "text": "This is routed internally"
  }' | jq -r '.emailId')

# Poll for RECEIVED status (not sent!)
while true; do
  STATUS=$(curl -s "https://send.fixture.email/api/status/$EMAIL_ID" \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  if [ "$STATUS" = "received" ]; then
    echo "Email received in recipient mailbox!"
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "Email failed - check if recipient mailbox exists"
    break
  fi
  sleep 3
done

# Email is now in RECIPIENT's mailbox
curl -s "https://send.fixture.email/api/messages?mailbox=$RECIPIENT_MAILBOX&status=received" \
  -H "X-API-Key: $API_KEY" | jq '.messages[0]'
```

**Important**: If the recipient mailbox doesn't exist, the email status becomes `failed`.

---

## API Reference

### Health Check

```
GET /health
```

No authentication required.

**Response:**
```json
{
  "status": "ok",
  "service": "email-test-send",
  "environment": "production"
}
```

---

### Create Mailbox

```
POST /api/mailboxes
```

Creates a new mailbox with a random 16-character ID. No request body needed.

**Response:**
```json
{
  "mailbox": "x7k2m9pqr3s4t5u6"
}
```

---

### Get Mailbox

```
GET /api/mailboxes/{mailbox}
```

Get a mailbox's current state.

**Response:**
```json
{
  "mailbox": "x7k2m9pqr3s4t5u6",
  "domain": "fixture.email",
  "label": null,
  "enabled": true,
  "scheduledForCleanup": false,
  "createdAt": 1730961190634
}
```

- `label`: optional mailbox label (null if unset)
- `scheduledForCleanup`: `true` once `POST /api/mailboxes/{mailbox}/safe-cleanup` has been called
- `createdAt`: Unix timestamp in **milliseconds**

**Status Codes:**
- `200` - Mailbox found
- `404` - Mailbox not found
- `401` - Missing or invalid API key

---

### Delete Mailbox

```
DELETE /api/mailboxes/{mailbox}
```

Disables the mailbox. This does NOT schedule cleanup - cleanup must be scheduled separately via `/safe-cleanup` endpoint.

**Behavior:**
1. Disables the mailbox (disabled mailboxes reject new emails immediately)
2. Takes effect immediately
3. Does NOT trigger cleanup
4. Does NOT schedule the mailbox for cleanup

**Response:**
```json
{
  "success": true
}
```

**Status Codes:**
- `200` - Mailbox disabled
- `404` - Mailbox not found

**Note**: If mailbox is already disabled, returns success (idempotent). To schedule cleanup, use `POST /api/mailboxes/{mailbox}/safe-cleanup`.

---

### Schedule Mailbox Cleanup

```
POST /api/mailboxes/{mailbox}/safe-cleanup
```

Schedules mailbox cleanup workflow without disabling the mailbox. Allows in-flight emails to complete before deletion.

**Request Body**: Required when using `Content-Type: application/json`. Send at least `{}` (empty object). Sending no body with that header returns `400 Malformed JSON`.

```json
{}
```

Or with optional duration:
```json
{
  "duration": "30 minutes"
}
```

- `duration` (optional): Duration override (e.g., "30 minutes", "1 hour", "2 days")
- If not provided, uses `CLEANUP_SLEEP_DURATION` from environment
- Duration format: `"{number} {unit}"` (e.g., "30 minutes", "1 hour")
- Supported units: second, minute, hour, day, week

**Behavior:**
1. Schedules the mailbox for cleanup after the grace period
2. Mailbox remains enabled during the grace period (allows in-flight emails)
3. After the grace period, all stored emails and metadata for the mailbox are permanently deleted
4. Can be cancelled via `POST /api/mailboxes/{mailbox}/cancel-cleanup` any time before the grace period ends

**Response:**
```json
{
  "success": true,
  "duration": "30 minutes"
}
```

**Status Codes:**
- `200` - Cleanup scheduled
- `400` - Malformed JSON (e.g. `Content-Type: application/json` with no body—send at least `{}`), or invalid duration format
- `404` - Mailbox not found

---

### Enable Mailbox

```
POST /api/mailboxes/{mailbox}/enable
```

Immediately enables mailbox (`enabled = 1`). This is an independent operation that does NOT affect cleanup scheduling.

**Response:**
```json
{
  "success": true,
  "warning": "Mailbox enabled, but this mailbox is scheduled for removal"
}
```

The `warning` field is only present if the mailbox is scheduled for cleanup (`scheduledForCleanup = 1`).

**Status Codes:**
- `200` - Mailbox enabled
- `404` - Mailbox not found (cleanup completed, mailbox removed)

---

### Disable Mailbox

```
POST /api/mailboxes/{mailbox}/disable
```

Immediately disables mailbox (`enabled = 0`). This is an independent operation that does NOT schedule cleanup.

**Response:**
```json
{
  "success": true
}
```

**Status Codes:**
- `200` - Mailbox disabled
- `404` - Mailbox not found (cleanup completed, mailbox removed)

---

### Cancel Scheduled Cleanup

```
POST /api/mailboxes/{mailbox}/cancel-cleanup
```

Cancels scheduled mailbox cleanup by setting `scheduledForCleanup = 0`. Only works before cleanup workflow reaches deletion steps.

**Response:**
```json
{
  "success": true
}
```

**Behavior:**
- Cancels the scheduled cleanup for the mailbox
- If cancelled before the grace period ends, no emails or metadata are deleted
- Once the grace period has elapsed, cancellation may no longer take effect

**Status Codes:**
- `200` - Cleanup cancelled
- `404` - Mailbox not found (cleanup completed, mailbox removed)

---

### Send Email (API Creation)

```
POST /api/send
```

**Request Body:**
```json
{
  "from": "sender+mailbox@fixture.email",
  "to": "recipient@example.com",
  "subject": "Test Email",
  "text": "Plain text body",
  "html": "<p>HTML body</p>",
  "cc": "cc@example.com",
  "bcc": ["bcc1@example.com", "bcc2@example.com"],
  "attachments": [
    {
      "name": "small-file.txt",
      "content": "base64-encoded-content",
      "contentType": "text/plain"
    },
    {
      "name": "large-file.pdf",
      "attachmentId": "uuid-from-upload",
      "contentType": "application/pdf"
    }
  ],
  "headers": {
    "X-E2E-Config": "value"
  }
}
```

**Fields:**
- `from` (optional): See smart from handling above
- `to` (required): Recipient email address
- `subject` (required): Email subject
- `text` (optional): Plain text body
- `html` (optional): HTML body
- `cc` (optional): CC recipient(s); single email or array of emails
- `bcc` (optional): BCC recipient(s); single email or array of emails
- `attachments` (optional): Array of attachments
  - `name`: Filename
  - `contentType`: MIME type
  - `content`: Base64-encoded content (for files < 1MB)
  - `attachmentId`: ID from upload endpoint (for files >= 1MB)
- `headers` (optional): `Record<string, string>` of custom MIME headers (e.g. `X-E2E-Config`). Persisted in the .eml and returned by `GET /api/messages/{emailId}/content`.

**Response:**
```json
{
  "emailId": "550e8400-e29b-41d4-a716-446655440000",
  "mailbox": "x7k2m9pqr3s4t5u6",
  "from": "sender+x7k2m9pqr3s4t5u6@fixture.email"
}
```

**Status Codes:**
- `200` - Email queued successfully
- `400` - Invalid payload or unknown mailbox
- `403` - A recipient is on your suppression list, or your account is suspended for excessive bounces/complaints
- `413` - Base64 attachment exceeds 1MB limit

**Bounces, complaints & suppression:**
A real external bounce or spam complaint adds that recipient to your org's suppression list and emits a `email.bounced` / `email.complained` callback. A later send to a suppressed recipient is rejected with `403` (and emits `email.suppressed`). Sustained high bounce/complaint rates auto-suspend the org — all sends then return `403` until support restores it.

**Simulated outcome addresses (testing):**
Send to a reserved address on `fixture.email` to exercise outcome handling WITHOUT a real send (no deliverability or reputation impact). The message is never delivered — a terminal status is synthesized and the matching callback event fires:
- `delivered@fixture.email` → status `sent`, event `email.sent`
- `bounced@fixture.email` → status `failed`, event `email.bounced`
- `complained@fixture.email` → status `sent`, event `email.complained`
- `suppressed@fixture.email` → status `failed`, event `email.suppressed`
Sub-addressing labels work (`delivered+signup@fixture.email`); an address that carries a valid mailbox subaddress (`delivered+<mailbox>@fixture.email`) routes to that mailbox as normal instead. Simulated sinks can't be mixed with real recipients in one send, and never count against your send quota.

---

### Send Email (Raw Upload)

```
POST /api/send/upload
```

Upload raw .eml file (RFC 822 format). Supports replaying external emails with From/To overrides.

**Request:** `multipart/form-data`
- `file`: Raw .eml file (required)
- `from`: Override From address (optional, uses .eml header if not provided)
- `to`: Override To address(es) - comma-separated for multiple recipients (optional, uses .eml header if not provided)

**From Address Handling:**
- If `from` has valid mailbox subaddress → validates mailbox exists
- If `from` is external (e.g., `someone@gmail.com`) → auto-creates mailbox, sends from `{local}+{mailbox}@fixture.email`
- If `from` not provided → parses from .eml header with same logic

**Response:**
```json
{
  "emailId": "550e8400-e29b-41d4-a716-446655440000",
  "mailbox": "x7k2m9pqr3s4t5u6",
  "from": "sender+x7k2m9pqr3s4t5u6@fixture.email"
}
```

**Status Codes:**
- `200` - Email queued
- `400` - Invalid .eml format, missing To header, or a form field sent with the wrong type (`file` must be a file part; `from`/`to` must be text parts)
- `413` - File exceeds 25MB limit

---

### Upload Attachment

```
POST /api/attachments/upload
```

Upload large attachment before sending email.

**Request:** `multipart/form-data`
- `file`: File to upload (max 25MB)
- `mailbox`: Mailbox ID (required)

**Response:**
```json
{
  "attachmentId": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "size": 1048576,
  "contentType": "application/pdf"
}
```

**Status Codes:**
- `200` - Attachment stored
- `400` - Missing/invalid mailbox, or a form field sent with the wrong type (`file` must be a file part; `mailbox` must be a text part)
- `413` - File exceeds 25MB, or the mailbox attachment quota is exceeded
- `429` - Attachment upload rate limit exceeded

---

### Check Email Status

```
GET /api/status/{uuid}
```

Get status and metadata for a specific email.

**Response:**
```json
{
  "emailId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "mailbox": "x7k2m9pqr3s4t5u6",
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "subject": "Test Email",
  "time": 1730961190634,
  "messageId": "msg-abc123",
  "subaddress": "test123",
  "spfResult": "pass",
  "dkimResult": "pass",
  "dmarcResult": "pass"
}
```

- `time`: Unix timestamp in **milliseconds** (e.g. `Date.now()` in JavaScript)
- `spfResult` / `dkimResult` / `dmarcResult` (optional): verdicts Cloudflare Email Routing (authserv-id `mx.cloudflare.net`) stamped on the inbound mail, taken only from the topmost `Authentication-Results` header — a sender-supplied one is ignored. `dkimResult` reports the signature aligned with the From domain. Omitted when no such stamp exists (outbound, uploaded or internally routed mail): absent means unknown, never pass.

**Status Codes:**
- `200` - Email found
- `404` - Email not found

**Polling Recommendations (HTTP callers only — over the MCP use `wait_for_send_outcome` / `wait_for_message`, one call, no loop):**
- Poll every 2-3 seconds
- Allow 20-30 retries for external sends (~60-90 seconds total)
- For internal routing, status changes faster (10-20 retries usually sufficient)
- Check for `failed` status to handle errors early

---

### Get Email Content

```
GET /api/messages/{emailId}/content
```

Retrieve the parsed body content of an email, including extracted links.

**Response:**
```json
{
  "html": "<html>Full HTML content...</html>",
  "text": "Plain text content...",
  "subject": "Email Subject",
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "links": ["https://example.com/verify?token=abc", "https://example.com/unsubscribe"],
  "headers": {
    "Message-ID": "<abc123@example.com>",
    "X-E2E-Config": "..."
  },
  "spfResult": "pass",
  "dkimResult": "pass",
  "dmarcResult": "pass"
}
```

- `html`: HTML body (null if email has no HTML part). Server-sanitized: `<script>` tags, `on*` event handlers, and any `href`/`src`/`action` whose URL scheme is not `http`, `https`, `mailto`, `tel` or `cid` (so every `javascript:`/`data:`/`vbscript:`, however it is spelled) are stripped. Consumers rendering this into a DOM should still re-sanitize with a full library.
- `text`: Plain text body (null if email has no text part)
- `links`: All href values extracted from the **sanitized** HTML (entities like `&amp;` automatically decoded; dangerous URL schemes already filtered)
- `headers`: `Record<string, string>` of MIME headers from the stored .eml (e.g. `Message-ID`, custom `X-E2E-Config` from POST /api/send)
- `spfResult` / `dkimResult` / `dmarcResult`: nullable strings — Cloudflare Email Routing's verdicts, as in Get Email Status; null (unknown, never pass) when no Cloudflare stamp exists. Do not re-derive them from `headers`, which can include a sender-forged `Authentication-Results`.

**Status Codes:**
- `200` - Content retrieved
- `404` - Email not found

---

### Get Raw Email (.eml)

```
GET /api/messages/{emailId}/raw
```

Get a presigned URL to download the raw .eml file.

**Response:**
```json
{
  "url": "https://<download-host>/...",
  "expiresIn": 900
}
```

The URL can be used to download the complete RFC 822 .eml file directly. No authentication required for the download URL, but it expires after 15 minutes (bounded leak window).

**Status Codes:**
- `200` - URL generated
- `404` - Email not found

---

### List Messages

```
GET /api/messages
```

List messages with optional filters.

**Query Parameters:**
- `mailbox` (required): Mailbox ID
- `status` (optional): `received` | `queued` | `sent` | `failed`
- `to` (optional): Filter by recipient email address
- `from` (optional): Filter by sender email address
- `subaddress` (optional): Filter by subaddress
- `subject` (optional): Filter by subject: literal substring match (subject contains this exact text; no wildcards). Max length: 500 characters after trim; empty / whitespace-only is rejected (400).
- `receivedAfter` (optional): ISO 8601 timestamp; supports optional subsecond precision (e.g. `2026-03-08T06:33:10.634Z`) for millisecond-precision filtering

**URL Encoding for Special Characters:**

Query parameters with special characters must be URL-encoded. The server automatically decodes them.

**Best Practices:**
- **JavaScript/TypeScript**: Use `URLSearchParams` (automatically encodes) or `encodeURIComponent()`
- **Python**: Use `urllib.parse.urlencode()` or `urllib.parse.quote()`
- **cURL**: Use `--data-urlencode` with `-G` flag or manually encode with `%` encoding
- **Bash**: Use `printf '%s' "value" | jq -sRr @uri` or manual encoding

**Special Character Encoding Examples:**

| Character | Encoded | Example Subject | Encoded URL |
|-----------|---------|-----------------|-------------|
| `%` | `%25` | `100% Off` | `subject=100%25%20Off` |
| `_` | `_` (no encoding) | `Test_Email` | `subject=Test_Email` |
| ` ` (space) | `%20` or `+` | `Test Email` | `subject=Test%20Email` |
| `[` | `%5B` | `[Important]` | `subject=%5BImportant%5D` |
| `]` | `%5D` | `[Important]` | `subject=%5BImportant%5D` |
| `?` | `%3F` | `Is This A Scam?` | `subject=Is%20This%20A%20Scam%3F` |

**Example Requests with Special Characters:**

```bash
# Using URLSearchParams (JavaScript/TypeScript) - RECOMMENDED
const params = new URLSearchParams({
  mailbox: 'x7k2m9pqr3s4t5u6',
  subject: 'Is This A Scam? - Subscription Cancellation Scheduled [100% Off]',
  to: 'test+x7k2m9pqr3s4t5u6@fixture.email'
});
fetch(`/api/messages?${params.toString()}`);

# Using cURL with manual encoding
curl -X GET "https://send.fixture.email/api/messages?mailbox=x7k2m9pqr3s4t5u6&subject=Is%20This%20A%20Scam%3F%20-%20Subscription%20Cancellation%20Scheduled%20%5B100%25%20Off%5D" \
  -H "X-API-Key: $API_KEY"

# Using cURL with --data-urlencode (recommended)
curl -G "https://send.fixture.email/api/messages" \
  --data-urlencode "mailbox=x7k2m9pqr3s4t5u6" \
  --data-urlencode "subject=Is This A Scam? - Subscription Cancellation Scheduled [100% Off]" \
  --data-urlencode "to=test+x7k2m9pqr3s4t5u6@fixture.email" \
  -H "X-API-Key: $API_KEY"

# Python example
from urllib.parse import urlencode
params = {
  'mailbox': 'x7k2m9pqr3s4t5u6',
  'subject': 'Is This A Scam? - Subscription Cancellation Scheduled [100% Off]',
  'to': 'test+x7k2m9pqr3s4t5u6@fixture.email'
}
url = f"/api/messages?{urlencode(params)}"
```

**Note**: The subject filter uses literal substring matching: messages are returned when the subject contains the given text exactly. No wildcards or pattern matching. URL-encode special characters in query parameters.

**Response:**
```json
{
  "messages": [
    {
      "emailId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "received",
      "mailbox": "x7k2m9pqr3s4t5u6",
      "from": "sender@example.com",
      "to": ["recipient@example.com"],
      "subject": "Test Email",
      "time": 1730961190634,
      "subaddress": "test123"
    }
  ]
}
```

- `time`: Unix timestamp in **milliseconds** (use with millisecond-precision `receivedAfter` so filtering does not exclude valid messages)

**Status Codes:**
- `200` - Messages retrieved
- `400` - Invalid query parameters (e.g., malformed URL encoding)
- `401` - Missing or invalid API key
- `500` - Internal server error

---

## Usage & Quota

### Get Usage

```
GET /api/usage
```

Return this organization's outbound send usage against its quota. Only **external** sends count; internal test-domain routing is never counted. The response is discriminated by `plan`: a **paid** org reports `day` + `month` buckets; a **trial** org reports `day` + a whole-trial `total` bucket, plus the trial's `trial` clock and a `pressure` block. Every variant names the `organizationId` the key resolved to. A send that would exceed the applicable cap is rejected with `429` before it is queued. Always read `limit`/`remaining` from this endpoint to size headroom — they reflect your actual (scaled) cap.

- **Paid:** 500 external sends/day and 15000/month **per purchased unit**. Quantity is the adjustable line-item quantity at checkout (1–99): buying _N_ units scales the cap to _N_ × these per-unit numbers, so `limit` below is `N × 500` / `N × 15000` (the example shows a 1-unit org).
- **Trial:** 50/day, 250 total across the whole trial (always 1 unit), **and** a 15-day window. A trial ends at whichever ceiling arrives first, so watch both — a trial can be at 40/250 sends and still expire tomorrow. A trial-cap `429` includes a `checkoutUrl` to upgrade.

#### Run this first in CI

`GET /api/usage` is the **cheap pre-flight check**: read-only, side-effect-free, and **off-quota** (it sends nothing, so it never consumes send budget and can be polled freely). Call it once at the start of a CI run before doing any real work — it answers, in one request, the three questions that otherwise surface as confusing mid-run failures:

- `200` — **healthy.** The key is valid and the org is entitled. Read `pressure.status`: `ok` = proceed, `approaching_limit` = proceed but warn (you are near a ceiling), `exhausted` = one ceiling is already gone and sends will fail.
- `401` — **the key is wrong** (missing, malformed, or revoked). Nothing about the org is knowable; fix the credential.
- `402` — **the org is not entitled** (trial expired, subscription lapsed or canceled). The error body carries `checkoutUrl` and `billingPortalUrl` — surface them in the CI log so a human can act without digging.
- `403` — the org is **suspended** for excessive bounces or spam complaints. Sending stays blocked until an operator clears it.

Two things make this diagnostic rather than merely a health probe. First, a `200` names the `organizationId` your key resolved to, so a fleet holding several credentials can prove which org each one actually addresses **without provoking a failing call** — the fastest way to catch "three copies of our credential" turning out to be keys for three different orgs. Second, on a trial it reports the clock, not just the budget.

```bash
curl -X GET "https://send.fixture.email/api/usage" \
  -H "X-API-Key: $API_KEY"
```

**Response (paid):**
```json
{
  "plan":  "paid",
  "organizationId": "org_1a2b3c",
  "day":   { "period": "2026-06-17", "sent": 3,  "limit": 500,   "remaining": 497 },
  "month": { "period": "2026-06",    "sent": 12, "limit": 15000, "remaining": 14988 },
  "reputation": { "month": { "bounces": 0, "complaints": 0 } }
}
```

**Response (trial):**
```json
{
  "plan":  "trial",
  "organizationId": "org_1a2b3c",
  "day":   { "period": "2026-06-17", "sent": 2,  "limit": 50, "remaining": 48 },
  "total": { "period": "all",        "sent": 40, "limit": 250, "remaining": 210 },
  "trial": { "endsAt": "2026-06-20T09:00:00.000Z", "endsAtSource": "provisional", "daysRemaining": 3 },
  "pressure": { "sends": "ok", "trialWindow": "approaching", "status": "approaching_limit" },
  "reputation": { "month": { "bounces": 0, "complaints": 0 } }
}
```

- `plan`: `paid` or `trial` — selects which cap set applies.
- `organizationId`: the org this API key resolves to. Compare it across stored credentials to confirm two keys address the same org.
- `day`: external emails `sent` today, the `limit` (for paid, the per-unit cap × your purchased quantity), and `remaining` headroom (`max(0, limit - sent)`).
- `month` (paid) / `total` (trial): the longer-window bucket — calendar month for paid (also scaled by quantity), the whole trial (`period: "all"`) for a trial org.
- `trial` (trial only) — the **time** ceiling, which no send bucket can express:
  - `endsAt`: ISO 8601 trial end, or `null` if none is recorded.
  - `endsAtSource`: `confirmed` (reconciled against the billing provider — safe to schedule against), `provisional` (the local checkout-time 15-day estimate, **not** confirmed — treat it as an upper bound and re-check), or `unknown` (no end date recorded). Never treat a `provisional` date as a deadline you can plan around.
  - `daysRemaining`: whole days left, rounded **up** so any part of a day reads as at least `1`, clamped at `0` once the window closes; `null` when `endsAt` is `null`.
- `pressure` (trial only) — machine-readable proximity to each ceiling. Reporting only; it gates nothing.
  - `sends`: `ok` / `approaching` / `exhausted` for the tightest send bucket (day **and** whole-trial total). `approaching` once remaining headroom is 20% of that bucket's limit or less — that is `remaining <= 50` against the 250 total.
  - `trialWindow`: `ok` / `approaching` (3 days left or fewer) / `expired` / `unknown`.
  - `status`: the worse of the two axes — `ok`, `approaching_limit`, `exhausted`. Branch on this one field, then read `sends`/`trialWindow` to see which ceiling is closing.
- `reputation.month`: hard bounces and spam complaints recorded this month (an org that exceeds the published bounce/complaint thresholds is auto-suspended).

**Status Codes:**
- `200` - Usage returned
- `401` - Missing or invalid API key
- `402` - No active subscription or trial (body carries `checkoutUrl` + `billingPortalUrl`)
- `403` - Organization suspended for excessive bounces or spam complaints
- `500` - Internal server error

---

## API Keys

Org-scoped API keys for direct HTTP access — mint extra keys (e.g. one per CI pipeline), list them, and revoke them. A key can carry an expiry — set `expiresIn` (seconds) on create here, or mint with a required name + expiry at the browser keys portal — and stays valid until it expires or is revoked. Listing and revoking are also available as the `list_api_keys` / `revoke_api_key` MCP tools; new keys are minted at the keys portal or here, never from an MCP tool.

### Create API Key

```
POST /api/keys
```

**Request Body:**
```json
{
  "name": "CI pipeline",
  "expiresIn": 7776000
}
```

- `name` (optional): display name shown in the key list
- `expiresIn` (optional): lifetime in seconds (max 365 days). Omit for a non-expiring key

**Response (201):**
```json
{
  "apiKey": "feml_...",
  "keyId": "key_abc123",
  "start": "feml_a",
  "name": "CI pipeline",
  "expiresAt": "2026-09-15T00:00:00.000Z",
  "note": "Save this key now - shown once and never recoverable."
}
```

- `apiKey`: the plaintext key — returned **once** and never recoverable. Send it as the `X-API-Key` header.
- `start`: display prefix; the only part of the key the list endpoint shows again
- `expiresAt`: ISO 8601 expiry, or null if the key does not expire

**Status Codes:**
- `201` - Key created
- `401` - Missing or invalid API key
- `409` - Per-organization key limit reached (revoke one first)

### List API Keys

```
GET /api/keys
```

Lists your org's keys. The secret is never returned — only display metadata.

**Response:**
```json
{
  "keys": [
    {
      "keyId": "key_abc123",
      "name": "CI pipeline",
      "start": "feml_a",
      "enabled": true,
      "source": "api",
      "createdAt": "2026-06-17T00:00:00.000Z",
      "lastRequest": "2026-06-17T01:23:45.000Z",
      "expiresAt": "2026-09-15T00:00:00.000Z"
    }
  ]
}
```

- `source`: where the key was minted (`portal` | `api` | `mcp` | null)
- `lastRequest`: ISO 8601 timestamp of last use, or null
- `expiresAt`: ISO 8601 expiry, or null if the key does not expire

### Revoke API Key

```
DELETE /api/keys/{keyId}
```

Disables a key by its `keyId` (from the list endpoint). A recently-used key may keep working for up to ~60s while the verification cache expires.

**Response:**
```json
{
  "keyId": "key_abc123",
  "revoked": true,
  "note": "API key revoked."
}
```

**Status Codes:**
- `200` - Key revoked (idempotent)
- `404` - Key not found in your organization
- `401` - Missing or invalid API key

---

## Webhooks (Callbacks)

Register an HTTPS endpoint to receive **signed**, at-least-once email-lifecycle events instead of polling `GET /api/status/{uuid}`. The same operations are available as the `register_callback` / `list_callbacks` / `delete_callback` MCP tools.

**Event types:** `email.sent`, `email.failed`, `email.received`, `email.bounced`, `email.complained`, `email.suppressed`.

### Register Callback

```
POST /api/callbacks
```

**Request Body:**
```json
{
  "url": "https://your-app.example.com/webhooks/email",
  "events": ["email.received", "email.bounced"]
}
```

- `url` (required): HTTPS URL to POST events to. Private/reserved hosts are rejected.
- `events` (optional): subset of the event types above. Omit to subscribe to all events.

**Response (201):**
```json
{
  "id": "cb_abc123",
  "url": "https://your-app.example.com/webhooks/email",
  "events": ["email.received", "email.bounced"],
  "secret": "whsec_...",
  "enabled": true,
  "createdAt": "2026-06-17T00:00:00.000Z",
  "note": "Save this secret now - shown once and never recoverable."
}
```

- `secret`: HMAC signing secret — returned **once** and never recoverable. Use it to verify the `X-Webhook-Signature` header (below).

**Status Codes:**
- `201` - Callback registered
- `400` - Invalid or unsafe callback URL
- `409` - Per-organization callback limit reached
- `401` - Missing or invalid API key

### List Callbacks

```
GET /api/callbacks
```

**Response:**
```json
{
  "callbacks": [
    {
      "id": "cb_abc123",
      "url": "https://your-app.example.com/webhooks/email",
      "events": ["email.received", "email.bounced"],
      "enabled": true,
      "createdAt": "2026-06-17T00:00:00.000Z"
    }
  ]
}
```

The signing secret is never returned.

### Delete Callback

```
DELETE /api/callbacks/{id}
```

**Response:**
```json
{
  "id": "cb_abc123",
  "deleted": true
}
```

**Status Codes:**
- `200` - Callback deleted (idempotent)
- `404` - Callback not found in your organization

### Delivery format & signature verification

Each subscribed event is delivered as an HTTP `POST` to your URL with this JSON body:

```json
{
  "id": "del_...",
  "event": "email.received",
  "occurredAt": "2026-06-17T00:00:00.000Z",
  "data": {
    "emailId": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_...",
    "mailbox": "x7k2m9pqr3s4t5u6",
    "status": "received"
  }
}
```

- `data.mailbox` and `data.status` are present when known for the event.
- Delivery is **at-least-once** — dedupe on the `X-Webhook-Id` header (a redelivery of the same event reuses the id).

Every delivery carries these headers:
- `X-Webhook-Id` - stable delivery id (dedupe on this)
- `X-Webhook-Timestamp` - signing timestamp (epoch milliseconds)
- `X-Webhook-Event` - the event type
- `X-Webhook-Signature` - `sha256=<hex>`

The signature is computed over the timestamp and the raw body:

```
X-Webhook-Signature = "sha256=" + hex( HMAC_SHA256( secret, timestamp + "." + rawBody ) )
```

To verify: read the `X-Webhook-Timestamp` header and the raw request body, recompute `HMAC-SHA256(secret, timestamp + "." + rawBody)`, hex-encode it, prefix `sha256=`, and constant-time-compare to the value in `X-Webhook-Signature`. Reject deliveries whose timestamp is far from your clock to limit replay.

---

## Error Responses

All errors follow this format:

```json
{
  "error": "Error message describing the problem"
}
```

This includes request-validation failures: a malformed query parameter, path parameter, JSON body or form field is rejected before the handler runs and still answers with this envelope (`{"error": "Invalid query parameters"}`, `"Invalid path parameter"`, `"Invalid request body"`, `"Invalid form data"`), never a validator-internal body. The message names the part of the request that failed and never echoes what you sent.

**Common Status Codes:**
- `400` - Bad Request (invalid payload, or a request that fails schema validation)
- `401` - Unauthorized (missing or invalid API key)
- `402` - Payment Required (no active subscription or trial — see "Paying for Access (Agents & Humans)")
- `404` - Not Found
- `413` - Payload Too Large
- `500` - Internal Server Error

---

## Workflow Examples

### 1. End-to-End Email Test

Send an email and verify it was sent:

```bash
# Create mailbox
MAILBOX=$(curl -s -X POST https://send.fixture.email/api/mailboxes \
  -H "X-API-Key: $API_KEY" | jq -r '.mailbox')

# Send email
EMAIL_ID=$(curl -s -X POST https://send.fixture.email/api/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "test+'$MAILBOX'@fixture.email",
    "to": "recipient@example.com",
    "subject": "Test Email",
    "text": "Hello from test!"
  }' | jq -r '.emailId')

# Poll for sent status
while true; do
  STATUS=$(curl -s "https://send.fixture.email/api/status/$EMAIL_ID" \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  if [ "$STATUS" = "sent" ]; then
    echo "Email sent successfully!"
    break
  fi
  sleep 1
done
```

### 2. Receive External Emails (Email Verification Testing)

Test your app's email verification flow:

```bash
# Create mailbox for testing
MAILBOX=$(curl -s -X POST https://send.fixture.email/api/mailboxes \
  -H "X-API-Key: $API_KEY" | jq -r '.mailbox')

EMAIL_ADDRESS="user+$MAILBOX@fixture.email"
echo "Use this email in your app signup: $EMAIL_ADDRESS"

# Poll for the verification email
while true; do
  MESSAGES=$(curl -s "https://send.fixture.email/api/messages?mailbox=$MAILBOX&status=received" \
    -H "X-API-Key: $API_KEY")
  COUNT=$(echo $MESSAGES | jq '.messages | length')
  if [ "$COUNT" -gt 0 ]; then
    echo "Received verification email!"
    echo $MESSAGES | jq '.messages[0]'
    break
  fi
  sleep 2
done
```

### 3. Mailbox Management

**Disable mailbox** (does NOT schedule cleanup):

```bash
curl -X DELETE "https://send.fixture.email/api/mailboxes/$MAILBOX" \
  -H "X-API-Key: $API_KEY"
```

**Schedule cleanup** (without disabling, allows in-flight emails). When using `Content-Type: application/json`, you must send a JSON body—use `{}` if no options, or include `duration` to override the default grace period:

```bash
# Default grace period (uses server CLEANUP_SLEEP_DURATION)
curl -X POST "https://send.fixture.email/api/mailboxes/$MAILBOX/safe-cleanup" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Optional: override duration (e.g., "30 minutes", "1 hour")
curl -X POST "https://send.fixture.email/api/mailboxes/$MAILBOX/safe-cleanup" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"duration": "30 minutes"}'
```

**Enable mailbox**:

```bash
curl -X POST "https://send.fixture.email/api/mailboxes/$MAILBOX/enable" \
  -H "X-API-Key: $API_KEY"
```

**Disable mailbox** (independent operation):

```bash
curl -X POST "https://send.fixture.email/api/mailboxes/$MAILBOX/disable" \
  -H "X-API-Key: $API_KEY"
```

**Cancel scheduled cleanup**:

```bash
curl -X POST "https://send.fixture.email/api/mailboxes/$MAILBOX/cancel-cleanup" \
  -H "X-API-Key: $API_KEY"
```

**Note**: Enable/disable and cleanup scheduling are independent operations. DELETE only disables the mailbox - cleanup must be scheduled separately via `/safe-cleanup`.

### 4. Retrieve Email Content After Receiving

Get the full body content of a received email:

```bash
EMAIL_ID="..."  # From list messages response

# Get parsed content (HTML and text)
curl -s "https://send.fixture.email/api/messages/$EMAIL_ID/content" \
  -H "X-API-Key: $API_KEY" | jq '.'

# Or download the raw .eml file
RAW_URL=$(curl -s "https://send.fixture.email/api/messages/$EMAIL_ID/raw" \
  -H "X-API-Key: $API_KEY" | jq -r '.url')

curl -o email.eml "$RAW_URL"
```

---

## TypeScript Examples

All examples use the `EmailTestApiClient` class from `tests/helpers/api-client.ts`.

### Setup

```typescript
import { EmailTestApiClient } from './helpers/api-client';

const apiClient = new EmailTestApiClient('https://send.fixture.email', 'your-api-key');
const baseDomain = 'fixture.email';
```

### Create Mailbox and Send Email

```typescript
// Create mailbox
const mailboxResponse = await apiClient.createMailbox();
const mailbox = mailboxResponse.mailbox;
// Returns: { mailbox: "x7k2m9pqr3s4t5u6" }

// Send email (auto-creates mailbox if from is not specified)
const sendResponse = await apiClient.sendEmail({
  to: 'recipient@example.com',
  subject: 'Test Email',
  text: 'Hello from TypeScript!',
});

// Response includes emailId, mailbox, and resolved from address
console.log(sendResponse);
// {
//   emailId: "550e8400-e29b-41d4-a716-446655440000",
//   mailbox: "x7k2m9pqr3s4t5u6",
//   from: "r4nd0m+x7k2m9pqr3s4t5u6@fixture.email"
// }
```

### Send Email with Smart From Handling

```typescript
// Option 1: No from - API auto-creates mailbox
const response1 = await apiClient.sendEmail({
  to: 'recipient@example.com',
  subject: 'Auto-created mailbox',
  text: 'Email body',
});
// Creates new mailbox, from: "r4nd0m+x7k2m9pqr3s4t5u6@fixture.email"

// Option 2: Local part only - API creates new mailbox
const response2 = await apiClient.sendEmail({
  from: 'newsletter',
  to: 'recipient@example.com',
  subject: 'Newsletter',
  text: 'Email body',
});
// Creates new mailbox, from: "newsletter+x7k2m9pqr3s4t5u6@fixture.email"

// Option 3: Full address with existing mailbox
const mailbox = await apiClient.createMailbox();
const response3 = await apiClient.sendEmail({
  from: `sender+${mailbox.mailbox}@fixture.email`,
  to: 'recipient@example.com',
  subject: 'From existing mailbox',
  text: 'Email body',
});
// Uses existing mailbox, validates it exists
```

### Poll for Email Status

```typescript
// Wait for email to reach 'sent' status (external) or 'received' status (internal)
const status = await apiClient.waitForEmailStatus(emailId, 'sent', {
  maxRetries: 30,    // Default: 10
  retryDelay: 2000,  // Default: 2000ms (2 seconds)
});

console.log(status);
// {
//   emailId: "550e8400-e29b-41d4-a716-446655440000",
//   status: "sent",
//   mailbox: "x7k2m9pqr3s4t5u6",
//   from: "sender+x7k2m9pqr3s4t5u6@fixture.email",
//   to: ["recipient@example.com"],
//   subject: "Test Email",
//   time: 1730961190634,  // Unix ms
//   messageId: "msg-abc123"
// }

// For internal routing (test-to-test), wait for 'received' status
const internalStatus = await apiClient.waitForEmailStatus(emailId, 'received', {
  maxRetries: 20,
  retryDelay: 2000,
});
```

### Receive Emails (Internal Routing)

```typescript
// Create mailbox to receive emails
const mailboxResponse = await apiClient.createMailbox();
const mailbox = mailboxResponse.mailbox;

// Generate recipient address (any local part works)
const recipient = `test+${mailbox}@fixture.email`;

// Send email to test domain address (routes internally)
const sendResponse = await apiClient.sendEmail({
  from: `sender+${mailbox}@fixture.email`,
  to: recipient,
  subject: 'Internal Test',
  text: 'This is routed internally',
});

// Wait for 'received' status (not 'sent')
const status = await apiClient.waitForEmailStatus(sendResponse.emailId, 'received', {
  maxRetries: 20,
  retryDelay: 2000,
});

// Email is now in recipient's mailbox
const messages = await apiClient.listMessages({
  mailbox,
  status: 'received',
});
```

### Get Email Content and Extract Links

```typescript
// Get parsed content (HTML, text, and extracted links)
const content = await apiClient.getEmailContent(emailId);

console.log(content);
// {
//   html: "<html>Full HTML content...</html>",
//   text: "Plain text content...",
//   subject: "Email Subject",
//   from: "sender@example.com",
//   to: ["recipient@example.com"],
//   links: ["https://example.com/verify?token=abc", "https://example.com/unsubscribe"]
// }

// Links are already extracted and decoded (e.g., &amp; → &)
const verifyLink = content.links.find(link => link.includes('/verify'));

// Get presigned URL for raw .eml file download
const rawResponse = await apiClient.getEmailRawUrl(emailId);
// { url: "https://...", expiresIn: 3600 }

// Download .eml (no auth needed for presigned URL)
const emlContent = await fetch(rawResponse.url).then(r => r.text());
```

### List Messages with Filters

```typescript
// List messages with filters (URLSearchParams handles encoding automatically)
const messages = await apiClient.listMessages({
  mailbox: 'x7k2m9pqr3s4t5u6',
  status: 'received',
  to: `test+x7k2m9pqr3s4t5u6@fixture.email`,
  subject: 'Is This A Scam? - Subscription Cancellation Scheduled [100% Off]',
  receivedAfter: '2024-01-01T00:00:00.000Z', // ISO 8601; subseconds (e.g. .634Z) enable millisecond-precision filtering
});

console.log(messages.messages);
// [
//   {
//     emailId: "550e8400-e29b-41d4-a716-446655440000",
//     status: "received",
//     mailbox: "x7k2m9pqr3s4t5u6",
//     from: "sender@example.com",
//     to: ["test+x7k2m9pqr3s4t5u6@fixture.email"],
//     subject: "Is This A Scam? - Subscription Cancellation Scheduled [100% Off]",
//     time: 1730961190634,  // Unix ms
//     subaddress: "test"
//   }
// ]

// Wait for email to appear in messages list
const message = await apiClient.waitForEmailInMessages(emailId, {
  maxRetries: 20,
  retryDelay: 2000,
  filters: {
    mailbox: 'x7k2m9pqr3s4t5u6',
    status: 'received',
  },
});
```

### Send Email with Attachments

```typescript
// Small attachment (< 1MB) - use base64
const textEncoder = new TextEncoder();
const bytes = textEncoder.encode('Test attachment content');
const attachmentContent = btoa(String.fromCharCode(...bytes));

const sendResponse = await apiClient.sendEmail({
  to: 'recipient@example.com',
  subject: 'Email with Attachment',
  text: 'See attached file',
  attachments: [
    {
      name: 'test.txt',
      content: attachmentContent,
      contentType: 'text/plain',
    },
  ],
});

// Large attachment (>= 1MB) - upload first, then reference
const mailbox = await apiClient.createMailbox();
const fileContent = 'Large file content...';
const file = new Blob([fileContent], { type: 'text/plain' });

// Upload attachment
const uploadResponse = await apiClient.uploadAttachment(
  mailbox.mailbox,
  file,
  'large-file.txt'
);
// Returns: { attachmentId: "uuid", filename: "large-file.txt", size: 1234, contentType: "text/plain" }

// Send email with attachmentId reference
const sendResponse2 = await apiClient.sendEmail({
  from: `sender+${mailbox.mailbox}@fixture.email`,
  to: 'recipient@example.com',
  subject: 'Email with Large Attachment',
  text: 'See attached file',
  attachments: [
    {
      name: 'large-file.txt',
      attachmentId: uploadResponse.attachmentId,
      contentType: 'text/plain',
    },
  ],
});
```

### Send Raw .eml File (Replay External Emails)

```typescript
// Read .eml file content
const emlContent = await fs.promises.readFile('saved-email.eml', 'utf-8');

// Send with optional From/To overrides (useful for replaying external emails)
const sendResponse = await apiClient.sendRawEmail(emlContent, {
  from: `sender+x7k2m9pqr3s4t5u6@fixture.email`,
  to: 'recipient@example.com',
});

// Original .eml is preserved in R2, From/To overrides are applied at send time
```

### Complete Example: Email Verification Flow

```typescript
import { EmailTestApiClient } from './helpers/api-client';

const apiClient = new EmailTestApiClient('https://send.fixture.email', process.env.API_KEY!);
const baseDomain = 'fixture.email';

// 1. Create mailbox for testing
const mailboxResponse = await apiClient.createMailbox();
const mailbox = mailboxResponse.mailbox;
const testEmail = `user+${mailbox}@fixture.email`;

console.log(`Use this email in your app: ${testEmail}`);

// 2. Poll for verification email to arrive
let verificationEmail = null;
for (let i = 0; i < 30; i++) {
  const messages = await apiClient.listMessages({
    mailbox,
    status: 'received',
  });
  
  if (messages.messages.length > 0) {
    verificationEmail = messages.messages[0];
    break;
  }
  
  await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
}

if (!verificationEmail) {
  throw new Error('Verification email not received');
}

// 3. Get email content and extract verification link
const content = await apiClient.getEmailContent(verificationEmail.emailId);
const verifyLink = content.links.find(link => 
  link.includes('/verify') || link.includes('token=')
);

if (verifyLink) {
  console.log(`Verification link: ${verifyLink}`);
  // Click the link or extract token for your test
}
```

### Cleanup

```typescript
// Disable mailbox (does NOT schedule cleanup)
await apiClient.deleteMailbox(mailbox);

// Schedule cleanup (without disabling, allows in-flight emails).
// Call with no options to use server default duration (sends {}); or pass { duration: '30 minutes' } to override.
await apiClient.scheduleMailboxCleanup(mailbox);
await apiClient.scheduleMailboxCleanup(mailbox, { duration: '30 minutes' });

// Enable mailbox
await apiClient.enableMailbox(mailbox);

// Disable mailbox (independent operation)
await apiClient.disableMailbox(mailbox);

// Cancel scheduled cleanup
await apiClient.cancelMailboxCleanup(mailbox);
// Returns: { success: true }

// Note: Mailbox is disabled immediately, but data is permanently deleted
// after CLEANUP_SLEEP_DURATION (typically 30 minutes) to allow in-flight
// emails to complete processing.
```

---

## Additional Resources

- **This document (`GET /llms.txt`)** - the public API contract. No key required; it is what our `/.well-known/api-catalog` and `Link: rel="service-doc"` header advertise.
- **Customer MCP** - the org-scoped tool surface (one-call waits, no polling loop); connect details are in "Start here" at the top of this document.
- **OpenAPI document**: `GET /api/openapi.json` - **authenticated, not public.** Requires your org-scoped `X-API-Key`; a keyless request gets `401`. Fetch it only once you hold a key.
- **Swagger UI**: `GET /api/docs` - the browser UI over that document, gated by the same `X-API-Key`, so it is not a public docs page either.
- **Test Examples**: See `tests/` directory for complete TypeScript test examples

---

## Limits

- Maximum email size: 25MB
- Maximum base64 attachment in request body: 1MB (use upload endpoint for larger files)
- Maximum uploaded attachment: 25MB