Интеграция почты

Авторизация и владельцы

Базовый URL: https://cloud-api.adaptgroup.pro. Каждый запрос использует ключ Cloud-интеграции в X-Api-Key и её числовой api_key_id: в query для GET/DELETE, в JSON для остальных методов. Для JSON передавайте Content-Type: application/json.

Аккаунт представляет вашего клиента. api_user_id — ваш постоянный идентификатор клиента длиной до 255 символов. Аккаунту принадлежат домены и ящики. account_id, domain_id, mailbox_id и key_id обозначают ресурсы; operation_id — UUID. Ресурсы должны принадлежать авторизованной интеграции.

Ключ Cloud-интеграции управляет услугами и оплатой. Почтовые API-ключи позволяют приложению работать с письмами, папками и вложениями через почтовое API. Это ключи интеграции: используйте их на своём бекенде, а не выдавайте отдельным клиентам. Для входа на adapt-mail.com нужны логин и пароль аккаунта. Пароль аккаунта и пароли отдельных ящиков — разные реквизиты.

Вход без пароля

Вызовите POST /mail/accounts/{account_id}/login-link со своего бекенда с api_key_id и необязательным locale (по умолчанию en). Без mailbox_id или с null откроется аккаунт; с ID — только этот ящик. Языки: en, ru, fr, es, de, zh-cn, ko, tr, hi, pt-br.

HTTP 201 возвращает data.login_url, expires_in: 300, expires_at, account_id и mailbox_id. Откройте URL целиком, сохранив #token=.... Ссылка одноразовая и действует пять минут; не записывайте её в логи и кеш. Перед выдачей ссылки проверьте, что авторизованный клиент владеет запрошенным аккаунтом или ящиком. Ключ Cloud API остаётся на бекенде.

Для новой вкладки создайте пустую вкладку сразу при нажатии, а после ответа направьте её на login_url. Пароли и сохранённые входы в браузере не меняются. При входе доступ проверяется повторно. Для использованной или истёкшей ссылки получите новую. Почтовый интерфейс сам обменивает токен на сессию.

Создать аккаунт и подключить домен

1. Вызовите POST /mail/accounts с api_user_id и name. Создание бесплатно. Сохраните полученные login и password: последующие чтения не возвращают пароль. Повтор создания с теми же ID клиента и именем вернёт существующий аккаунт. Чтобы получить новый пароль, используйте сброс.
2. Вызовите POST /mail/accounts/{account_id}/domains с name: "example.com". Передавайте только доменное имя без протокола и пути. Ящики создаются на вашем подключённом домене; adapt-mail.com — интерфейс почты, а не предоставляемый домен для адресов клиентов.
3. Получите DNS-записи и добавьте их у своего DNS-провайдера.
4. Вызовите verify. Он проверяет TXT владения и активирует домен. В ответе появится созданный TXT DKIM: его тоже нужно добавить.
5. Получите DNS повторно. Когда status="active" и у всех записей matches=true, настройка DNS завершена. Можно переходить к покупке ящика.

GET /mail/domains показывает все собственные домены без выбора клиента. GET /mail/accounts/{account_id}/domains показывает домены, доступные одному аккаунту.

Как читать DNS-записи

Поле	Значение
type	Тип DNS-записи, например TXT или MX.
name	Полное имя записи. Если провайдер сам добавляет домен, вводите только относительное имя; для корня используйте @, если это требуется провайдером.
value	Ожидаемое содержимое. Копируйте полностью, включая длинный публичный ключ DKIM.
observed	Значения, найденные при проверке.
matches	Совпадает ли найденное значение с ожидаемым.
error	dns_unavailable, если эту запись не удалось проверить.

Запись	Имя для example.com	Значение / назначение
TXT владения	_adapt-mail.example.com	Точное подтверждающее значение из API.
MX	example.com	Для 10 mx1.adapt-mail.com задайте приоритет: 10 и почтовый сервер: mx1.adapt-mail.com в отдельных полях провайдера.
TXT SPF	example.com	Полное значение SPF из API.
TXT DMARC	_dmarc.example.com	Полное значение DMARC из API.
TXT DKIM	dkim._domainkey.example.com	Полное созданное значение DKIM, полученное после подтверждения.

status=active подтверждает активацию домена, но не совпадение MX, SPF, DMARC и DKIM. Для этого проверяйте records[].matches. Если записи не совпали, сверьте имя и значение и дождитесь распространения DNS перед повторной проверкой.

Сохраняйте записи из API, пока используете домен для почты. MX направляет входящие письма; SPF, DKIM и DMARC участвуют в проверке отправителя. TXT владения используется при повторном подтверждении домена. Удалять их после настройки не нужно.

Покупка и оплата

Получите GET /mail/plans, выберите активный code и используйте его monthly_price_usd. Это конечные цены в USD; наценка интеграции не добавляется. storage_shared=true означает, что письма, вложения и файлы используют общую квоту. mail_quota_mb и file_quota_mb равны и описывают один объём в МиБ; складывать их нельзя. Отдельного расчёта покупки нет.

curl 'https://cloud-api.adaptgroup.pro/mail/mailboxes' \
  -H 'X-Api-Key: YOUR_CLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: mail-customer-42-order-001' \
  --data '{
    "api_key_id": 1,
    "account_id": 12,
    "domain_id": 8,
    "local_part": "team",
    "name": "Team",
    "password": "ExamplePassword42!",
    "plan_code": "mail-10",
    "auto_renew": false,
    "expected_amount_usd": "1.0000"
  }'

Пример создаёт [email protected]. Замените ID, домен, пароль и цену своими значениями. api_user_id берётся из выбранного аккаунта и не передаётся отдельным полем покупки.

Покупка, продление, увеличение объёма и удаление возвращают HTTP 202 с заказом. Проверяйте GET /orders/{order_id} до получения результата. Завершённая покупка содержит mailbox_id, mail_operation_id и paid_until. После этого получите детали ящика. Принятие запроса не означает готовность ящика. Оплаченный срок начинается после успешного создания и составляет один календарный месяц.

Списание с баланса интеграции происходит при принятии заказа. Если средств недостаточно, возвращается 409 insufficient_balance, кроме интеграций с разрешённым отрицательным балансом. Подтверждённая неуспешная покупка возвращает оплату после очистки; проверяйте статус заказа и error_code. review означает, что результат ещё требует разрешения; не создавайте новый оплаченный заказ только ради повтора.

Idempotency-Key обязателен для покупки, продления, увеличения объёма, удаления и изменения настроек ящика. Допустимы 8–128 печатных ASCII-символов без пробелов. Используйте один ключ на команду. После таймаута повторяйте тот же запрос с тем же ключом. Ключ заказа с другими параметрами возвращает 409 idempotency_conflict.

expected_amount_usd необязателен и содержит четыре знака после точки. При покупке и продлении он сравнивается с точной суммой. Для увеличения объёма задаёт максимально допустимую доплату: расчёт может уменьшаться с течением времени. Изменившаяся или превышенная цена возвращает 409 price_changed без списания.

Общее хранилище

Базовый тариф предоставляет 10 ГиБ всего для почты и файлов. Увеличение хранилища повышает единую квоту; файлы не являются отдельной платной услугой.

Детали и списки ящиков возвращают storage_shared=true. Общий расход отображайте как used_bytes / (quota_mb × 1048576). used_bytes уже включает файлы, MIME-кодирование и заголовки. file_quota_bytes равен quota_mb × 1048576; file_used_bytes — исходный размер отдельных файлов без MIME-кодирования, аналитический показатель, а не дополнительный расход. Не прибавляйте файловые поля к соответствующим общим значениям.

Продление, увеличение объёма и удаление

• Продление: расчёт, затем продление. Каждый запрос покупает календарный месяц по актуальной цене тарифа, начиная с более поздней даты: конца оплаты или текущего времени. Календарный месяц сохраняет время UTC и использует последний доступный день в более коротком месяце.
• Увеличение объёма: расчёт, затем увеличение. Можно выбрать только больший тариф. Доплата учитывает остаток каждого оплаченного календарного месяца, включая оплаченные заранее. Конец оплаты не меняется. Расчёт не резервирует деньги и не создаёт заказ.
• Автопродление: по умолчанию выключено; задаётся при покупке или через auto-renew. Сервис пытается продлить ящик на месяц с баланса интеграции за час до конца оплаты и, если он не продлён, за час до удаления.
• Окончание оплаты: доступ приостанавливается. Продление возможно в течение 24 часов после окончания оплаты, пока не началось удаление. delete_after содержит срок удаления. После начала удаления продление недоступно.
• Ручное удаление: DELETE /mail/mailboxes/{mailbox_id} создаёт заказ с нулевой ценой и удаляет ящик, письма и файлы. Неиспользованный срок не возвращается.

Оплаты почты отображаются в транзакциях как mail_purchase, mail_renewal и mail_upgrade; возврат — refund. В заказах также есть mail_delete. mailbox_id связывает заказ с ящиком, а mail_operation_id — с почтовой операцией. Для завершённых почтовых заказов paid_until возвращается, если у операции есть подтверждённый срок.

Настройки и операции

PATCH настроек ящика меняет отображаемое имя, пароль ящика или подпись. Пропущенные поля и null не меняют значения; пустая подпись очищает её. HTTP 200 возвращает операцию в очереди. Проверяйте операцию по UUID и ID аккаунта; succeeded подтверждает завершение.

Настройка доступа блокирует или включает ящик без приостановки оплаченного срока. Продление не снимает ручную блокировку. Смена аккаунта переносит ящик внутри интеграции с сохранением адреса, пароля, данных и оплаченного срока, обновляя api_user_id.

Статусы операции: queued, running, succeeded, failed, uncertain и cancelled. uncertain означает неподтверждённый результат. error — публичный код ошибки или null; result содержит публичные поля результата, когда они доступны. Повтор доступен для допустимых неуспешных настроек и оплаченного увеличения объёма в review, без нового списания. Отправку письма через этот маршрут повторить нельзя.

Лимиты отправки и расход

Список ящиков и детали содержат лимиты и расход в одном ответе:

Поля лимита и расхода	Период
outbound_daily_recipient_limit, outbound_daily_recipients_used, outbound_daily_recipients_remaining	Получатели за последние 24 часа.
outbound_messages_per_minute, outbound_minute_messages_used, outbound_minute_messages_remaining	Сообщения за последние 60 секунд.
outbound_recipients_per_message	Сумма получателей в To/Cc/Bcc одного письма.

Суточный лимит — 1000 получателей или 5000 при outbound_high_limit=true. Остальные лимиты: 30 сообщений в минуту и 50 получателей одного письма. Они не зависят от размера хранилища. SMTP и API используют общие счётчики. remaining не бывает меньше нуля. Расход отражает допущенные попытки отправки, а не подтверждённую доставку; принятая операция может завершиться ошибкой при отправке. Если расход недоступен, возвращается 503, а не выдуманные нули.

Ответ изменения автопродления тоже содержит текущий расход. Ответы изменения доступа и владельца содержат лимиты без счётчиков расхода; актуальный расход получите в деталях ящика.

Почтовые API-ключи

Создайте именованный ключ, получайте список без секретов и просматривайте активный ключ при необходимости. Создание и просмотр возвращают key; ответы с секретами не кешируются. Для удаления сначала отзовите ключ, затем вызовите тот же DELETE с permanent=true. Активный ключ окончательно удалить нельзя.

Ошибки и вебхуки

HTTP 401 означает неверный ключ/ID или неактивную интеграцию; 403 — запрет доступа; 404 — ресурс недоступен этой интеграции; 422 — неверные поля или параметры. Структурированная ошибка содержит detail.code и detail.message; некоторые ошибки проверки и состояния используют другие формы detail, поэтому обрабатывайте также HTTP-статус.

Код	Действие
insufficient_balance	Пополнить баланс или использовать разрешённый интеграции отрицательный баланс.
price_changed	Получить актуальный каталог или расчёт и подтвердить сумму.
idempotency_conflict	Для повтора передать исходные параметры; для другой команды — новый ключ.
mail_busy, mail_domain_busy	Дождаться текущей операции и повторить.
mail_conflict	Получить актуальное состояние ресурса перед изменением.
mail_plan_unavailable	Выбрать активный тариф из каталога.
mail_request_rejected	Исправить параметры запроса.
mail_access_denied, mail_not_found	Проверить владельца, ID и доступ.
mail_domain_shared	Общий домен удалить нельзя.
mail_domain_has_mailboxes	Удалить ящики домена и дождаться завершения.
mail_domain_deleting, mail_domain_delete_failed	Повторить удаление для подтверждения результата.
mail_key_active	Отозвать ключ перед окончательным удалением.
mail_key_not_recoverable	Создать новый ключ.
mail_unavailable	Повторить чтение, когда сервис доступен.
mail_operation_unconfirmed	Проверить исходную операцию или ресурс; не считать команду неуспешной без подтверждения.

Ошибки заказа mail_rejected и mail_creation_failed означают отклонённый или неуспешный заказ с возвращённой оплатой; mail_unconfirmed требует проверки исходной операции. Ошибки отправки и все события жизненного цикла ящика описаны в вебхуках. Пароли, API-ключи и тело письма в партнёрские вебхуки не включаются.