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.

The base URL

The Mailbox API is served by the mail server, not by app.mailyte.com — that address answers every mailbox call with 404.

The examples below use $MAIL_SERVER for it:

export MAIL_SERVER=https://courier.mailyte.com

Get a token

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

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

{
  "type": "success",
  "msg": "Signed in",
  "data": {
    "token": "mbx_3q9Xk2Lr7...",
    "expires_at": "2026-10-18T10:00:00+00:00",
    "idle_timeout_seconds": 28800,
    "email_address": "ada@yourdomain.com",
    "must_change_password": false
  }
}

If the mailbox has two-factor sign-in on, the first answer is "two_factor_required": true with no token: send the same request again with "two_factor_code". A wrong password, a wrong code and an unknown address all answer 401 Invalid email or password, so nobody can tell which part was wrong.

Every Mailbox API answer has this shape — type is success or error, msg says what happened in words, and data carries the result. Errors also carry a correlation_id to quote to support.

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 (see above). 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",
    "body_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.

Retrying a send safely

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",
    "body_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.