Zmail Docs
operator + agent reference for zmail.zergai.com
source: docs/api-reference.md

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_DOMAIN belongs 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 /mailboxes
  • POST /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=0
  • GET /messages/{message_id}?mark_read=true
  • POST /messages/{message_id}/read?read=true
  • POST /messages/{message_id}/move?folder=archive
  • DELETE /messages/{message_id}

Sending

  • POST /send
  • Body: from_mailbox, to, subject, body, optional html
  • from_mailbox (default noreply@<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 /stats
  • POST /messages/{message_id}/spam
  • POST /messages/{message_id}/not-spam

2. Session APIs (/app/api/*)

Auth header:

  • X-Zmail-Session: <session_token>

Session and Workspace

  • POST /app/api/login
  • POST /app/api/logout
  • GET /app/api/session
  • POST /app/api/workspaces/select

Mailboxes

  • GET /app/api/mailboxes
  • POST /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-domains
  • POST /app/api/sending-domains
  • POST /app/api/sending-domains/{domain_id}/verify
  • GET /app/api/service-tokens
  • POST /app/api/service-tokens
  • POST /app/api/service-tokens/{token_id}/rotate
  • DELETE /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/messages
  • GET /app/api/messages/{message_id}
  • POST /app/api/messages/{message_id}/read
  • POST /app/api/messages/{message_id}/move
  • POST /app/api/messages/{message_id}/labels
  • GET /app/api/messages/{message_id}/thread
  • GET /app/api/messages/{message_id}/attachments
  • GET /app/api/messages/{message_id}/attachments/{attachment_id}

Threads

  • GET /app/api/threads
  • GET /app/api/threads/{thread_id}
  • POST /app/api/threads/{thread_id}/labels

Drafts

  • GET /app/api/drafts
  • POST /app/api/drafts
  • GET /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/send
  • GET /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/webhooks
  • POST /app/api/webhooks
  • GET /app/api/webhooks/{webhook_id}
  • PATCH /app/api/webhooks/{webhook_id}
  • DELETE /app/api/webhooks/{webhook_id}
  • GET /app/api/webhooks/{webhook_id}/deliveries
  • POST /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, optional html, from_name, reply_to
  • Returns 202 with stable message_id and status: 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 (on MAIL_DOMAIN), owner_key, optional description,

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 (on MAIL_DOMAIN), optional owner_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/mailbox
  • GET /public/inbox?folder=inbox&limit=50&offset=0
  • GET /public/messages/{message_id} and /thread
  • POST /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-logout
  • 200 {"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_logout notice (contract backchannel-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, or iat more than

300 s ahead), 422 issuer_mismatch.

Response Conventions

  • Success responses use object payloads and include ok/success where appropriate.
  • Errors return JSON with error or detail and 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"}'