-
Notifications
You must be signed in to change notification settings - Fork 1
API Reference
All API routes are served from /api/ and return JSON. There are two authentication models:
-
Session Auth — Cookie-based. The
auth_sessioncookie must be present (set automatically after login). Used by all UI-facing endpoints. -
Webhook Auth — Header-based. The
x-webhook-secretheader must match theWEBHOOK_SECRETenv variable. Used only by the Cloudflare Worker inbound endpoint.
Responses follow a consistent envelope format:
// Success
{ "success": true, "data": { ... } }
// Error
{ "success": false, "error": "Error message" }Log in with email and password. Sets the auth_session cookie on success.
Body:
{ "email": "user@example.com", "password": "yourpassword" }Clears the session cookie and invalidates the server-side session.
Returns the currently authenticated user's profile.
Triggers a password reset email. Always returns success (see Users & Access for why).
Body: { "email": "user@example.com" }
Resets the password using a valid token from the reset email.
Body: { "token": "<reset-token>", "password": "newpassword" }
Validates an invite token before the user sets a password.
Accepts an invitation and sets the user's password.
Body: { "token": "<invite-token>", "password": "newpassword" }
Auth: x-webhook-secret header
Called by the Cloudflare Worker when an inbound email arrives. Accepts a parsed MIME payload and stores it in the database.
Body:
{
"messageId": "<unique-message-id>",
"from": { "address": "sender@example.com", "name": "Sender Name" },
"to": [{ "address": "support@yourcompany.com" }],
"subject": "Hello",
"text": "Plain text body",
"html": "<p>HTML body</p>"
}Auth: Session
Returns a paginated list of emails. Results are filtered by the user's mailbox access.
Query params:
| Param | Type | Default | Description |
|---|---|---|---|
page |
number | 1 |
Page number |
limit |
number | 20 |
Results per page (max 100) |
search |
string | — | Full-text search across subject and body |
trashed |
boolean | false |
Return trashed emails only |
starred |
boolean | false |
Return starred emails only |
Auth: Session
Returns a single email by ID. Respects mailbox access control.
Auth: Session
Updates the state of an email for the current user.
Body: { "action": "read" | "unread" | "save" | "unsave" | "trash" | "restore" }
Auth: Session
Permanently deletes an email. The email must be in the trash first.
Auth: Session
Returns sent email jobs from the queue, ordered by creation date.
Auth: Session
Validates sender mailbox access, then enqueues the email as a background job.
Body:
{
"fromId": "<mailbox-address-id>",
"to": "recipient@example.com",
"cc": "cc@example.com",
"bcc": "bcc@example.com",
"subject": "Subject",
"bodyText": "Plain text",
"bodyHtml": "<p>HTML</p>",
"attachments": [{ "filename": "file.pdf", "content": "<base64>", "contentType": "application/pdf" }]
}Auth: Session
Returns all drafts for the current user, grouped as threads.
Auth: Session
Creates a new draft. All fields are optional — a draft can be empty.
Body:
{
"mailboxAddressId": "<id>",
"to": "recipient@example.com",
"subject": "Draft subject",
"bodyText": "Plain text",
"bodyHtml": "<p>HTML</p>"
}Auth: Session — Returns a single draft by ID.
Auth: Session — Updates an existing draft.
Auth: Session — Permanently deletes a draft.
Auth: Session
Returns all inbound emails grouped into conversation threads, sorted by latest message. Supports starred and trashed query params.
Auth: Session — Returns all mailbox addresses.
Auth: Session (Owner/Admin) — Creates a new mailbox address and registers it with Cloudflare.
Body: { "address": "support@yourcompany.com", "displayName": "Support" }
Auth: Session (Owner/Admin) — Deactivates and removes a mailbox address.
Auth: Session (Owner/Admin) — Returns all users with their pending invite status.
Auth: Session (Owner/Admin) — Creates a new user and sends an invite email.
Auth: Session (Owner/Admin) — Updates a user's profile, role, or mailbox access.
Auth: Session (Owner) — Permanently deletes a user. Cannot delete the Owner.
Auth: Session — Returns the current user's profile.
Auth: Session — Updates the current user's name and email.
Auth: Session — Changes the current user's password.
Body: { "currentPassword": "old", "newPassword": "new" }
Auth: Session (Owner) — Links a Cloudflare domain by deploying the Worker and routing rules. The token is used immediately and never stored.
Auth: Session (Owner) — Removes the Cloudflare Worker and routing rules.
Returns whether the initial setup has been completed (i.e., if an Owner account exists). Used to gate the setup wizard.
Creates the initial Owner account. Only works if no Owner exists yet.
Auth: Session (Owner) — Returns the active database engine and connection info for diagnostics.