# MailWarren API reference

> MailWarren is an email sandbox for developers. Apps send email to it (over SMTP or HTTP) and it is captured instead of delivered; tests and AI agents then read that email back through an API — with verification codes and links already extracted. It can also deliver real transactional email from a verified domain.

This document is the complete, plain-text API reference, written so an AI agent or a developer can use MailWarren without anything else. Machine-readable OpenAPI 3.1 spec: https://www.mailwarren.io/openapi.json. Human docs: https://www.mailwarren.io/docs.

## Quick facts

- API base URL: `https://api.mailwarren.io/gateway/5d1da8dd-9504-4297-9bd3-8dfc3fc90faf/Prod/mailwarren/v1` — every path below is relative to it.
- Authentication: `Authorization: Bearer <key>`. Keys are created by a signed-in user in the web app (https://www.mailwarren.io); no API creates keys. If you are an agent without a key, ask your user for one.
- Requests and responses are JSON (UTF-8). Field names in request bodies for `/send` and `/sandbox/send` are PascalCase (`From`, `To`, …); responses are camelCase.
- Times are UTC ISO-8601.
- MCP server for AI agents: `https://api.mailwarren.io/gateway/5d1da8dd-9504-4297-9bd3-8dfc3fc90faf/Prod/mailwarren/v1/mcp` (streamable HTTP, bearer key).

## Keys

| Key | Prefix | Can do | Created in the web app at |
|---|---|---|---|
| Send key | `mw_live_` | `POST /send` — deliver real email from one verified domain | Sending Domains |
| Mailbox key | `mw_sandbox_` | One mailbox: capture into it (`POST /sandbox/send`), read it (`/inbox/*`), MCP | A mailbox's page inside a Warren → Sandbox API keys |
| Account key | `mw_mcp_` | Read every mailbox the account (or organisation) owns (`/inbox/*`), MCP | Account → MCP keys (organisation Owners/Admins) |

A key only ever sees its own owner's mail; anything else is "not found" (404), never 403. Prefer a mailbox key when one mailbox is enough; keep account keys out of client-side code and logs.

## Concepts

- **Warren**: a project. It holds mailboxes.
- **Mailbox**: a capture inbox with its own SMTP credentials and mailbox keys. Point an app's SMTP settings at it and everything the app sends lands there.
- **Captured message**: an email in a mailbox. Captures count against the plan's monthly capture allowance and are kept for the plan's retention period.

## Typical flows

**Test that your app sends the right email (CI or agent):**
1. Your app sends via SMTP to a MailWarren mailbox (or you call `POST /sandbox/send`).
2. Note the time (or `DELETE /inbox/messages` to clear the mailbox first).
3. Trigger the action (sign up, reset password, order).
4. `GET /inbox/wait?to=<address>&since=<time or 1m>` — returns the email with `code` and `links`.
5. Use `code`, or the link whose `purpose` is `verify`/`reset`/…; optionally `GET /inbox/messages/{id}?analyze=true` for quality checks.

**Send real email:** `POST /send` with a send key; check `status` in the 200 response.

---

## POST /send — send an email

Key: send key (`mw_live_…`). Delivers through Amazon SES from the domain the key was created for.

Request body:

| Field | Type | Required | Notes |
|---|---|---|---|
| `From` | string | yes | Must be an address on the key's verified domain, or 403. |
| `To` | string[] | yes | Up to the account's per-message recipient cap (50 by default). |
| `Subject` | string | yes | |
| `TextBody` | string | one of | Plain-text body. |
| `HtmlBody` | string | one of | HTML body, sent exactly as given. |
| `Attachments` | object[] | no | Up to 10 (inline images included). Whole message under 10 MB after base64. |

Attachment object:

| Field | Type | Required | Notes |
|---|---|---|---|
| `FileName` | string | yes | |
| `ContentType` | string | yes | e.g. `application/pdf`, `image/png` |
| `ContentBase64` | string | yes | The raw file bytes, base64. |
| `ContentId` | string | no | Makes it an inline image referenced from `HtmlBody` as `<img src="cid:ID">`. `logo`, `<logo>` and `cid:logo` are equivalent. Printable ASCII, no spaces/quotes/angle brackets, ≤ 250 chars, unique per message (case-insensitive). |
| `Disposition` | string | no | `inline` or `attachment`. Default: `inline` if `ContentId` is set, else `attachment`. |

Refused with 400 (nothing sent, queued or charged): inline item without `ContentId`; inline item when there is no `HtmlBody`; duplicate `ContentId`; other `Disposition` values; invalid `ContentId`; more than 10 attachments; invalid base64. A `cid:` in the HTML with no matching attachment is not an error — it shows as a broken image.

Response — HTTP 200 whenever the request is well-formed:

```json
{ "status": "Sent", "sesMessageId": "0100018f…", "message": null }
```

| `status` | Meaning |
|---|---|
| `Sent` | Handed to SES; `sesMessageId` set. `message` lists any recipients skipped because they are on the suppression list. |
| `PendingReview` | The account's first send is held for a one-time manual review; later sends flow automatically. |
| `Rejected` | Account suspended, daily cap reached, or every recipient is suppressed. See `message`. |
| `Failed` | SES refused it. See `message`. Any credit charged is refunded. |
| `HeldForCredit` | Not enough prepaid credit. Held up to 7 days and sent automatically once credit is added. |

Errors: `401` bad/missing key, `403` `From` not on the key's domain, `400` bad request. **The error body is plain text** (the reason), except malformed JSON → `{"error":"invalid_json"}` and schema validation → `{"error":"validation_failed","details":"…"}`.

Example:

```bash
curl -X POST "https://api.mailwarren.io/gateway/5d1da8dd-9504-4297-9bd3-8dfc3fc90faf/Prod/mailwarren/v1/send" \
  -H "Authorization: Bearer mw_live_…" -H "Content-Type: application/json" \
  -d '{"From":"noreply@yourdomain.com","To":["customer@example.com"],"Subject":"Your receipt",
       "HtmlBody":"<img src=\"cid:logo\" alt=\"Acme\"><p>Thanks for your order.</p>","TextBody":"Thanks for your order.",
       "Attachments":[{"FileName":"logo.png","ContentType":"image/png","ContentBase64":"iVBORw0KGgo…","ContentId":"logo"}]}'
```

### SMTP relay (same key, same rules)

Apps that only speak SMTP can send through the relay instead of `/send`: host `send.smtp.mailwarren.io`, port `587` (STARTTLS), username anything, password = the send key. `From` must still be on the key's domain. Attachments and inline (Content-ID) parts come through; an inline part that can't be placed (no Content-ID, a repeated one, or no HTML body) is delivered as a regular attachment.

## POST /sandbox/send — capture an email (nothing is delivered)

Key: mailbox key (`mw_sandbox_…`). Same request body and attachment rules as `POST /send`. The message is captured into the key's mailbox; `From`/`To` can be anything (display only). No domain check, review or daily cap. Counts against the monthly capture allowance (`429`, plain-text body, when used up). Attachments may total 30 MB.

Response (same shape as `/send` on purpose): `{ "status": "Sent", "sesMessageId": "<captured message id>" }`.

## Inbox API

Keys: mailbox key (pinned to its mailbox) or account key (all the account's mailboxes; use `mailbox_id` to narrow). Errors are JSON: `{ "error": "…" }`. `401` bad/revoked key; `404` not found or not yours; `400` bad parameter.

Shared filters (query string) for `/inbox/messages` and `/inbox/wait`:

| Parameter | Meaning |
|---|---|
| `mailbox_id` | Only this mailbox (uuid). |
| `to`, `from`, `subject` | Case-insensitive "contains". |
| `text` | Subject, text body or HTML body contains. |
| `since` | ISO-8601 time or an age: `30s`, `5m`, `2h`, `1d` (ages avoid clock skew). |

### GET /inbox/mailboxes

`{ "keyKind": "mailbox" | "account", "mailboxes": [ { "id", "name", "warrenId", "warrenName", "messageCount" } ] }`

### GET /inbox/messages

List or search, newest first. Extra parameter `limit` (default 20, max 200). No default `since`.

`{ "messages": [ { "id", "mailboxId", "fromAddress", "toAddresses", "subject", "receivedAtUtc", "attachmentCount" } ] }`

### GET /inbox/wait

Long-poll: holds up to `timeout` seconds (default 20, max 25) until a matching message arrives, then returns the newest match in full. `since` defaults to 10 minutes ago. If nothing arrives: `{ "matched": false, "timedOut": true, "waitedSeconds": 20, "since": "…" }` — call again (loop client-side for longer waits). Counts as one request however long it is held.

```json
{ "matched": true, "message": { "id": "…", "subject": "Verify your email", "code": "482913", "links": [ { "url": "https://app.example/verify?t=…", "text": "Confirm my email", "purpose": "verify" } ], "…": "…" } }
```

### GET /inbox/messages/{id}

One message in full:

```json
{
  "id": "…", "mailboxId": "…", "fromAddress": "noreply@app.example", "toAddresses": ["alice@test.dev"],
  "subject": "Verify your email", "receivedAtUtc": "2026-09-24T10:00:00Z",
  "bodyText": "Your code is 482913", "bodyHtml": "<p>…</p>", "headers": "From: …",
  "attachments": [ { "id": "…", "fileName": "logo.png", "contentType": "image/png", "sizeBytes": 2048, "contentId": "logo", "disposition": "inline" } ],
  "code": "482913",
  "codes": [ { "value": "482913", "confidence": "high", "context": "Your code is 482913" } ],
  "links": [ { "url": "https://…", "text": "Confirm", "purpose": "verify" } ],
  "analysis": null
}
```

- `code` is only set at high confidence (a word like code, OTP, PIN, passcode, token, verification just before it) so an order number is never returned; every candidate is in `codes`. A code is 4–8 digits, `123 456`, or 6–8 upper-case letters and digits.
- `links[].purpose`: `verify`, `reset`, `invite`, `login`, `unsubscribe`, `other` (guessed from URL and text).
- `attachments[].disposition` is `inline` for an embedded image (`contentId` = what the HTML's `cid:` refers to), otherwise `attachment`.
- `?analyze=true` fills `analysis` with the pre-send checks: `errors`, `warnings`, `infos`, `issues[] { id, category, severity, message, clients }` (category: content, deliverability, compatibility, accessibility, mobile, links), `spam { score, threshold (5), verdict: low-risk|borderline|likely-spam, rules[], note }`, `compatibility[] { client: Gmail|Outlook (Windows)|Apple Mail|Yahoo Mail, status: ok|minor|issues|problems, problems[] }`. On every plan.
- `?links=live` also requests each link (≤ 15; never private/internal addresses, never single-use verify/reset/invite/login/unsubscribe links) and adds `analysis.links { total, checked, broken, results[] }`. Slower (up to ~18 s). Plan-gated: `403 plan_limit` if not included, `429 quota_exceeded` when today's quota is used (resets 00:00 UTC).

### GET /inbox/attachments/{id}

`{ "fileName": "invoice.pdf", "contentType": "application/pdf", "sizeBytes": 30211, "contentBase64": "JVBERi0…" }`

### DELETE /inbox/messages

Deletes every message in one mailbox (the mailbox and keys stay). Mailbox key: no parameter needed. Account key: `mailbox_id` required. Returns `{ "deleted": 12 }`. Doesn't give back capture allowance.

## GET /plans — public, no key

`{ "plans": [ { "planCode", "name", "priceUsd", "purchasable", "features": [], "limits": { "monthlyCaptureCap", "mcpKeyLimit", "teamSeatLimit", "messageRetentionDays", "apiRequestsPerMinute", "liveLinkChecksPerDay" } } ] }` — `null` = unlimited; `liveLinkChecksPerDay: 0` = not included.

## Limits and plan errors

- Inbox API + MCP requests are limited **per account per minute** (all keys combined; Free: 30/min). Over the limit: `429`, `Retry-After` header, body `{ "error", "code": "rate_limited", "plan", "limit", "retryAfterSeconds" }`. Wait and retry.
- Live link checks are per account per UTC day: `403 { "code": "plan_limit" }` when the plan lacks them, `429 { "code": "quota_exceeded" }` when used up (don't retry until 00:00 UTC).
- Captures (SMTP or `/sandbox/send`) count against the monthly capture allowance; reading, waiting and deleting don't.
- Do not send real customer email to capture mailboxes (see https://www.mailwarren.io/legal/acceptable-use).

## MCP server (AI agents)

URL `https://api.mailwarren.io/gateway/5d1da8dd-9504-4297-9bd3-8dfc3fc90faf/Prod/mailwarren/v1/mcp`, header `Authorization: Bearer <mailbox or account key>`. Stateless; nothing to install.

Claude Code:

```bash
claude mcp add --transport http mailwarren https://api.mailwarren.io/gateway/5d1da8dd-9504-4297-9bd3-8dfc3fc90faf/Prod/mailwarren/v1/mcp --header "Authorization: Bearer mw_mcp_…"
```

Generic MCP config:

```json
{ "mcpServers": { "mailwarren": { "type": "http", "url": "https://api.mailwarren.io/gateway/5d1da8dd-9504-4297-9bd3-8dfc3fc90faf/Prod/mailwarren/v1/mcp", "headers": { "Authorization": "Bearer mw_mcp_…" } } } }
```

Tools: `list_mailboxes`, `list_warrens`, `list_messages`, `wait_for_message`, `get_message`, `analyze_message` (`check_links=true` for the live check) — read-only; `send_test_email` — writes a captured email, never delivers; `delete_all_messages` — destructive. Prompts: verify a signup email, review an email's quality, find a missing email.

## SDKs (single-file, dependency-free; not yet on package registries)

- JavaScript/TypeScript: https://www.mailwarren.io/downloads/mailwarren-test.js (+ `.d.ts`)
- Python: https://www.mailwarren.io/downloads/mailwarren_test.py
- .NET: https://www.mailwarren.io/downloads/MailWarrenTest.cs

Each wraps the Inbox API: `waitForEmail` / `wait_for_email` / `WaitForEmailAsync`, `code`, `links`, `findLink`, `analyze`, `assertQuality`, `attachment("cid:logo")`, `send`, `clear`. Configure with the API base URL above and a key (env `MAILWARREN_API_URL`, `MAILWARREN_API_KEY`). Details: https://www.mailwarren.io/docs/test-automation.

## Support

support@mailwarren.io