MailcrateAPI Reference
Every public endpoint, generated from the API itself, with the conventions they all share.
The pages under this section document every endpoint of the public API: its parameters, request and response bodies, and the scope its key needs. They are generated from the API's own source code, so they change when the API does. The same description is available as an OpenAPI spec at /openapi.json.
Conventions
These hold on every endpoint, so the individual pages do not repeat them.
| Convention | What holds |
|---|---|
| Base URL | https://api.mailcrate.io. Every workspace endpoint lives under /public/. |
| Authentication | Authorization: Api-Key mc_... on every request. See Authentication. |
| Scopes | Each page names the scope it needs, such as sending:write. On workspace endpoints GET needs read and everything else needs write. Organization endpoints use read and manage, and a few name their own scope, such as workspaces:provision. See API Keys & Scopes. |
| Bodies | JSON in, JSON out. Send Content-Type: application/json on writes. |
| Status codes | 200 for success, POST included. A few POSTs answer 201 instead, mostly ones that create a credential or a workspace; each page shows which. |
| Ids | UUIDs. Contacts also accept their external identifier where an id is expected, and some routes accept an email address (the path parameter is then called idOrEmail). Templates accept their slug. |
| Times | ISO 8601 strings in UTC, such as 2026-10-21T09:30:00.000Z. |
| Lists | Paged with limit and offset, in a { data, total, limit, offset } envelope. See Pagination. |
| Errors | One envelope everywhere. Branch on the status and code, never on message. See Errors. |
| Rate limits | Per key, with X-RateLimit-* headers on every response. See Rate Limits. |
Every workspace endpoint acts on the workspace that owns the key. None of them take a workspace id.
Resources
Sending
Send one email, or a batch of up to 500.
Email Templates
Create, preview and push templates.
Contacts
Create, update and unsubscribe contacts.
Events
Record what your contacts do, for segments and journeys.
Segments
Segments and their members.
Subscription Groups
Groups a contact can opt in to or out of.
Suppression
Addresses Mailcrate will not send to.
Campaigns
Create, schedule, send and measure campaigns.
Journeys
Enroll and exit contacts, read enrollments and stats.
Journey Hooks
Enroll from any system with a trigger URL, no key needed.
Deliveries
What happened to every email you sent.
Webhooks
Manage endpoints and inspect delivery attempts.
Inbound
Receive mail and read what arrives.
Sender Identities
The from addresses you can send as.
Sending Domains
Domains, DNS records and tracking domains.
Workspace
Postal address, quota, frequency cap and send window.
Organization
Provision tenant workspaces with an organization key.
External audiences, branding and hosted page domains are in the sidebar too.
Response bodies
Request bodies and parameters are complete. A handful of responses, mostly deletes and previews, are not described in detail yet; they are JSON objects, and the page says so when the shape is open. The descriptions fill in as the API's response types are tightened.