Mailbox (Webmail & Mobile)¶

The mailbox-holder surface -- what the open-source webmail and the mobile app are built on. Everything lives under the /api/v1/mailbox prefix and is authenticated by a mailbox session (see Authentication -- Mailbox Sessions): the mailyte_mailbox_session cookie the login sets, or Authorization: Bearer <token> for a native client.

No route here carries an account id. The session says which mailbox the request is for, which makes cross-mailbox access structurally impossible rather than a per-route check. Responses use the standard envelope ({"type", "msg", "data"}); some errors additionally carry a stable error_code the client can branch on. A 502 always means the mail server itself was unreachable -- nothing the caller sends can fix it.

This page covers folders, messages, sending, contacts and settings. The same router also serves GET /capabilities, the security/2FA group, optional AI assistance, and the Sieve-backed rules/forwarding/vacation group -- the capability manifest says which of those exist on a deployment.

Capabilities¶

GET /api/v1/mailbox/capabilities

Runtime feature detection: which optional groups are configured on this deployment (rules, forwarding, vacation, ai, ...). Clients fetch it right after sign-in and hide any control it does not advertise.

Folders¶

List Folders¶

GET /api/v1/mailbox/folders

Response data -- an array, INBOX first, then special-use, then the rest alphabetically:

Create Folder¶

POST /api/v1/mailbox/folders

Creates and subscribes the folder. Labels are folders here. Returns the full folder list.

Rename Folder¶

PATCH /api/v1/mailbox/folders/{folder}

{folder} is the id from the folder list (the literal name is also accepted for flat folders, but names can contain /, so the id is the form to store).

A nested folder keeps its parent (Clients/Acme renamed to Acme Ltd becomes Clients/Acme Ltd), and subfolders move along with it. Returns {"id", "name", "folders"} -- the rename changes the folder's id, and every message id minted under the old name with it.

Errors

Delete Folder¶

DELETE /api/v1/mailbox/folders/{folder}

Deletes an empty, non-special folder (unsubscribing it first) and returns the updated folder list.

Errors

Messages¶

List Messages¶

GET /api/v1/mailbox/messages

Query Parameters

Response data: {"messages", "total", "offset", "limit", "has_more", "folder"}. Each row carries:

id, folder, subject, from/to/cc/bcc/reply_to (arrays of {name, email}), received_at (ISO 8601 or null), size, has_attachment, is_read, is_starred, is_answered, is_draft, preview (~200 chars or null), and the threading identifiers below.

Threading fields (list rows and detail, always present, null when the message carries no identifier):

is_answered reflects the IMAP \Answered flag; the send route sets it on the original when a reply goes out (see Send).

Read One Message¶

GET /api/v1/mailbox/messages/{message_id}

Everything a list row has, plus body_text, body_html (each string or null), attachments (below), and the provenance block -- fields read from headers the receiving side stamped, never from anything the sender wrote for display. Each is always present and null when absent:

Each entry of attachments:

Reading a message does not mark it read (the fetch uses BODY.PEEK); the client says so explicitly via /mark-read.

Download the Original (raw RFC 822)¶

GET /api/v1/mailbox/messages/{message_id}/raw

The stored bytes exactly as the mail server holds them -- headers, MIME structure and encodings untouched, never a re-serialisation. Returned as Content-Type: message/rfc822 with Content-Disposition: attachment and a sanitised <subject>-<uid>.eml filename. This is what "Show original" / "Download .eml" load. Does not mark the message read.

Attachments¶

GET /api/v1/mailbox/messages/{message_id}/attachments
GET /api/v1/mailbox/messages/{message_id}/attachments/{index}

The list route returns the same array as the detail view. The download route streams the decoded part with its own content type; Content-Disposition is always attachment (rendering sender-supplied HTML in the app's origin would be stored XSS). A stale index is a 404.

Thread¶

GET /api/v1/mailbox/messages/{message_id}/thread

The conversation the message belongs to, oldest first, as list-row objects. Follows Message-ID / In-Reply-To / References -- never subject lines -- searching the message's own folder plus Sent.

Flags¶

POST /api/v1/mailbox/messages/{message_id}/mark-read
POST /api/v1/mailbox/messages/{message_id}/mark-unread
POST /api/v1/mailbox/messages/{message_id}/star
POST /api/v1/mailbox/messages/{message_id}/unstar

Each sets or clears one IMAP system flag and answers {"type": "success", "msg": "Message updated"}.

Move, Trash, Delete¶

POST /api/v1/mailbox/messages/{message_id}/move      {"folder": "<name>"}
POST /api/v1/mailbox/messages/{message_id}/trash
DELETE /api/v1/mailbox/messages/{message_id}

move and trash return the message's new id. Trashing something already in Trash is a no-op, never a destroy. Permanent deletion is refused with 409 / error_code: not_in_trash unless the message is already in Trash -- nothing outside Trash is ever destroyed.

Drafts¶

POST /api/v1/mailbox/messages/draft
DELETE /api/v1/mailbox/messages/draft/{message_id}

Drafts are real messages in the Drafts folder, readable by every client on the account. Fields: to/cc/bcc (arrays or one comma-separated string), subject, body_text, body_html, in_reply_to, references, and replace_id (alias replaces_id) -- the draft this save supersedes, expunged only after the new copy lands. All fields tolerate being absent: autosave never fails on a half-typed message. Returns {"id", "folder"}.

The DELETE route permanently discards a draft (allowed outside Trash -- a discarded draft was never delivered mail).

Send a Message¶

POST /api/v1/mailbox/messages/send

Accepts JSON (no uploaded files) or multipart/form-data (with files). The From address is always the signed-in mailbox -- nothing the client sends can change it. Repeated fields are accepted both bare (to) and PHP-style (to[]).

Forwarded inline parts whose content_id the new body_html still references (cid:<content_id>) go out as inline parts under the same id, so pictures render where the original showed them; carried parts the body no longer references become ordinary attachments rather than being dropped. The 20-attachment / 25 MB limits apply to uploads and carried parts together.

Response data: {"id", "message_id", "answered_id"} -- the Sent copy's API id (null if filing failed after a successful send), the new message's RFC Message-ID, and the API id of the message that was flagged \Answered (null when in_reply_to was absent or the original could not be found).

Example (JSON reply)

curl -X POST -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["bob@example.net"],
    "subject": "Re: lunch?",
    "body_text": "Sounds good.",
    "in_reply_to": "<m1@example.net>",
    "in_reply_to_id": "INBOX:1042",
    "references": "<m0@example.net> <m1@example.net>"
  }' \
  http://your-server:8083/api/v1/mailbox/messages/send

Example (forward with carried attachments)

curl -X POST -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["carol@example.com"],
    "subject": "Fwd: contract",
    "body_html": "<p>FYI</p>",
    "forward_attachments_from": "INBOX:1042",
    "attachment_indexes": [2, 3]
  }' \
  http://your-server:8083/api/v1/mailbox/messages/send

Contacts¶

GET /api/v1/mailbox/contacts

Addresses this mailbox actually corresponds with -- harvested from Sent and INBOX headers, most-used first, as {name, email, count} -- for compose autocomplete. There is no address book to maintain.

Settings¶

Read Settings¶

GET /api/v1/mailbox/settings

Response data

Update Settings¶

PUT /api/v1/mailbox/settings

Partial update -- only the fields present change. The signature is sanitised against an allowlist before storage (it is HTML this server later attaches to outgoing mail); an unsafe signature is a 422 with the reason. Returns the same payload as the read.

Related groups on this router¶

• Security & two-factor -- GET /security, POST /security/2fa/*, GET/DELETE /security/sessions*. Mailbox 2FA gates the webmail sign-in only, never IMAP/SMTP.
• AI assistance -- POST /ai/compose, POST /ai/summarize/{message_id}; present only when the deployment configures an endpoint (503 / ai_not_configured otherwise).
• Rules, forwarding, vacation -- GET/PUT /rules, /forwarding, /vacation; Sieve-backed, absent without a ManageSieve master credential (503 / sieve_not_configured).