API Reference
Zmail exposes four API surfaces:
- API key APIs for server-to-server calls
- Session APIs under
/app/api/*for product app and CLI - Scoped service-token APIs under
/v1/transactional/* - Mailbox capability-token APIs under
/public/*
Which workspace may use a domain:
MAIL_DOMAINbelongs to the platform workspace (tenant 1). Inbound mail
for it is delivered there.
- Any other domain belongs to the workspace that verified it as a sending
domain.
Mailboxes are created, and mail is sent, only on a domain the workspace may
use. Otherwise the request gets 400 (a domain the workspace has not
verified) or 403 (MAIL_DOMAIN outside the platform workspace). The
outbox worker applies the same domain rule again when it sends, so a queued
message whose sender the rule refuses by then is not sent: its status is
failed with the reason, and a message.failed webhook carries it.
Browsers on other origins get no CORS grant unless the origin is listed in
ZMAIL_CORS_ALLOWED_ORIGINS, and listed origins never get credentials. Call
from a server, or send a Bearer token.
1. API Key APIs
Auth header:
Authorization: Bearer <ZMAIL_API_KEY>- Optional tenant scoping:
X-Tenant-ID: <tenant_id>
Health
GET /health
Mailboxes
GET /mailboxesPOST /mailboxes?address=<email>&description=<text>: the address must be
on a domain the X-Tenant-ID workspace may use
GET /mailboxes/{address}DELETE /mailboxes/{address}
Messages
GET /inbox?mailbox=&folder=inbox&limit=50&offset=0GET /messages/{message_id}?mark_read=truePOST /messages/{message_id}/read?read=truePOST /messages/{message_id}/move?folder=archiveDELETE /messages/{message_id}
Sending
POST /send- Body:
from_mailbox,to,subject,body, optionalhtml from_mailbox(defaultnoreply@<MAIL_DOMAIN>) must be on a domain the
X-Tenant-ID workspace may use. It need not be a mailbox, so
noreply@ works.
Stats and Spam
GET /statsPOST /messages/{message_id}/spamPOST /messages/{message_id}/not-spam
2. Session APIs (/app/api/*)
Auth header:
X-Zmail-Session: <session_token>
Session and Workspace
POST /app/api/loginPOST /app/api/logoutGET /app/api/sessionPOST /app/api/workspaces/select
Mailboxes
GET /app/api/mailboxesPOST /app/api/mailboxes: the address must be on a domain the active
workspace may use
Sending Domains and Service Tokens
These routes require an owner/admin session in the active workspace.
GET /app/api/sending-domainsPOST /app/api/sending-domainsPOST /app/api/sending-domains/{domain_id}/verifyGET /app/api/service-tokensPOST /app/api/service-tokensPOST /app/api/service-tokens/{token_id}/rotateDELETE /app/api/service-tokens/{token_id}
Domain creation returns the DNS verification token once. Service-token creation
and rotation return plaintext credentials once; list responses never contain
them. Only message:send is currently supported.
Messages
GET /app/api/messagesGET /app/api/messages/{message_id}POST /app/api/messages/{message_id}/readPOST /app/api/messages/{message_id}/movePOST /app/api/messages/{message_id}/labelsGET /app/api/messages/{message_id}/threadGET /app/api/messages/{message_id}/attachmentsGET /app/api/messages/{message_id}/attachments/{attachment_id}
Threads
GET /app/api/threadsGET /app/api/threads/{thread_id}POST /app/api/threads/{thread_id}/labels
Drafts
GET /app/api/draftsPOST /app/api/draftsGET /app/api/drafts/{draft_id}PATCH /app/api/drafts/{draft_id}DELETE /app/api/drafts/{draft_id}POST /app/api/drafts/{draft_id}/send
Lists
GET /app/api/lists/{direction}/{list_type}POST /app/api/lists/{direction}/{list_type}GET /app/api/lists/{direction}/{list_type}/{entry:path}DELETE /app/api/lists/{direction}/{list_type}/{entry:path}
Outbound and Sent
POST /app/api/sendGET /app/api/sent
from_mailbox on sends and drafts must be one of the active workspace's
mailboxes, on a domain it may use (403 otherwise). A draft is checked
again when it is sent.
Webhooks
Creating, updating and deleting a webhook, and include_secret=true, require
an owner/admin session in the active workspace: a webhook copies the
workspace's mail to an outside URL. Members can list webhooks, read them
without the secret, see deliveries and send a test event.
GET /app/api/webhooksPOST /app/api/webhooksGET /app/api/webhooks/{webhook_id}PATCH /app/api/webhooks/{webhook_id}DELETE /app/api/webhooks/{webhook_id}GET /app/api/webhooks/{webhook_id}/deliveriesPOST /app/api/webhooks/{webhook_id}/test
3. Transactional Service API
Auth and idempotency headers:
Authorization: Bearer <scoped_service_token>Idempotency-Key: <stable caller request ID>
Create a message:
POST /v1/transactional/messages- Body:
from_mailbox,to,subject,body, optionalhtml,from_name,reply_to - Returns
202with stablemessage_idandstatus: queued
The token is bound to one workspace, verified sending domain, mailbox, and
message:send scope. The same key and canonical payload replay the original
202; reusing a key for different content returns 409. Tracking pixels are
disabled for this API.
Status lookup:
GET /v1/transactional/messages/{message_id}GET /v1/transactional/messages?idempotency_key=<key>
Statuses are queued, processing, accepted, failed, and unknown.
accepted means the SMTP peer accepted responsibility; it is not proof of
final inbox delivery. unknown is terminal and prevents an ambiguous SMTP
retry from duplicating authentication mail.
4. Mailbox Capability Tokens (/public/*)
A capability token reads and sends for exactly one mailbox. ZergDesk capture
uses one.
Mint one (owner or admin of the platform workspace, X-Zmail-Session):
POST /public/provision/mailbox- Body:
address(onMAIL_DOMAIN),owner_key, optionaldescription,
optional tenant_id (must be the session's workspace)
- Creates the mailbox if it does not exist. Returns
capability_token. The
first owner_key keeps the mailbox, and a different key gets 409. The
same owner_key gives back the mailbox's current token, so an operator can
re-mint a lost token from the key it was claimed with (zerg:<uuid> for an
agent the zcloud bridge claimed).
Re-key one (owner or admin of the platform workspace, X-Zmail-Session):
POST /public/provision/mailbox/rekey- Body:
address(onMAIL_DOMAIN), optionalowner_key(a new owner key;
omitted, the mailbox keeps its own)
- Gives the mailbox's capability row a new random salt, so every token issued
for it before gets 401, and returns the new capability_token. The
mailbox and its mail stay. 404 when the mailbox has no capability token
(mint one instead), 400 for a blank owner_key or an address off
MAIL_DOMAIN, 403 outside the platform workspace.
Revoke one (owner or admin of the session's workspace, X-Zmail-Session):
POST /public/provision/mailbox/revoke- Body:
address - Deletes the mailbox's capability row in the session's workspace: every
token issued for it gets 401, and a later mint makes a new row with a new
salt, so none of them comes back. The mailbox and its mail stay. 404 when
the workspace has no capability token for that address.
The routes act only in the session's workspace. For a row in another
workspace (the anonymous endpoint took any tenant), the platform operator
runs manage.py revoke-capability or `rekey-capability --tenant N --address
A on the host; see docs/deployment-operations.md`.
Use one (Authorization: Bearer <capability token>):
GET /public/mailboxGET /public/inbox?folder=inbox&limit=50&offset=0GET /public/messages/{message_id}and/threadPOST /public/send: sends as the token's mailbox;reply_to_message_id
must be a message in that mailbox
5. ZergAI Platform Calls (/api/service/zergai/*)
Only ZergAI calls these. Each request carries
Authorization: ZergPlatform v1 kid=..,ts=..,nonce=..,sig=.., an Ed25519
signature for the zmail audience from a key in ZERGAI_PLATFORM_PUBLIC_KEYS
(contract zergai/api/directory/contracts/platform-signature.v1.vectors.json).
Bodies are at most 16 KiB. Every signature refusal (malformed header, oversized
body, unknown key, clock skew over 300 s, bad signature, replayed nonce) is the
same 401 {"code": "platform_signature_invalid"}.
Link a ZergAI workspace to its Zmail tenant (contract
platform-provisioning.v1; one workspace is one tenant):
PUT /api/service/zergai/organizations/{directory_organization_id}200 {"tenant_id": "<id>", "slug": "...", "status": "provisioned" | "adopted" | "unchanged"}- Creates a tenant with the workspace owner as its
owner, adopts the tenant
named by adopt_existing (a canonical decimal tenant id; its members and
mailboxes stay), or answers unchanged for a workspace already linked (the
tenant is never renamed).
- Refusals:
404 tenant_not_found,409 tenant_already_linked,
409 directory_organization_already_linked, 409 owner_account_link_required
(a Zmail account already holds the owner's email; it is never taken over),
422 tenant_id_not_canonical, 422 tenant_not_adoptable,
422 owner_issuer_mismatch, 422 owner_subject_invalid,
422 invalid_request, 422 directory_organization_mismatch.
End the sessions ZergAI revoked (contract backchannel-logout.v1):
POST /api/service/zergai/backchannel-logout200 {"status": "logged_out" | "duplicate"}: every session of the
(issuer, subject) begun before iat plus 5 seconds ends; each jti is
applied once. While ZMAIL_ZERGAI_ORGANIZATIONS=on, a notice with reason
admin (ZergAI lowered or removed the person's access to a workspace,
without saying which, or deactivated them) also withdraws every membership
ZergAI granted before iat plus 5 seconds, so a Zmail password cannot keep
them; the next Sign in with Zerg restores whatever ZergAI still grants. A
membership ZergAI granted later (a sign-in whose claim listed it, or a
provisioning call that added it) stays, as a session begun then does: ZergAI
retries a notice for about 5.5 hours, so it can arrive late. With the claim
off it ends sessions only: nothing would restore a withdrawn membership, and
the only ones ZergAI granted are the owners of provisioned tenants.
Memberships that began in Zmail stay.
- A
session_logoutnotice (contractbackchannel-session-logout.v1) on the
same route ends only the browser session whose sign-in that ZergAI session
(sid) authorized. Zmail keeps its (issuer, subject, sid) for 30 days
and refuses a later Zerg sign-in whose userinfo names it: the callback
issues no session and sends the browser to
/login?sso_error=zergai_session_ended.
- Refusals:
400 invalid_notice(breaks the contract, oriatmore than
300 s ahead), 422 issuer_mismatch.
Response Conventions
- Success responses use object payloads and include
ok/successwhere appropriate. - Errors return JSON with
errorordetailand HTTP status code.
cURL Examples
# API-key mailbox list
curl -sS https://zerg-mail.com/mailboxes \
-H "Authorization: Bearer $ZMAIL_API_KEY" \
-H "X-Tenant-ID: 1"
# Session login
curl -sS https://zerg-mail.com/app/api/login \
-H "content-type: application/json" \
-d '{"email":"you@example.com","password":"***"}'
# Create webhook in active workspace
curl -sS https://zerg-mail.com/app/api/webhooks \
-H "content-type: application/json" \
-H "X-Zmail-Session: $SESSION" \
-d '{"url":"https://example.com/webhooks/zmail","event_types":["message.received"]}'
# Queue transactional auth mail
curl -sS https://zerg-mail.com/v1/transactional/messages \
-H "Authorization: Bearer $ZMAIL_SERVICE_TOKEN" \
-H "Idempotency-Key: core-auth-email:$OUTBOX_ID" \
-H "content-type: application/json" \
-d '{"from_mailbox":"auth@example.com","to":"user@example.net","subject":"Verify","body":"Code: 123456"}'