Get a mailbox token
/api/v1/mailbox-auth/loginExchanges 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
| Name | In | Type | Description |
|---|---|---|---|
X-Client-Platform | header | string | Your app's platform, for the longer app sessions: ios, android, macos, windows or linux. Leave it out from a browser. |
Request body
email_addressstringrequiredThe mailbox's full address.
passwordstringrequiredThe mailbox password: the same one a mail app uses.
two_factor_codestring or nullOnly when the first call answered
two_factor_required: the 6-digit code from the authenticator app, or a recovery code.
Request
/api/v1/mailbox-auth/logincurl -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"
}'const response = await fetch('https://courier.mailyte.com/api/v1/mailbox-auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
"email_address": "ada@yourdomain.com",
"password": "her-mailbox-password"
}),
});
const { data } = await response.json();import requests
response = requests.post(
"https://courier.mailyte.com/api/v1/mailbox-auth/login",
json={
"email_address": "ada@yourdomain.com",
"password": "her-mailbox-password"
},
)
data = response.json()["data"]<?php
$response = Http::asJson()
->post('https://courier.mailyte.com/api/v1/mailbox-auth/login', [
'email_address' => 'ada@yourdomain.com',
'password' => 'her-mailbox-password',
]);
$data = $response->json('data');require "net/http"
require "json"
uri = URI("https://courier.mailyte.com/api/v1/mailbox-auth/login")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request.body = {
"email_address": "ada@yourdomain.com",
"password": "her-mailbox-password"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }Response
Signed in, or (with two-factor on and no code sent) a request for the code.
dataobjecttokenstringSend as
Authorization: Bearer <token>.expires_atstringWhen the session ends at the latest (ISO 8601 with offset).
idle_timeout_secondsintegerThe session ends after this long without a call.
email_addressstringemail_accountobjectidstringemail_addressstringnamestring or null
must_change_passwordbooleanTrue: change the password first (
POST /security/password).password_change_reasonstring or nullclient_platformstring or nullThe platform the server read from
X-Client-Platform. Null means a web browser.csrf_tokenstringOnly for browsers using the session cookie instead of the token.
two_factor_requiredbooleanOnly on the two-factor prompt: no token yet, send
two_factor_code.
application/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
| 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.` |
Every status, with what causes it and what to do, is on the error reference.