Документация SmakMail API v1

Документация SmakMail API v1

Смак

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

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

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

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

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

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

API v1 не меняет receive-only архитектуру сервиса.

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

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

Версия API: v1

Базовый путь: /api/v1

Служебные endpoints:

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

3. Доступ к API

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

Токен:

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

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

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

Раздел API в боте

В главном меню раздел расположен так:

  • Купить почты
  • Почты | Пароли
  • Профиль
  • IMAP | ☁️ API
  • Добавить свой домен
  • Поддержка | О сервисе

В разделе ☁️ API доступны:

  • статус токена
  • Создать токен или Перевыпустить токен
  • Отозвать токен
  • Документация
  • Назад

Кнопка Документация в боте открывает страницу:

https://telegra.ph/Dokumentaciya-SmakMail-API-v1-03-26

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

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

Authorization: Bearer <API_TOKEN>

Пример:

Authorization: Bearer smakmail_api_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5. Ограничения и безопасность

Лимиты

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

  • 10 запросов в секунду на пользователя

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

  • 429 rate_limited

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

API работает только по модели owner-only.

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

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

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

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

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

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

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

{
  "ok": true
}

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

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "Mailbox does not belong to current user"
  },
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

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

  • bad_request
  • invalid_token
  • forbidden
  • not_found
  • conflict
  • validation_error
  • rate_limited
  • internal_error

7. Методы API

7.1 Проверка токена и информации о пользователе

GET /api/v1/me

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

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

{
  "ok": true,
  "user_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "scope": "mail.read order.create pj.change",
  "token_created_at": "2026-03-26T06:11:30+00:00",
  "token_last_used_at": "2026-03-26T06:17:40+00:00"
}

7.2 Баланс

GET /api/v1/balance

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

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

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

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

GET /api/v1/products

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

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

{
  "ok": true,
  "items": [
    {
      "product": "Eternal",
      "title": "Eternal",
      "unit_price_kopeks": 4,
      "available": true,
      "available_qty": 999999851,
      "min_qty": 100
    },
    {
      "product": "Limited_ru",
      "title": "Limited .ru",
      "unit_price_kopeks": 20,
      "available": true,
      "available_qty": 99985,
      "min_qty": 10
    },
    {
      "product": "Limited_com",
      "title": "Limited .com",
      "unit_price_kopeks": 25,
      "available": true,
      "available_qty": 29991,
      "min_qty": 10
    },
    {
      "product": "Premium",
      "title": "Premium",
      "unit_price_kopeks": 30,
      "available": true,
      "available_qty": 4992,
      "min_qty": 10
    },
    {
      "product": "Ultimate",
      "title": "Ultimate",
      "unit_price_kopeks": 100,
      "available": true,
      "available_qty": 1000,
      "min_qty": 10
    },
    {
      "product": "Personal",
      "title": "Personal",
      "unit_price_kopeks": 100,
      "available": true,
      "min_qty": 10,
      "requires_personal_domain": true
    }
  ]
}

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

  • Eternal
  • Limited_ru
  • Limited_com
  • Premium
  • Ultimate
  • Personal

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

POST /api/v1/orders

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

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

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": "upsoulmail.ru"
}

Правила

  • 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
}

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

GET /api/v1/orders/{order_id}

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

order_id это UUID.

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

GET /api/v1/orders/e43e7413-ba40-4934-ae8d-a4e0aec15144

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

{
  "ok": true,
  "order": {
    "order_id": "e43e7413-ba40-4934-ae8d-a4e0aec15144",
    "product": "Eternal",
    "qty": 100,
    "unit_price_kopeks": 4,
    "total_kopeks": 400,
    "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
    }
  }
}

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

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

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

API возвращает JSON со списком email/password для завершённого заказа.

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

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

GET /api/v1/orders/e43e7413-ba40-4934-ae8d-a4e0aec15144/result

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

{
  "ok": true,
  "order_id": "e43e7413-ba40-4934-ae8d-a4e0aec15144",
  "items": [
    {
      "email": "aldonusleeden@plovmail.com",
      "password": "Ef3_!OQ89Ki0"
    },
    {
      "email": "denwrighthaleear@onexsmail.com",
      "password": "#3%HlJv1OP-_"
    }
  ]
}

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

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

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

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

GET /api/v1/mailbox?email=denwrighthaleear@onexsmail.com

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

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

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

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

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

Параметры

  • email — обязателен
  • limit — необязателен, по умолчанию 50, максимум 100
  • cursor — необязателен

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

GET /api/v1/mailbox/messages?email=denwrighthaleear@onexsmail.com&limit=5

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

{
  "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
}

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

GET /api/v1/messages/{msg_id}

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

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

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

GET /api/v1/messages/m63264u1

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

{
  "ok": true,
  "message": {
    "msg_id": "m63264u1",
    "email": "denwrighthaleear@onexsmail.com",
    "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
  }
}

7.10 HTML письма

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

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

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

  • HTTP 200
  • Content-Type: text/html; charset=utf-8
  • тело HTML

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

GET /api/v1/messages/m63264u1/html

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

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

Далее идёт HTML документа письма.

7.11 Смена PJ

POST /api/v1/mailbox/password/change

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

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

{
  "email": "denwrighthaleear@onexsmail.com",
  "old_password": "#3%HlJv1OP-_",
  "new_password": "NewPass123!"
}

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

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

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

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

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

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

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

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

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

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

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

Idempotency-Key: <UNIQUE_KEY>

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

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

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

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

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

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

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

  1. Открыть в боте раздел ☁️ 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. Получить карточку почты через GET /api/v1/mailbox
  2. Получить список писем через GET /api/v1/mailbox/messages
  3. Получить карточку письма через GET /api/v1/messages/{msg_id}
  4. При необходимости получить HTML письма через GET /api/v1/messages/{msg_id}/html

Смена пароля

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

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

  • API v1 уже работает с UUID-идентификаторами заказов
  • msg_id письма нужно брать из ответа GET /api/v1/mailbox/messages
  • для Personal всегда передаётся полный домен строкой в поле domain
  • кнопка Документация в боте ведёт на Telegraph-страницу документации
  • /api/v1/docs и /api/v1/openapi.json существуют как web-представление документации и OpenAPI-схемы

13. Пример минимального сценария

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

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

Баланс

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

Каталог

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

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

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

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

curl \
  -H "Authorization: Bearer <TOKEN>" \
  --get \
  --data-urlencode "email=denwrighthaleear@onexsmail.com" \
  --data-urlencode "limit=5" \
  https://api.smakmail.com/api/v1/mailbox/messages

HTML письма

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

Смена PJ

curl \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email":"denwrighthaleear@onexsmail.com","old_password":"#3%HlJv1OP-_","new_password":"NewPass123!"}' \
  https://api.smakmail.com/api/v1/mailbox/password/change
Report content on this page

Report Page

Please submit your DMCA takedown request to dmca@telegram.org