Get a mailbox token

POST/api/v1/mailbox-auth/login
No token needed: this is how you get amailbox token.

Exchanges a mailbox's own email address and password for a token. Send it as Authorization: Bearer <token> on every other Mailbox API call.

Two-factor. If the mailbox has two-factor sign-in on, the first call answers two_factor_required: true and no token. Call again with the same email and password plus two_factor_code (or a recovery code).

How long it lasts. A browser session lasts 8 hours idle and 7 days at most. An app that sends X-Client-Platform gets 30 days idle and 180 days at most. expires_at and idle_timeout_seconds say exactly.

Temporary password. If an admin reset the password, you still get a token, with must_change_password: true. Until POST /security/password succeeds, every other call is refused, except logout.

The password is checked by the mail server itself, so it is always the same password a mail app uses.

Errors

Status When
401 Wrong email or password, or a wrong two-factor code. The message is the same for both, on purpose: Invalid email or password.
422 email_address or password is missing or too long.
429 Too many failed attempts from this IP or for this address: Too many failed attempts. Try again later.

Parameters

NameInTypeDescription
X-Client-PlatformheaderstringYour app's platform, for the longer app sessions: ios, android, macos, windows or linux. Leave it out from a browser.

Request body

  • email_addressstringrequired

    The mailbox's full address.

  • passwordstringrequired

    The mailbox password: the same one a mail app uses.

  • two_factor_codestring or null

    Only when the first call answered two_factor_required: the 6-digit code from the authenticator app, or a recovery code.

Request

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

Response

Signed in, or (with two-factor on and no code sent) a request for the code.

  • dataobject
    • tokenstring

      Send as Authorization: Bearer <token>.

    • expires_atstring

      When the session ends at the latest (ISO 8601 with offset).

    • idle_timeout_secondsinteger

      The session ends after this long without a call.

    • email_addressstring
    • email_accountobject
      • idstring
      • email_addressstring
      • namestring or null
    • must_change_passwordboolean

      True: change the password first (POST /security/password).

    • password_change_reasonstring or null
    • client_platformstring or null

      The platform the server read from X-Client-Platform. Null means a web browser.

    • csrf_tokenstring

      Only for browsers using the session cookie instead of the token.

    • two_factor_requiredboolean

      Only on the two-factor prompt: no token yet, send two_factor_code.

200application/json
{
  "type": "success",
  "msg": "Signed in",
  "data": {
    "token": "mbx_3q9Xk2Lr7...redacted",
    "expires_at": "2026-04-09T10:00:00+00:00",
    "idle_timeout_seconds": 2592000,
    "email_address": "ada@yourdomain.com",
    "email_account": {
      "id": "01J9ZK3M5Q8R2T4V6W8X0Y2Z4A",
      "email_address": "ada@yourdomain.com",
      "name": "Ada Obi"
    },
    "must_change_password": false,
    "password_change_reason": null,
    "client_platform": "ios",
    "csrf_token": "J3k...redacted"
  }
}

Returned inside the standard envelope.

Errors

StatusWhen
401Wrong email or password, or a wrong two-factor code. The message is the same for both, on purpose: `Invalid email or password`.
422`email_address` or `password` is missing or too long.
429Too many failed attempts from this IP or for this address: `Too many failed attempts. Try again later.`

Every status, with what causes it and what to do, is on the error reference.