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, scheduled_send, ...). Clients fetch it right after sign-in and hide any control it does not advertise.

Keys are only ever added, never renamed -- this is a published contract and a rename is a breaking change for every self-hoster. An absent key means absent: a client reading scheduled_send off an older server gets undefined, which must read as "no", not as "probably yes".

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"}. A message that no longer exists (moved or deleted by another client) is a 404 with error_code: not_found -- IMAP itself answers a STORE on a missing UID with a silent OK, so the server checks first.

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 {"id": <new id>} -- the destination UID from COPYUID, or null if the server reported none. Trashing something already in Trash is a no-op that returns the same id, 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, and the expunge is UID EXPUNGE of that one UID, so messages another client has flagged \Deleted without expunging are left alone.

Errors (all three, and the flag routes above)

Bulk Actions¶

POST /api/v1/mailbox/messages/bulk

One action on many messages in one request: one IMAP connection per mailbox the ids live in, and one SELECT + one UID SEARCH + one UID command per folder. The per-message routes above cost a full connection each.

• trash resolves Trash by role. Ids already in Trash succeed with new_id equal to their own id.
• delete destroys only ids already in Trash; the rest get not_in_trash.
• A move into or out of Junk emits spam.reported / spam.false_positive and trains the classifier exactly as the single-message move does.

Response -- always 200 once the request itself is valid; the result list is the answer:

{
  "type": "success",
  "msg": "2 of 3 messages moved",
  "data": {
    "results": [
      { "id": "INBOX:4521", "ok": true,  "new_id": "Archive:88" },
      { "id": "INBOX:4522", "ok": true,  "new_id": "Archive:89" },
      { "id": "INBOX:4523", "ok": false, "error_code": "not_found",
        "message": "That message no longer exists" }
    ],
    "succeeded": 2,
    "failed": 1
  }
}

new_id appears on move and trash results only (and may be null, as above). Each failed result's error_code corresponds to the status the single-message route would have answered:

The request is a 502 only when the mail server could not be reached for any id at all; 422 when ids is empty or over 500, move has no folder, or labels has nothing to add or remove.

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. Accepts JSON, or multipart/form-data when the draft carries new files. Repeated fields are accepted bare or PHP-style (to[]). All fields tolerate being absent: autosave never fails on a half-typed message.

The 20-attachment / 25 MB limits cover new files and kept parts together. A carried inline image the new body_html still references by cid: stays inline under the same id.

Response data: {"id", "folder", "attachments"} -- the new draft's id and its attachment list, shaped as on Read One Message. Indexes change whenever the MIME structure does, so a client uses the ones from the latest save; it never has to fetch the draft again to learn them.

Errors

The DELETE route permanently discards a draft (allowed outside Trash -- a discarded draft was never delivered mail). It is refused with 409 / error_code: not_a_draft for any message not in the Drafts folder, and answers 404 / not_found for a draft that is already gone.

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).

Schedule Send¶

Setting send_at on the send route stores the message and sends it later, rather than now.

curl -X POST -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":["bob@example.net"],"subject":"Monday","body_text":"Morning.",
       "send_at":"2026-09-15T08:00:00Z"}' \
  http://your-server:8083/api/v1/mailbox/messages/send

Response data: {"id", "folder", "send_at", "message_id"} -- the id the message can be cancelled by, the folder it is waiting in, and the time it will go, echoed back to the second.

Where the message waits matters: it is APPENDed to the mailbox's own Scheduled folder as an ordinary message, so a pending send is visible in Outlook, Thunderbird and on a phone, not only in the webmail. The folders route reports it with role: "scheduled".

• send_at is an absolute instant. Any ISO-8601 form is accepted; one with an offset (...Z, +01:00) is unambiguous and is what a client should send. A naive value is read as the server's local time.
• It must be at least a minute ahead and at most a year (SCHEDULED_SEND_MIN_LEAD_SECONDS, SCHEDULED_SEND_MAX_AHEAD_DAYS). Outside that, 422 with a message to show the user.
• The message is assembled at schedule time by the same builder a send uses, so what goes out is what was written.
• The api service sweeps for due messages every SCHEDULED_SEND_SWEEP_SECONDS (30 by default), under a MySQL advisory lock so replicas never double-send.
• Moving or deleting the stored message in another client cancels the send. The sweeper finds no message and drops the schedule rather than sending some other copy.
• A send that fails permanently leaves the message in Scheduled and the schedule marked failed with the reason -- it is never silently dropped, and never retried once it may already have reached Postfix.

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

GET returns {"messages": [...]}, each {"id", "folder", "send_at", "status", "attempts", "error", "created_at"}, soonest first. id is the ordinary FOLDER:UID message id, so this joins onto a folder listing rather than duplicating it. status is pending or failed; failed ones are included deliberately.

DELETE cancels: the message is moved back to Drafts, never destroyed, and the schedule is forgotten. Returns {"id", "folder"} with the id in Drafts (null if the server did not report it). 404 if that message is not scheduled, or -- with error_code: not_found -- if it has already left the Scheduled folder, which in practice means it was sent.

Capability key: scheduled_send on GET /api/v1/mailbox/capabilities. A client must gate on it -- a server that predates this ignores send_at and sends the message immediately.

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).