API Reference

Zmail exposes two API surfaces:

• API key APIs for server-to-server calls
• Session APIs under /app/api/* for product app and CLI

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>
• 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

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

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

Webhooks

• 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

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"]}'