Обновлено: 13 августа 2026

1. Назначение API

SmakMail API v1 это product API для работы с почтами, письмами, кодами, ссылками, заказами и PJ.

API предназначен для:

• получения информации о токене и текущем пользователе
• получения текущего баланса
• получения каталога товаров
• создания заказа на почты
• получения статуса заказа
• получения результата завершённого заказа
• получения информации о конкретной почте по email
• получения списка писем конкретной почты
• получения карточки письма
• получения HTML письма
• получения извлечённых кодов и ссылок из письма
• получения последнего кода по конкретной почте
• смены PJ конкретной почты

API v1 не является panel API.

API v1 не даёт административные функции.

API v1 не даёт отправку писем от пользовательских почт.

API v1 не раскрывает внутренние filesystem paths и внутренние служебные идентификаторы доменов.

2. Базовая информация

Версия API:

v1

Базовый URL:

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

Локальный базовый путь сервиса:

/api/v1

Служебные endpoints:

GET /api/v1/openapi.json
GET /api/v1/docs
GET /api/v1/healthz

3. Доступ к API

Доступ к API осуществляется через Bearer token.

Токен:

• создаётся через Telegram-бота
• перевыпускается через Telegram-бота
• отзывается через Telegram-бота
• активен в одном экземпляре на пользователя

Через HTTP API не поддерживаются:

• регистрация
• логин по паролю
• создание токена по логину и паролю
• OAuth
• multi-token management

4. Авторизация

Во все защищённые запросы передаётся заголовок:

Authorization: Bearer <API_TOKEN>

Пример:

Authorization: Bearer smakmail_api_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Не передавайте API token в URL.

Не публикуйте API token в чатах, логах и скриншотах.

5. Доступ к почтам и письмам

Для чтения конкретной почты, писем, HTML, extract и latest-code теперь требуется два фактора доступа:

1. API token пользователя
2. текущий PJ конкретной почты

PJ передаётся только через HTTP header:

X-Mailbox-Password: <MAILBOX_PASSWORD>

Не передавайте PJ в query string.

Плохо:

GET /api/v1/mailbox/latest-code?email=mailbox@example.com&password=123

Правильно:

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

Эти endpoints требуют X-Mailbox-Password:

GET /api/v1/mailbox
GET /api/v1/mailbox/messages
GET /api/v1/mailbox/latest-code
GET /api/v1/messages/{msg_id}
GET /api/v1/messages/{msg_id}/extract
GET /api/v1/messages/{msg_id}/html

Эти endpoints не требуют X-Mailbox-Password:

GET /api/v1/me
GET /api/v1/balance
GET /api/v1/products
GET /api/v1/shop/domain-options
POST /api/v1/orders
GET /api/v1/orders/{order_id}
GET /api/v1/orders/{order_id}/result
POST /api/v1/mailbox/password/change

POST /api/v1/mailbox/password/change принимает текущий PJ в JSON-поле old_password.

Если X-Mailbox-Password не передан, API возвращает:

{
  "ok": false,
  "error": {
    "code": "mailbox_password_required",
    "message": "Mailbox password is required"
  },
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Если PJ неверный, API возвращает:

{
  "ok": false,
  "error": {
    "code": "invalid_mailbox_password",
    "message": "Mailbox password is invalid"
  },
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

6. Лимиты и безопасность

Лимит запросов

Для API действует лимит:

Стандартный API: 10 запросов/с, burst 20. Developer: 50 запросов/с, burst 250, 5 000 000 запросов/сутки, 100 000 000 запросов за 30 дней.

При превышении лимита сервис возвращает:

429 rate_limited

Модель доступа

API работает в owner-only режиме.

Это означает:

• пользователь видит только свои заказы
• пользователь видит только свои почты
• пользователь видит только свои письма
• пользователь может менять PJ только у своей почты
• пользователь может получать коды только из своих писем
• для чтения почты нужен текущий PJ этой почты

Чужой email, msg_id или order_id возвращает ошибку forbidden.

Защита после передачи почты другому владельцу

Если пользователь купил почту, передал её другому человеку, а новый владелец сменил PJ, старый владелец не сможет читать письма и коды через API без нового PJ.

API token сам по себе больше не даёт доступ к письмам и кодам.

Внутренние данные не раскрываются

API не возвращает:

• filesystem paths
• внутренние пути к HTML-файлам
• внутренние пути к result-файлам заказа
• user_domain_id
• mailauth_domain_id
• внутренние id доменов

7. Формат ответа

Успешный ответ

{
  "ok": true
}

Ответ с ошибкой

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "message is not available for current user"
  },
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Основные коды ошибок

bad_request
invalid_token
forbidden
not_found
conflict
validation_error
rate_limited
quota_exceeded
mailbox_password_required
invalid_mailbox_password
internal_error

8. Методы API

8.1 Проверка токена

GET /api/v1/me

Возвращает информацию о текущем токене и пользователе.

X-Mailbox-Password не требуется.

Пример ответа:

{
  "ok": true,
  "user_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "scope": "mail.read order.create pj.change",
  "token_created_at": "2026-05-02T19:44:04.381444+03:00",
  "token_last_used_at": "2026-05-02T19:44:05.719220+03:00"
}

8.2 Баланс

GET /api/v1/balance

Возвращает текущий баланс пользователя.

X-Mailbox-Password не требуется.

Пример ответа:

{
  "ok": true,
  "balance_kopeks": 7975,
  "balance_rub": "79.75"
}

8.3 Каталог товаров

GET /api/v1/products

Возвращает текущий каталог доступных товаров.

X-Mailbox-Password не требуется.

Актуальные цены, остатки и минимальные количества нужно получать из ответа API.

Пример ответа:

{
  "ok": true,
  "items": [
    {
      "product": "Eternal",
      "title": "Eternal",
      "available": true
    },
    {
      "product": "Limited_ru",
      "title": "Limited .ru",
      "available": true
    },
    {
      "product": "Limited_com",
      "title": "Limited .com",
      "available": true
    },
    {
      "product": "Privileged",
      "title": "Privileged",
      "available": true
    },
    {
      "product": "Ultimate",
      "title": "Ultimate",
      "available": true
    },
    {
      "product": "Personal",
      "title": "Personal",
      "available": true,
      "requires_personal_domain": true
    }
  ]
}

Поддерживаемые товары:

Eternal
Limited_ru
Limited_com
Privileged
Ultimate
Personal

8.4 Создание заказа

POST /api/v1/orders

Создаёт заказ на выдачу почт.

X-Mailbox-Password не требуется.

Обязательные заголовки:

Authorization: Bearer <API_TOKEN>
Content-Type: application/json
Idempotency-Key: <UNIQUE_KEY>

Idempotency-Key обязателен.

Заказ обычного товара

{
  "product": "Eternal",
  "qty": 100
}

Заказ Personal

Для Personal нужно передать полный домен пользователя.

{
  "product": "Personal",
  "qty": 100,
  "domain": "example.com"
}

Правила:

• product обязателен
• qty обязателен
• для Personal поле domain обязательно
• для остальных товаров поле domain запрещено
• пользователь не передаёт user_domain_id
• пользователь не передаёт mailauth_domain_id
• сервер сам резолвит домен пользователя внутри owner-safe контура

Пример успешного ответа:

{
  "ok": true,
  "order_id": "e43e7413-ba40-4934-ae8d-a4e0aec15144",
  "status": "awaiting_backend",
  "issuance_request_id": 689
}

8.5 Заказы: выбор доменов и статус

Выбор и исключение доменов при покупке

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

GET /api/v1/shop/domain-options?product=Eternal&quantity=100
Authorization: Bearer <API_TOKEN>

{
  "ok": true,
  "product": "Eternal",
  "quantity": 100,
  "service": null,
  "service_filter_applied": false,
  "domains": [
    {
      "domain_id": 685,
      "domain": "ochkomail.com",
      "fqdn": "ochkomail.com",
      "available": 9998843
    }
  ],
  "total_available": 59861181
}

Параметр service можно передавать для будущей совместимости, но сейчас сервисная фильтрация не применяется. В ответе это явно указано как service_filter_applied=false.

Режим only

mode=only означает: создать почты только на указанных доменах. Если ёмкости выбранных доменов не хватает, заказ не создаётся и деньги не списываются.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: api-domain-only-1" \
  -d '{"product":"Eternal","qty":100,"domain_selection":{"mode":"only","domains":["ochkomail.com"]}}' \
  https://api.smakmail.com/api/v1/orders

Режим exclude

mode=exclude означает: не использовать указанные домены. Это основной режим для случая, когда сервис заблокировал один из доменов.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: api-domain-exclude-1" \
  -d '{"product":"Eternal","qty":100,"domain_selection":{"mode":"exclude","domains":["ochkomail.com"]}}' \
  https://api.smakmail.com/api/v1/orders

Ошибки domain_selection

invalid_domain_selection
domain_not_found
domain_not_available
domain_product_mismatch
insufficient_capacity_selected_domains

Для Personal по-прежнему используется поле domain. Поле domain_selection предназначено для продуктов из общего пула доменов: Eternal, Limited_ru, Limited_com, Ultimate и других публично доступных пулов.

GET /api/v1/orders/{order_id}

Возвращает статус конкретного заказа пользователя.

X-Mailbox-Password не требуется.

order_id это UUID.

Пример ответа:

{
  "ok": true,
  "order": {
    "order_id": "e43e7413-ba40-4934-ae8d-a4e0aec15144",
    "product": "Eternal",
    "qty": 100,
    "unit_price_kopeks": 20,
    "total_kopeks": 2000,
    "status": "done",
    "created_at": "2026-03-26T06:55:58.366986+00:00",
    "updated_at": "2026-03-26T07:34:59.484063+00:00",
    "issuance_request_id": 689,
    "last_error": null,
    "status_obj": {
      "status": "done",
      "progress_done": 100,
      "progress_total": 100,
      "progress_phase": "done",
      "created_count": 100,
      "total_boxes": 100
    }
  }
}

8.6 Результат заказа

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

Возвращает результат завершённого заказа.

X-Mailbox-Password не требуется.

API возвращает JSON со списком email и password.

Внутренние filesystem paths наружу не раскрываются.

Пример ответа:

{
  "ok": true,
  "order_id": "e43e7413-ba40-4934-ae8d-a4e0aec15144",
  "items": [
    {
      "email": "mailbox1@example.com",
      "password": "ExamplePass123!"
    },
    {
      "email": "mailbox2@example.com",
      "password": "ExamplePass456!"
    }
  ]
}

Важно: если почта передаётся другому владельцу, новому владельцу нужно сменить PJ. После смены PJ старый владелец не сможет читать письма и коды без нового PJ.

8.7 Карточка почты по email

GET /api/v1/mailbox?email=<EMAIL>

Возвращает информацию о конкретной почте текущего пользователя.

Требует текущий PJ почты через header:

X-Mailbox-Password: <MAILBOX_PASSWORD>

Параметры:

ПараметрГдеОбязателенОписаниеemailqueryдаПолный email почтыX-Mailbox-PasswordheaderдаТекущий PJ этой почтыПример ответа:

{
  "ok": true,
  "mailbox": {
    "email": "mailbox@example.com",
    "notify_enabled": true,
    "updated_at": "2026-03-26T07:18:59.420928+00:00"
  }
}

8.8 Список писем конкретной почты

GET /api/v1/mailbox/messages?email=<EMAIL>&limit=<N>&cursor=<CURSOR>

Возвращает список писем конкретной почты.

Требует текущий PJ почты через header:

X-Mailbox-Password: <MAILBOX_PASSWORD>

Параметры:

ПараметрГдеОбязателенОписаниеemailqueryдаПолный email почтыlimitqueryнетКоличество писем. По умолчанию 50, максимум 100cursorqueryнетКурсор следующей страницыX-Mailbox-PasswordheaderдаТекущий PJ этой почтыПример ответа:

{
  "ok": true,
  "items": [
    {
      "msg_id": "m63264u1",
      "from_addr": "noreply@example.com",
      "subject": "Example subject",
      "snippet_600": "Example text",
      "preview_text": "Example text",
      "flags": [
        "\\Seen"
      ],
      "date": "2026-03-26T07:58:00+00:00",
      "arrived_at": "2026-03-26T07:58:02+00:00",
      "has_html": true
    }
  ],
  "next_cursor": null
}

msg_id из этого ответа нужно использовать для получения карточки письма, HTML, кодов и ссылок.

8.9 Карточка письма

GET /api/v1/messages/{msg_id}

Возвращает карточку одного письма.

Требует текущий PJ той почты, которой принадлежит письмо:

X-Mailbox-Password: <MAILBOX_PASSWORD>

msg_id это строковый идентификатор письма, полученный из GET /api/v1/mailbox/messages.

Ответ включает объект extract.

API гарантирует extract-on-read:

• если коды и ссылки уже извлечены, API отдаёт готовый результат
• если extract ещё не готов, API синхронно запускает извлечение при чтении письма
• результат сохраняется в msg_extract
• клиент получает готовый объект extract

Параметры:

ПараметрГдеОбязателенОписаниеmsg_idpathдаID письмаX-Mailbox-PasswordheaderдаТекущий PJ почты, которой принадлежит письмоПример ответа:

{
  "ok": true,
  "message": {
    "msg_id": "m63264u1",
    "email": "mailbox@example.com",
    "from_addr": "noreply@example.com",
    "subject": "Your verification code",
    "snippet_600": "Your verification code is 142008",
    "preview_text": "Your verification code is 142008",
    "flags": [
      "\\Recent",
      "\\Seen"
    ],
    "date": "2026-05-02T13:23:26+03:00",
    "arrived_at": "2026-05-02T16:23:29+03:00",
    "has_html": true,
    "extract": {
      "status": "ready",
      "db_status": "ok",
      "service": "genshinimpact",
      "kind": "code",
      "summary": "",
      "preview_text": "Код: 142008",
      "codes": [
        {
          "value": "142008",
          "label": "Код",
          "score": 1.2
        }
      ],
      "links": [],
      "confidence": 1.2,
      "model_name": null,
      "model_version": null,
      "extracted_at": "2026-05-02T13:25:06.835495+03:00",
      "updated_at": "2026-05-02T18:33:23.507370+03:00"
    }
  }
}

8.10 Extract письма

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

Возвращает только извлечённые коды и ссылки из письма.

Требует текущий PJ той почты, которой принадлежит письмо:

X-Mailbox-Password: <MAILBOX_PASSWORD>

Этот endpoint удобен, когда клиенту не нужна карточка письма целиком.

API также гарантирует extract-on-read.

Параметры:

ПараметрГдеОбязателенОписаниеmsg_idpathдаID письмаX-Mailbox-PasswordheaderдаТекущий PJ почты, которой принадлежит письмоПример ответа с кодом:

{
  "ok": true,
  "extract": {
    "status": "ready",
    "db_status": "ok",
    "service": "genshinimpact",
    "kind": "code",
    "summary": "",
    "preview_text": "Код: 142008",
    "codes": [
      {
        "value": "142008",
        "label": "Код",
        "score": 1.2
      }
    ],
    "links": [],
    "confidence": 1.2,
    "model_name": null,
    "model_version": null,
    "extracted_at": "2026-05-02T13:25:06.835495+03:00",
    "updated_at": "2026-05-02T18:33:23.507370+03:00"
  }
}

Пример ответа без найденного кода:

{
  "ok": true,
  "extract": {
    "status": "no_code_found",
    "db_status": "ok",
    "service": null,
    "kind": "other",
    "summary": "",
    "preview_text": "Example message",
    "codes": [],
    "links": [],
    "confidence": null,
    "model_name": null,
    "model_version": null,
    "extracted_at": "2026-05-02T13:25:06.835495+03:00",
    "updated_at": "2026-05-02T13:25:06.835495+03:00"
  }
}

Поля extract

ПолеТипОписаниеstatusstringПубличный статус extract. Обычно ready или no_code_founddb_statusstringВнутренний статус строки extract. Обычно okservicestring или nullОпределённый сервис, если распознанkindstringТип результата. Например code, link, code_link, othersummarystring или nullКраткое описаниеpreview_textstringКраткий текст результатаcodesarrayНайденные кодыlinksarrayНайденные ссылкиconfidencenumber или nullОценка уверенностиmodel_namestring или nullИмя модели, если применимоmodel_versionstring или nullВерсия модели, если применимоextracted_atstring или nullВремя извлеченияupdated_atstring или nullВремя обновления extractПоля codes

ПолеТипОписаниеvaluestringЗначение кодаlabelstringЧеловекочитаемая меткаscorenumberОценка релевантности, если естьkindstringТип кода, если естьconfidencenumberУверенность, если естьПоля links

ПолеТипОписаниеurlstringURLlabelstringТекст ссылкиkindstringТип ссылки, если распознанscorenumberОценка релевантности, если естьconfidencenumberУверенность, если есть8.11 Последний код по почте

GET /api/v1/mailbox/latest-code?email=<EMAIL>

Возвращает последний найденный код по конкретной почте.

Это самый удобный endpoint для автоматизаций, которым нужен только код.

Требует текущий PJ почты через header:

X-Mailbox-Password: <MAILBOX_PASSWORD>

Параметры:

ПараметрГдеОбязателенОписаниеemailqueryдаПолный email почтыservicequeryнетФильтр по сервисуlimitqueryнетСколько последних писем проверить. По умолчанию 20, максимум 50X-Mailbox-PasswordheaderдаТекущий PJ этой почтыПример запроса:

GET /api/v1/mailbox/latest-code?email=mailbox@example.com

Пример ответа:

{
  "ok": true,
  "status": "ready",
  "email": "mailbox@example.com",
  "message_id": "m111208u8",
  "service": "genshinimpact",
  "kind": "code",
  "code": "142008",
  "codes": [
    "142008"
  ],
  "links": [],
  "arrived_at": "2026-05-02T16:23:29+03:00",
  "extracted_at": "2026-05-02T13:25:06.835495+03:00",
  "extract": {
    "status": "ready",
    "db_status": "ok",
    "service": "genshinimpact",
    "kind": "code",
    "summary": "",
    "preview_text": "Код: 142008",
    "codes": [
      {
        "value": "142008",
        "label": "Код",
        "score": 1.2
      }
    ],
    "links": [],
    "confidence": 1.2,
    "model_name": null,
    "model_version": null,
    "extracted_at": "2026-05-02T13:25:06.835495+03:00",
    "updated_at": "2026-05-02T18:33:23.507370+03:00"
  }
}

Пример с фильтром service:

GET /api/v1/mailbox/latest-code?email=mailbox@example.com&service=genshinimpact

Ответ, если писем нет:

{
  "ok": true,
  "status": "not_found",
  "email": "mailbox@example.com",
  "message_id": null,
  "code": null,
  "codes": [],
  "links": []
}

Ответ, если письма есть, но код не найден:

{
  "ok": true,
  "status": "no_code_found",
  "email": "mailbox@example.com",
  "message_id": null,
  "service": null,
  "code": null,
  "codes": [],
  "links": []
}

8.12 HTML письма

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

Возвращает HTML письма.

Требует текущий PJ той почты, которой принадлежит письмо:

X-Mailbox-Password: <MAILBOX_PASSWORD>

Если для письма есть HTML-версия, endpoint возвращает:

HTTP 200
Content-Type: text/html; charset=utf-8

Тело ответа содержит HTML документа письма.

Параметры:

ПараметрГдеОбязателенОписаниеmsg_idpathдаID письмаX-Mailbox-PasswordheaderдаТекущий PJ почты, которой принадлежит письмоПример запроса:

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \
  https://api.smakmail.com/api/v1/messages/m63264u1/html

8.13 Смена PJ

POST /api/v1/mailbox/password/change

Меняет PJ конкретной почты текущего пользователя.

Для этого endpoint X-Mailbox-Password не нужен. Текущий PJ передаётся в JSON-поле old_password.

Пример запроса:

{
  "email": "mailbox@example.com",
  "old_password": "OldPass123!",
  "new_password": "NewPass123!"
}

Пример успешного ответа:

{
  "ok": true,
  "status": "ok",
  "closed_sessions": 1
}

Что происходит при успешной смене PJ:

• проверяется принадлежность почты текущему пользователю
• проверяется старый пароль
• новый пароль валидируется по текущей политике PJ
• обновляется hash пароля
• закрываются старые сессии этой почты
• выполняется IMAP session kick
• в аудит пишется событие смены пароля

9. Owner-only модель доступа

Все mail-операции и order-операции работают только в owner-only режиме.

Это означает:

• чужой email недоступен
• чужой msg_id недоступен
• чужой order_id недоступен
• сменить PJ чужой почты нельзя
• получить результат чужого заказа нельзя
• получить код из чужого письма нельзя

При нарушении прав доступа возвращается ошибка:

forbidden

Для mail-read endpoints дополнительно требуется текущий PJ почты.

Если PJ отсутствует:

mailbox_password_required

Если PJ неверный:

invalid_mailbox_password

10. Идемпотентность заказов

Для POST /api/v1/orders обязателен заголовок:

Idempotency-Key: <UNIQUE_KEY>

Рекомендуется передавать уникальную строку для каждого нового заказа.

Повторный запрос с тем же Idempotency-Key должен рассматриваться как повтор того же действия, а не как создание нового заказа.

11. Extract-on-read

SmakMail API v1 гарантирует извлечение кодов и ссылок при чтении.

Это значит:

фоновый extractor = ускоритель
API extract-on-read = гарантия

Рабочая схема:

1. Письмо приходит на почту.
2. Письмо становится доступно через API.
3. Клиент запрашивает письмо, extract или latest-code.
4. API проверяет наличие готового extract.
5. Если extract уже есть, API отдаёт его сразу.
6. Если extract ещё нет, API синхронно извлекает код и ссылки.
7. API сохраняет результат.
8. Клиент получает готовый ответ.

Это убирает ситуацию, когда письмо уже доступно, но код ещё не извлечён.

12. Что не входит в API v1

В API v1 не входят:

• регистрация
• логин по паролю
• создание токена по логину и паролю
• multi-token management
• пополнение баланса
• refund
• cancel order
• admin endpoints
• общий GET /mailboxes
• webhook subscriptions
• signed links на HTML
• отправка писем от пользовательских почт
• раскрытие внутренних filesystem paths
• раскрытие внутренних идентификаторов доменов

13. Рекомендованный порядок работы клиента

Получение и использование API

1. Открыть в боте раздел IMAP | API.
2. Создать или перевыпустить токен.
3. Сохранить токен.
4. Проверить токен через GET /api/v1/me.

Работа с заказами

1. Получить баланс через GET /api/v1/balance.
2. Получить каталог через GET /api/v1/products.
3. Создать заказ через POST /api/v1/orders.
4. Проверять статус через GET /api/v1/orders/{order_id}.
5. После завершения получить результат через GET /api/v1/orders/{order_id}/result.

Работа с письмами

1. Иметь API token.
2. Иметь текущий PJ конкретной почты.
3. Получить карточку почты через GET /api/v1/mailbox.
4. Получить список писем через GET /api/v1/mailbox/messages.
5. Взять msg_id из списка писем.
6. Получить карточку письма через GET /api/v1/messages/{msg_id}.
7. Получить extract через GET /api/v1/messages/{msg_id}/extract.
8. При необходимости получить HTML через GET /api/v1/messages/{msg_id}/html.

Быстрое получение кода

Для большинства автоматизаций достаточно одного запроса:

GET /api/v1/mailbox/latest-code?email=<EMAIL>

Нужны заголовки:

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

Endpoint сразу возвращает последний найденный код по почте.

Смена PJ

1. Вызвать POST /api/v1/mailbox/password/change.
2. Передать текущий PJ в old_password.
3. Передать новый PJ в new_password.

14. Примечания по текущей версии

• API v1 работает с UUID-идентификаторами заказов.
• msg_id письма нужно брать из ответа GET /api/v1/mailbox/messages.
• GET /api/v1/messages/{msg_id} возвращает объект extract.
• GET /api/v1/messages/{msg_id}/extract возвращает только extract письма.
• GET /api/v1/mailbox/latest-code возвращает последний код по почте.
• Для чтения почты, писем, HTML, extract и latest-code нужен X-Mailbox-Password.
• Для Personal всегда передаётся полный домен строкой в поле domain.
• /api/v1/docs и /api/v1/openapi.json существуют как web-представление документации и OpenAPI-схемы.

15. Примеры curl

Проверка токена

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

Баланс

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

Каталог

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

Заказ обычного товара

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

Заказ Personal

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-personal-order-1" \
  -d '{"product":"Personal","qty":100,"domain":"example.com"}' \
  https://api.smakmail.com/api/v1/orders

Статус заказа

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  https://api.smakmail.com/api/v1/orders/e43e7413-ba40-4934-ae8d-a4e0aec15144

Результат заказа

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  https://api.smakmail.com/api/v1/orders/e43e7413-ba40-4934-ae8d-a4e0aec15144/result

Карточка почты

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

Список писем почты

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

Карточка письма с extract

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \
  https://api.smakmail.com/api/v1/messages/m63264u1

Extract письма

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \
  https://api.smakmail.com/api/v1/messages/m63264u1/extract

Последний код по почте

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

Последний код по почте с фильтром service

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

HTML письма

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \
  https://api.smakmail.com/api/v1/messages/m63264u1/html

Смена PJ

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email":"mailbox@example.com","old_password":"OldPass123!","new_password":"NewPass123!"}' \
  https://api.smakmail.com/api/v1/mailbox/password/change

16. Минимальный сценарий для получения кода

Запрос:

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

Ожидаемый успешный ответ:

{
  "ok": true,
  "status": "ready",
  "email": "mailbox@example.com",
  "message_id": "m111208u8",
  "service": "genshinimpact",
  "kind": "code",
  "code": "142008",
  "codes": [
    "142008"
  ],
  "links": [],
  "arrived_at": "2026-05-02T16:23:29+03:00",
  "extracted_at": "2026-05-02T13:25:06.835495+03:00"
}