Авторизация и области доступа
Вход по ссылке
Сервер партнёра вызывает POST /v1/auth/login-link с X-API-Key и X-Customer-ID. Укажите mailbox_id для входа только в этот ящик; без него откроется весь аккаунт. locale выбирает язык интерфейса.
Ответ содержит login_url, expires_in=300, expires_at (UTC), account_id и mailbox_id. Кнопка «Войти в почту» открывает login_url целиком, включая #token. Ссылка действует 5 минут и только один раз. Не сохраняйте её в логах и не передавайте API-ключ в браузер.
Страница входа удаляет токен из адресной строки и обменивает его на HttpOnly cookies. При ошибке или истечении срока создайте новую ссылку. Область доступа, состояние аккаунта и ящика проверяются повторно. Пользовательские сессии не могут выпускать ссылки.
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}Ключ партнёра
Используйте почтовый API-ключ вашей интеграции. Передавайте его в X-API-Key, а ID почтового аккаунта — в обязательном заголовке X-Customer-ID. Это ID аккаунта, а не external_id и не ID ящика. Ключ открывает доступ только к клиентам вашей интеграции.
Храните ключ на сервере партнёра. Не помещайте общий ключ интеграции в браузер или мобильное приложение.
curl 'https://adapt-mail.com/v1/mailboxes' \ -H 'X-API-Key: <mail-api-key>' \ -H 'X-Customer-ID: <mail-account-id>'Токен пользователя
POST /v1/auth/token принимает login, password и mode. Для mode=account используется логин user-ID, для mode=mailbox — полный адрес ящика. Пароли аккаунта и ящика независимы.
Ответ содержит access_token, token_type=Bearer и expires_in=3600. Токен аккаунта открывает его ящики; токен ящика — только один ящик. После истечения получите новый токен.
POST /v1/auth/tokenContent-Type: application/json
{"login":"user-123","password":"<password>","mode":"account"}
GET /v1/mailboxesAuthorization: Bearer <access_token>Браузерные сессии
POST /v1/auth/login предназначен для собственного сайта adapt-mail.com. Он требует правильный Origin и устанавливает HttpOnly cookies. Несекретный X-Mail-Session выбирает один из сохранённых входов, но без cookie не даёт доступа.
Для стороннего фронтенда используйте свой сервер и токен пользователя. Не рассчитывайте на произвольный междоменный доступ с cookie: публичного CORS для любого сайта нет.