Authentication & API keys
Connect an external workflow to the right Mailat instance with the smallest useful set of permissions.
Start with your instance#
Mailat.co manages hosting and billing. Email requests go to your own Mailat application. All paths in the reference already begin with /api/v1.
export MAILAT_BASE_URL='https://mail.example.com'
export MAILAT_TOKEN='ue_REPLACE_WITH_YOUR_KEY'
curl "$MAILAT_BASE_URL/api/v1/domains" \
--header "Authorization: Bearer $MAILAT_TOKEN"
Create a key while signed in to your Mailat instance. Store it in the secret store of your workflow runner, never in a public frontend, repository or URL. Choose an expiry, set an appropriate rate limit and revoke unused keys. A key belongs to its creating user and organization; it cannot bypass resource ownership.
Choose scopes#
| Work | Scope |
|---|---|
| Mail details, attachments, change feed, reply context | email:read |
| Sending, attachment uploads and drafts | email:send |
| Marking, moving, labels and filters | email:manage |
| Read or configure domains | domains:read, domains:manage |
| Read or change sending identities | identities:read, identities:manage |
| Read or change templates | templates:read, templates:manage |
| Webhooks, tests, deliveries, secret rotation and replay | webhooks:manage |
The API reference states the exact scope for every operation, including contacts and lists. A read-only workflow should not receive management or sending permissions.
Human sessions and public routes#
Keys cannot create stronger keys, change account passwords, administer sessions or bypass MFA. Those operations are labelled Human session in the reference. “Public / special authentication” means the normal bearer middleware does not apply; callback signatures, one-time tokens or other validation may still be required.
Browser event streams use a short-lived stream ticket. Headless SSE clients can use a bearer key with email:read; do not put API keys in query strings.
Errors and pagination#
Most JSON results use { "code": 0, "message": "...", "data": ... }. Check the HTTP status and the endpoint's response schema. Pagination is endpoint-specific: received mail returns emails, total, unread, page, pageSize and totalPages; webhook deliveries return deliveries, page, pageSize and total.
- 400: correct the request, including required values and formats.
- 401 / 403: check key expiry, user state, scope and ownership. Do not retry with escalating privileges.
- 409: resolve a conflicting change or reused idempotency key with different content.
- 410: a recovery cursor expired; take a new snapshot.
- 429: wait for the
Retry-Afternumber of seconds. Limits are checked per key in a database-backed minute window. - 5xx / timeout: retry with bounded backoff. For sends, preserve the same idempotency key and payload.
Your running instance's /api/v1/openapi.json is the contract for that release. The hosted reference displays its pinned source revision and download hash.