API overview

Everything the dashboard does, the HTTP API does too. These pages list every endpoint a universe offers.

Try it in the docs

Every endpoint on these pages has a Try it button. It sends the request for real from your browser and shows the response, its status and timing, and the same call as curl. Send it as:

• the demo universe: read-only and open to everyone, no account needed;
• your universes, when you are signed in: the page gets a 15-minute pass for them, with at most the member role;
• an API key you paste, which stays in that browser tab.

To try things without using AI credits, switch AI writing off in a universe.

Base URL

Each universe is served by its organization’s server (cell). Your account page shows the API address for each universe:

https://c1.simmail.dev/api

Authentication

Send an API key as a bearer token:

curl -s https://c1.simmail.dev/api/me -H "Authorization: Bearer smk_your_key"

For clients that cannot set headers, such as a browser’s EventSource, the key can go in the query instead: ?token=smk_your_key. Prefer the header everywhere else, since URLs end up in logs.

GET /api/me says who you are: for a key, its prefix, name, universe and role, and the universes you can open.

Choosing the universe

An API key belongs to one universe, so requests with a key go there. When signed in as a person, choose with the X-Simmail-Universe header or ?universe=. See Universes.

Roles

Each request needs a minimum role:

Requests	Least role
Every GET	viewer
Changes to logins (/api/accounts), webhooks, retention, link rules, recipient rules, faults, the World and reset	admin
Every other change	member

JSON conventions

• Request bodies are JSON. Send Content-Type: application/json.
• Answers are JSON, indented. A list is always a list, [] when empty, never null.
• Times are RFC 3339, such as 2026-10-10T14:32:05Z, on the universe’s simulated clock unless noted.
• Durations are strings: 90s, 45m, 2h, 3d.
• Message-IDs include their angle brackets, such as <[email protected]>. URL-encode them in query strings (%3C and %3E).
• PUT on a settings document (world, faults, webhooks, link rules, recipient rules) replaces it. Read it, change it, write all of it back.
• PATCH merges: fields you leave out keep their values.

Errors

Errors have a status code and a JSON body with one field:

{ "error": "no such persona" }

Status	Meaning
200	Done.
400	The request is wrong: bad JSON, a missing field, an invalid value. A plan’s numeric limit (people, logins, streams) is also refused with 400 and a message such as “the Starter plan includes 250 people; upgrade for more”.
401	No key, or a key that is not valid.
402	Your plan does not include this feature: insights, MCP, webhooks, link rules, or advanced chaos.
403	Your role cannot do this (“your role (viewer) cannot do this”), the key belongs to another universe, the organization is suspended, or the call is for the server’s own administrators.
404	No such thing: mailbox, message, persona, case, job or share.
405	Wrong method.
408	A wait timed out.
409	A conflict: a person decided not to reply (wait/reply), or the persona comes from a YAML file and cannot be edited through the API.
429	Too many requests. Each key or person may make about 20 a second, in bursts of up to 100; the docs’ Try it consoles a few a second. Also too many sign-ins or deliverability-check addresses.
500	Something failed on the server. Sending past your plan’s monthly mail limit with POST /api/send also answers 500, with the plan’s message.

Reference

Area	Page
Mailboxes, messages, sending, waiting	Mail and mailboxes
People, memory, relations	Personas
Shared context	Cases
SMTP and IMAP logins, connection details	Accounts and logins
The clock and the job queue	Clock and jobs
Health reports	Inspect
Company and inbound streams	World
Campaign reports	Insights
SMTP failures	Faults
Notifications	Webhooks
The activity log and live stream	Events and stream
Pace, recipients, links, retention	Behaviour settings