Authentication and access

API 0.16.0OpenAPIllms-full.txt

Sign in with a link

Your server calls POST /v1/auth/login-link with X-API-Key and X-Customer-ID. Set mailbox_id to open only that mailbox; omit it to open the entire account. locale selects the interface language.

The response contains login_url, expires_in=300, expires_at (UTC), account_id and mailbox_id. Your “Open mail” button opens the complete login_url, including #token. The link is valid for 5 minutes and one use only. Do not log it or expose the API key in the browser.

The sign-in page removes the token from the address bar and exchanges it for HttpOnly cookies. If it fails or expires, create a new link. Access scope and account and mailbox status are checked again. User sessions cannot create links.

curl https://adapt-mail.com/v1/auth/login-link \
  -H "X-API-Key: <mail-api-key>" \
  -H "X-Customer-ID: <mail-account-id>" \
  -H "Content-Type: application/json" \
  --data '{"mailbox_id":42,"locale":"en"}'

{
  "login_url": "https://adapt-mail.com/auth/#token=<one-time-token>",
  "expires_in": 300,
  "expires_at": "2026-10-20T12:05:00Z",
  "account_id": 123,
  "mailbox_id": 42
}

Partner key

Use your integration’s mail API key in X-API-Key and the mail account ID in the required X-Customer-ID header. This is the account ID, not external_id or a mailbox ID. The key grants access only to your integration’s customers.

Store the key on your partner's server. Do not place the shared integration key in the browser or mobile application.

curl 'https://adapt-mail.com/v1/mailboxes' \
  -H 'X-API-Key: <mail-api-key>' \
  -H 'X-Customer-ID: <mail-account-id>'

User token

POST /v1/auth/token accepts login, password and mode. For mode=account the login user-ID is used, for mode=mailbox the full mailbox address is used. Account and mailbox passwords are independent.

The response contains access_token, token_type=Bearer and expires_in=3600. An account token grants access to its mailboxes; a mailbox token is restricted to that mailbox. Obtain a new token when it expires.

POST /v1/auth/token
Content-Type: application/json

{"login":"user-123","password":"<password>","mode":"account"}

GET /v1/mailboxes
Authorization: Bearer <access_token>

Browser sessions

POST /v1/auth/login is reserved for adapt-mail.com. It requires the correct Origin and sets HttpOnly cookies. The non-secret X-Mail-Session selector chooses a saved session; it does not grant access without the corresponding cookie.

For a third-party frontend, use your own backend with a user token. Arbitrary cross-origin cookie access is not supported; the service does not enable public CORS for every website.