API-документация

Базовый URL для всех запросов:

https://api.smakmail.com/api/v1

Точная схема запросов и ответов доступна в OpenAPI. Для начала можно проверить токен через GET /me.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  https://api.smakmail.com/api/v1/me

Защищённые методы используют Bearer token. Методы чтения конкретной почты и её писем дополнительно требуют текущий пароль этой почты.

Authorization: Bearer <API_TOKEN>
X-Mailbox-Password: <MAILBOX_PASSWORD>

Не передавайте API token или пароль почты в query string. Доступ к заказам, почтам и письмам ограничен данными текущего пользователя.

• Стандартный API: 10 запросов/с, burst 20.
• Developer: 50 запросов/с, burst 250.
• Developer: 5 000 000 запросов в сутки.
• Developer: 100 000 000 запросов за 30 дней.
• Developer: 199 ₽ за 30 дней. Personal API low-qty 1–99: 0,08 ₽/шт с Developer и 0,80 ₽/шт без него. Для других поддерживаемых товаров API-заказ 1 шт с Developer использует цену за 1 шт уровня пакета 1000. Одноразовый пробный период: 72 часа без автоматического списания.

При превышении скоростного лимита API возвращает HTTP 429 rate_limited. При исчерпании Developer quota возвращается HTTP 429 quota_exceeded. Текущие лимиты также возвращаются в GET /developer.

GET  /api/v1/me
GET  /api/v1/balance
GET  /api/v1/products

GET  /api/v1/developer
POST /api/v1/developer/trial
POST /api/v1/developer/subscribe

GET  /api/v1/shop/domain-options

POST /api/v1/orders/quote
POST /api/v1/orders
GET  /api/v1/orders/{order_id}
GET  /api/v1/orders/{order_id}/result

GET  /api/v1/mailbox
GET  /api/v1/mailbox/messages
GET  /api/v1/mailbox/latest-code
POST /api/v1/mailbox/password/change

GET  /api/v1/messages/{msg_id}
GET  /api/v1/messages/{msg_id}/extract
GET  /api/v1/messages/{msg_id}/html

GET    /api/v1/webhooks
POST   /api/v1/webhooks
GET    /api/v1/webhooks/{webhook_id}
DELETE /api/v1/webhooks/{webhook_id}
GET    /api/v1/webhooks/{webhook_id}/deliveries
GET    /api/v1/webhooks/{webhook_id}/mailboxes
POST   /api/v1/webhooks/{webhook_id}/mailboxes
DELETE /api/v1/webhooks/{webhook_id}/mailboxes/{email}
POST   /api/v1/webhooks/{webhook_id}/test

OpenAPI является канонической схемой параметров и ответов для этих методов.

Перед заказом получите актуальный каталог через GET /products. Для low-qty 1–99 сначала вызовите POST /orders/quote: он не создаёт заказ и не списывает баланс, а возвращает цену за единицу, итоговую цену и сравнение с Developer. POST /orders создаёт заказ и сразу списывает баланс, если заказ проходит. Для POST /orders требуется уникальный Idempotency-Key. Personal API low-qty 1–99 стоит 0,80 ₽/шт без Developer и 0,08 ₽/шт с Developer. Для других поддерживаемых товаров API-заказ 1 шт с Developer использует цену за 1 шт уровня пакета 1000. Для Personal передаётся поле domain. Для товаров из общего пула можно использовать domain_selection с mode only или exclude.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"product":"Eternal","qty":1}' \
  https://api.smakmail.com/api/v1/orders/quote

POST /orders/quote является только расчётом: он не создаёт заказ, не списывает баланс и не требует Idempotency-Key. После проверки цены отправьте отдельный POST /orders только если хотите совершить покупку.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-001" \
  -d '{"product":"Eternal","qty":100}' \
  https://api.smakmail.com/api/v1/orders

Статус заказа: GET /orders/{order_id}. Результат завершённого заказа: GET /orders/{order_id}/result.

Для чтения почты, списка писем, карточки письма, HTML, extract и latest-code нужен X-Mailbox-Password с текущим паролем конкретной почты.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \
  --get \
  --data-urlencode "email=mailbox@example.com" \
  https://api.smakmail.com/api/v1/mailbox/latest-code

GET /mailbox/latest-code подходит для автоматизаций, которым нужен только последний найденный код. GET /messages/{msg_id}/extract возвращает извлечённые коды и ссылки.

API поддерживает webhook endpoints и привязку конкретных почт. Пароли почт используются только для проверки доступа при создании привязки и не сохраняются.

GET    /api/v1/webhooks
POST   /api/v1/webhooks
GET    /api/v1/webhooks/{webhook_id}
DELETE /api/v1/webhooks/{webhook_id}
GET    /api/v1/webhooks/{webhook_id}/deliveries
GET    /api/v1/webhooks/{webhook_id}/mailboxes
POST   /api/v1/webhooks/{webhook_id}/mailboxes
DELETE /api/v1/webhooks/{webhook_id}/mailboxes/{email}
POST   /api/v1/webhooks/{webhook_id}/test

bad_request
invalid_token
forbidden
not_found
conflict
validation_error
rate_limited
quota_exceeded
mailbox_password_required
invalid_mailbox_password
internal_error

Ошибки возвращаются в JSON с ok=false, error.code, error.message и request_id.

• OpenAPI
• IMAP
• POP3
• Статус сервиса
• Правила использования и условия сервиса