Skip to main content
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:
Create a key in the Mermail app under Settings → API Keys, then paste it into Try it or your client. See Authentication. Every sold-API credential call debits API credits and counts toward workspace RPM. When credits run out you get 402; when you exceed RPM you get 429.
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):

​
Plans at a glance

Full workspace limits (inboxes, email volume, storage): Plans. 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.
Start with Usage → Get API credit usage after you have a key.

​
Core API catalog (all plans)

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

​
Catalog by area

Path param {mailboxId} accepts public_id (UUID), hosted alias id, or current email. Prefer public_id from list responses.
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.

​
Developer-gated APIs (Developer + Enterprise)

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

​
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. 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

Over limit → 429.

​
Auth reminder

Details: Authentication.

​
Spec source

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