Building on the Mailbox API

Everything the Mailyte webmail does — folders, messages, drafts, scheduled send, calendars, contacts, rules, vacation replies — is available over the Mailbox API.

It is a different credential from the rest of this documentation, and that is the whole idea.

Two tiers, and why

An organization key provisions a mailbox. It deliberately cannot read what is in it. If it could, one leaked integration credential would expose every employee's correspondence — so the capability does not exist rather than being guarded.

To act as a person, you authenticate as that person.

Get a token

curl -X POST "$MAIL_SERVER/api/v1/mailbox-auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email": "ada@yourdomain.com", "password": "her-mailbox-password"}'

The response carries a token. Send it as Authorization: Bearer <token> on every Mailbox API call.

These endpoints are served by the mail server rather than the application API — the mailbox surface moved there so that reading mail never passes through the application that manages billing. One consequence you will notice: the base URL is different. Everything else behaves the same way.

List messages

curl "$MAIL_SERVER/api/v1/mailbox/messages?folder=INBOX&limit=25" \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Folders, search, threads, attachments and the raw source are all available — see the Mailbox API reference.

Send as the mailbox holder

curl -X POST "$MAIL_SERVER/api/v1/mailbox/messages/send" \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": ["colleague@example.com"],
    "subject": "Re: the quarterly numbers",
    "text": "Attached."
  }'

This is a person sending mail, so it lands in their Sent folder and comes from their address. That is different from POST /api/v1/messages, which is your application sending mail on the organization's behalf.

Bcc

Pass bcc as its own field. Do not fold blind recipients into a header you construct yourself — Bcc: has to be removed before the message reaches the transport, and no MTA does that for you. Getting it wrong discloses every hidden recipient to every recipient, which is unrecoverable.

Scheduled send

curl -X POST "$MAIL_SERVER/api/v1/mailbox/messages/send" \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": ["colleague@example.com"],
    "subject": "Monday morning",
    "text": "Sent while I was asleep.",
    "send_at": "2026-09-22T08:00:00Z"
  }'

Scheduled messages live in a Scheduled folder until they go, and can be cancelled before then. Send times are UTC. Convert in your own interface; do not send a local time and hope.

Building a client

If you are writing a mail client against this, the two things worth knowing up front:

Message ids are opaque. Do not parse them, and do not strip characters you find surprising. Angle brackets are part of the id, and removing them is a real bug that once 404'd every inbound message here.

Dates are UTC, everywhere. Format for display at the edge.

Next

Provisioning mailboxes — creating the mailboxes this API then acts on.