> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mermail.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authenticate with an API key, see plan limits, and try Mermail endpoints from the docs.

Use Mermail’s HTTP API from scripts, agents, Postman, or this docs **Try it** playground.

**Base URL:** `https://console.mermail.app`

All protected sold-API routes need:

```bash theme={null}
x-api-key: sk-proj-YOUR_KEY
```

Create a key in the Mermail app under **Settings → API Keys**, then paste it into Try it or your client. See [Authentication](https://docs.mermail.app/api-reference/authentication.md).

Every sold-API credential call debits **API credits** and counts toward workspace **RPM**. When credits run out you get `402` with `credits_exhausted`; when you exceed RPM you get `429`. The keyless [Agent Marketplace](https://docs.mermail.app/ai/agent-marketplace.md) API uses a different `402`: x402 or MPP payment (including `$0` identity handshakes), not API credits.

> [!NOTE]
>
> Each API key is bound to **one workspace**. Required path `workspaceId`
> values must identify that workspace. Optional body/query `workspaceId` values
> can be omitted and are resolved from the key; supplied values must match
> (`403` `workspace_scope_denied` otherwise). `GET /workspaces` returns only the
> key's workspace. Workspaces are created automatically for new accounts in the
> Mermail console — there is no sold-API “create workspace” endpoint.

Each endpoint page in this reference shows **plan badges** (sidebar tag + Plans line):

| Badge | Meaning |
| - | - |
| `All plans` | Free, Developer, and Enterprise |
| `Developer+` | Developer and Enterprise only (`403` on Free) |

***

## Plans at a glance

| | Free | Developer | Enterprise |
| - | -: | -: | -: |
| API keys | 1 | 5 | Unlimited |
| API credits / period | 1,000 | 50,000 | Soft unlimited |
| API RPM | 60 | 300 | Unlimited |
| Core API catalog | Yes | Yes | Yes |
| Developer-gated APIs | No (`403`) | Yes | Yes |

Full workspace limits (inboxes, email volume, storage): [Plans](https://docs.mermail.app/resources/plans.md).

Enterprise shares the same endpoint list as Developer — higher quotas, not extra customer paths.

***

## Quick start

**1. Create an API key**

In Mermail → **Settings → API Keys** → copy `sk-proj-…` once (Free: 1 key, Developer: up to 5).

**2. Pick an endpoint**

Use the sidebar in this API Reference. Prefer core catalog endpoints on Free; Developer-gated paths need Developer or Enterprise.

**3. Authorize and send**

Open the page → **Try it** → paste your API key → fill params → send. Or copy a **cURL / Python / JavaScript / PHP / Go / Java / Ruby** snippet from the language dropdown.

> [!TIP]
>
> Start with **Usage → Get API credit usage** after you have a key.

***

## Core API catalog (all plans)

### Send files and inline images

Send, reply, forward, save-draft, and schedule requests accept an `attachments` array in the JSON request body. Each item contains base64 file bytes (`content`, `filename`, `type`, `disposition`, and optional `contentId`) or `{ "attachment_id": "existing-id" }` to reuse a file in the same authorized mailbox. Pass complete file bytes, not a local path, URL, or `data:` URL.

When replacing or sending an existing draft, omitting `attachments` preserves its files; `[]` clears them; an explicit array replaces the entire set. Use `draft_id` for save/schedule and `source_draft_id` for sends. Include references for existing files you want to retain alongside new bytes.

For inline PNG, JPEG, GIF, or WebP, set `disposition: "inline"`, assign a unique `contentId`, and include a matching HTML image such as `<img src="cid:chart-1" alt="Chart" />`. Drafts and schedules carry HTML in `body` with `body_format: "html"`; sends use `html`.

Storage allows 20 files, 10 MiB per file, and 25 MiB decoded total. The Email module also checks the encoded message, its bodies, and overhead: about **5 MiB** for hosted `@mermail.app` addresses and about **40 MB** for custom-domain addresses. A file that fits storage can exceed the message limit. See the [Email module](https://docs.mermail.app/concepts/email.md#attachments-and-message-size) and [attachment examples](https://docs.mermail.app/ai/mcp.md#files-and-inline-images). MCP wraps the REST payload in a tool's `body` object; REST sends the payload directly.

Treat saved drafts, queued requests, and scheduled emails according to the returned status. Only report **sent** after an authoritative send result; recipient delivery is a separate outcome.

Auth: `x-api-key`. Metered with credits + RPM. Open each group in the sidebar for full schemas and Try it.

### Catalog by area

> [accordion] Workspaces, members, invites, usage
>
> | Method | Path | Credits |
> | - | - | -: |
> | `GET` | `/api/v1/workspaces` | 1 |
> | `GET` | `/api/v1/workspaces/{workspaceId}` | 1 |
> | `PUT` | `/api/v1/workspaces/{workspaceId}` | 2 |
> | `GET` | `/api/v1/workspaces/{workspaceId}/storage` | 1 |
> | `GET` | `/api/v1/workspaces/{workspaceId}/usage/email` | 1 |
> | `GET` | `/api/v1/workspaces/{workspaceId}/usage/credits` | 1 |
> | `GET` | `/api/v1/workspaces/{workspaceId}/members` | 1 |
> | `PUT` | `/api/v1/workspaces/{workspaceId}/members/{memberId}` | 2 |
> | `DELETE` | `/api/v1/workspaces/{workspaceId}/members/{memberId}` | 2 |
> | `POST` | `/api/v1/workspaces/{workspaceId}/invites` | 2 |
> | `POST` | `/api/v1/workspaces/{workspaceId}/invites/{inviteId}/resend` | 2 |

> [accordion] Mailboxes
>
> Path param `{mailboxId}` accepts **`public_id` (UUID)**, hosted alias id, or current email. Prefer `public_id` from list responses.
>
> | Method | Path | Credits |
> | - | - | -: |
> | `GET` | `/api/v1/workspaces/{workspaceId}/mailboxes` | 1 |
> | `GET` | `/api/v1/mailboxes` | 1 |
> | `POST` | `/api/v1/mailboxes` | 10 |
> | `GET` | `/api/v1/mailboxes/{mailboxId}` | 1 |
> | `PUT` | `/api/v1/mailboxes/{mailboxId}` | 2 |
> | `GET` | `/api/v1/mailboxes/{mailboxId}/storage` | 1 |

> [accordion] Emails, folders, search, labels
>
> List / send / reply / forward, bounded safe thread context, drafts,
> scheduled sends, threads, folders, search, and custom labels under
> `/api/v1/mailboxes/{mailboxId}/...`.
>
> Typical costs: send / reply / forward / schedule = **5**; draft regenerate = **15**; most reads = **1**, writes = **2**.

> [accordion] AI agent
>
> | Method | Path | Credits |
> | - | - | -: |
> | `GET` | `/api/v1/mailboxes/{mailboxId}/agent-conversations` | 1 |
> | `POST` | `/api/v1/mailboxes/{mailboxId}/agent-conversations` | 2 |
> | `PATCH` | `/api/v1/mailboxes/{mailboxId}/agent-conversations/{conversationId}` | 2 |
> | `DELETE` | `/api/v1/mailboxes/{mailboxId}/agent-conversations/{conversationId}` | 2 |
> | `GET` | `/api/v1/mailboxes/{mailboxId}/agent-conversations/{conversationId}/messages` | 1 |
> | `POST` | `/api/agent/mailbox` | 25 |

> [accordion] Task triage
>
> | Method | Path | Credits |
> | - | - | -: |
> | `GET` | `/api/v1/mailboxes/{mailboxId}/task-triagers` | 1 |
> | `POST` | `/api/v1/mailboxes/{mailboxId}/task-triagers` | 2 |
> | `GET` | `/api/v1/mailboxes/{mailboxId}/task-triager-runs/recent` | 1 |
> | `PUT` | `/api/v1/mailboxes/{mailboxId}/task-triagers/{triagerId}` | 2 |
> | `DELETE` | `/api/v1/mailboxes/{mailboxId}/task-triagers/{triagerId}` | 2 |
> | `POST` | `/api/v1/mailboxes/{mailboxId}/task-triagers/{triagerId}/default` | 2 |
> | `POST` | `/api/v1/mailboxes/{mailboxId}/task-triagers/{triagerId}/agent-conversation` | 2 |

***

## Developer-gated APIs (Developer + Enterprise)

Free workspaces receive `403` on these paths. Upgrade to unlock them.

| Area | Paths |
| - | - |
| Custom domains | `GET/POST /workspaces/{id}/email-domains`, `DELETE …/{domainId}`, `POST …/verify` |

***

## Credits

API credits are workspace usage units. A 10-credit provision operation does not
mean a `$10` currency charge. A successful mailbox create consumes 10 provision
credits. Pass `Idempotency-Key` when repeating the same create intent, but do not
treat it as proof of exactly-once business execution. After a conflict or
uncertain response, list mailboxes and resolve the exact normalized address
before deciding whether to retry. Authenticated requests carrying this header
have a 50 MiB request-fingerprint body limit; larger bodies return `413`
`idempotency_payload_too_large` before the operation runs.

| Class | Cost |
| - | -: |
| read | 1 |
| write | 2 |
| email\_send | 5 |
| provision | 10 |
| ai\_light | 15 |
| ai\_heavy | 25 |

Free and Developer return `402` (`credits_exhausted`) when the period pool is empty. Enterprise soft-unlimited still records usage. Check remaining balance via `GET /api/v1/workspaces/{workspaceId}/usage/credits`.

## Rate limits

| Plan | Default RPM |
| - | -: |
| Free | 60 |
| Developer | 300 |
| Enterprise | Unlimited |

Over limit → `429`.

## Auth reminder

| Credential | Header | When to use |
| - | - | - |
| API key | `x-api-key: sk-proj-…` | Scripts, Postman, and apps |

Details: [Authentication](https://docs.mermail.app/api-reference/authentication.md).

## Spec source

This reference is generated from `openapi/openapi.json`. Regenerate with:

```bash theme={null}
node scripts/generate-openapi.mjs
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.