PUBLIC API

Справочник API

Назначение методов, параметры запросов и значения полей ответа.

Все запросы — GET. Обязательный параметр: token — ваш личный API-токен.

Базовый адрес: HTTPS-адрес этой страницы

Первый запрос

Скопируйте URL в адресную строку. Замените USER_TOKEN своим токеном, text.ru — нужным сервисом.

https://YOUR_API_HOST/domain-email/available?sender=text.ru&token=USER_TOKEN

Ответ: список доступных доменов и цен. Подробности — в методе available.

Спецсимволы в значениях кодируйте для URL: + → %2B, & → %26, @ → %40. Вместо token допустим заголовок Authorization: Bearer USER_TOKEN.

Не передавайте свой токен другим людям. URL с токеном может сохраниться в истории браузера. Покупка и перезаказ могут списать деньги; не повторяйте покупку автоматически после ошибки связи.

Проверить запрос

Вызов available: домены и цены, без покупки.

Запрос ещё не отправлен.

GET /domain-email/available

Доступные домены и цены

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

Параметр	Обязателен	Описание
`sender`	Да	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/available?sender=text.ru&token=USER_TOKEN

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

{
  "items": [
    {
      "domain": "example.com",
      "price": {
        "amount": "0.012",
        "currency": "USD"
      }
    }
  ]
}

items — доступные домены; domain — домен; price.amount — цена; price.currency — валюта. Пустой items — нет доступных предложений.

GET /domain-email/prices

Каталог цен

Возвращает цены для указанного сервиса. Формат ответа совпадает с available.

Параметр	Обязателен	Описание
`sender`	Да	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/prices?sender=text.ru&token=USER_TOKEN

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

{
  "items": [
    {
      "domain": "example.com",
      "price": {
        "amount": "0.012",
        "currency": "USD"
      }
    }
  ]
}

items — доступные домены; domain — домен; price.amount — цена; price.currency — валюта. Пустой items — нет доступных предложений.

GET /domain-email/check-custom

Проверить своё имя ящика

Проверяет, можно ли купить указанный адрес для сервиса. Без покупки.

Параметр	Обязателен	Описание
`domain`	Да	Принимающий домен из available, без имени ящика.
`name`	Да	Часть до @: латинские буквы, цифры, ., _, +, -. Без .. и точек по краям.minLength: 1, maxLength: 63
`site`	Нет	Ключ сервиса вместо sender; нужно одно из site/sender. Разные значения одновременно запрещены.
`sender`	Нет	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/check-custom?domain=example.com&name=mylogin&site=text.ru&token=USER_TOKEN

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

{
  "email": "mylogin@example.com",
  "purchasable": true,
  "price": {
    "amount": "0.012",
    "currency": "USD"
  }
}

email — проверяемый адрес; purchasable — можно ли купить; price — цена и валюта, либо null. При отказе добавляется reason: custom_mailbox_service_already_owned — уже ваш (используйте перезаказ), custom_mailbox_service_taken — занят другим пользователем, custom_mailbox_not_shared — адрес недоступен, mailbox_issuance_paused или sender_issuance_paused — выдача приостановлена, domain_unavailable — домен недоступен, domain_mailbox_quota_exceeded — нет свободных мест, price_unavailable — покупка по текущей цене недоступна.

GET /domain-email/order

Купить адрес для сервиса

Покупает адрес на указанном домене. Платный запрос. Каждый вызов — новая покупка.

Параметр	Обязателен	Описание
`domain`	Да	Принимающий домен из available, без имени ящика.
`site`	Нет	Ключ сервиса вместо sender; нужно одно из site/sender. Разные значения одновременно запрещены.
`sender`	Нет	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.
`label`	Нет	Необязательная подпись заказа.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/order?domain=example.com&site=text.ru&token=USER_TOKEN

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

{
  "ok": true,
  "order_id": 51,
  "email": "box@example.com"
}

ok — покупка успешна; order_id — ID заказа, передавайте как activation_id при чтении письма; email — купленный адрес. Статус получения письма смотрите в activations.

GET /domain-email/order-custom

Купить адрес со своим именем

Покупает адрес с указанным именем. Платный запрос. Каждый вызов — новая покупка.

Параметр	Обязателен	Описание
`domain`	Да	Принимающий домен из available, без имени ящика.
`name`	Да	Часть до @: латинские буквы, цифры, ., _, +, -. Без .. и точек по краям.minLength: 1, maxLength: 63
`site`	Нет	Ключ сервиса вместо sender; нужно одно из site/sender. Разные значения одновременно запрещены.
`sender`	Нет	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.
`label`	Нет	Необязательная подпись заказа.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/order-custom?domain=example.com&name=mylogin&site=text.ru&token=USER_TOKEN

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

{
  "ok": true,
  "order_id": 52,
  "email": "mylogin@example.com"
}

GET /domain-email/routes

Мои назначения

Возвращает ваши адреса и сервисы.

Параметр	Обязателен	Описание

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/routes?token=USER_TOKEN

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

{
  "items": [
    {
      "email": "box@example.com",
      "senders": [
        {
          "sender": "text.ru",
          "label": null,
          "purchase": {
            "activation_id": 51,
            "price": "0.012",
            "currency": "USD",
            "purchased_at": "2026-11-01 12:00:00"
          }
        }
      ]
    }
  ]
}

items — ваши адреса; email — адрес; senders — сервисы; sender — сервис или точный отправитель; label — подпись. purchase — последняя покупка или null: activation_id — ID активации, price — цена, currency — валюта, purchased_at — дата покупки в UTC. История и статусы — в orders и activations.

GET /domain-email/activations

Активации

Возвращает ваши активации и статусы получения писем.

Параметр	Обязателен	Описание
`limit`	Нет	Размер страницы в пределах указанных ограничений.maximum: 500, minimum: 1, default: 100
`page`	Нет	Номер страницы, начиная с 1.minimum: 1, default: 1
`page_size`	Нет	Альтернативный размер страницы; при передаче имеет приоритет над limit.
`before_id`	Нет	Курсор вместо постраничной навигации.
`refresh`	Нет	true только для ручного обновления; по умолчанию false.default: False

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/activations?page=1&page_size=20&token=USER_TOKEN

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

{
  "status": "success",
  "data": [
    {
      "activation_id": 51,
      "user_id": 3,
      "from": "text.ru",
      "price": 0.012,
      "email": "box@example.com",
      "created_at": 1793400000,
      "ratio_withdrawal": "0.00000",
      "status": 1
    }
  ],
  "pages": 1
}

status в корне — результат запроса. data — список; activation_id — ID активации; user_id — ID пользователя; from — сервис; price — цена; email — адрес; created_at — Unix-секунды; ratio_withdrawal — коэффициент списания. status в строке: 0 — ожидание, 1 — письмо получено, -1 — отменено, ошибка или возврат. pages — число страниц; при before_id вместо pages возвращаются next_page и next_cursor.

GET /domain-email/orders

История покупок

Возвращает историю покупок, цены и статусы.

Параметр	Обязателен	Описание
`limit`	Нет	Размер страницы в пределах указанных ограничений.maximum: 500, minimum: 1, default: 50
`page`	Нет	Номер страницы, начиная с 1.minimum: 1, default: 1
`page_size`	Нет	Альтернативный размер страницы; при передаче имеет приоритет над limit.
`before_id`	Нет	Курсор вместо постраничной навигации.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/orders?page=1&limit=20&token=USER_TOKEN

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

{
  "status": "success",
  "data": [
    {
      "activation_id": 51,
      "user_id": 3,
      "from": "text.ru",
      "price": 0.012,
      "email": "box@example.com",
      "created_at": 1793400000,
      "ratio_withdrawal": "0.00000",
      "status": 1
    }
  ],
  "pages": 1
}

GET /domain-email/reorder

Перезаказ

Заказывает следующее письмо для последней активации со статусом 1 или -1. Может списать деньги. Повтор того же id возвращает тот же перезаказ.

Параметр	Обязателен	Описание
`id`	Да	ID последней своей активации для перезаказа.minimum: 1

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/reorder?id=51&token=USER_TOKEN

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

{
  "status": "success",
  "id": "74",
  "email": "box@example.com"
}

status — результат запроса; id — ID новой активации; email — адрес. Для чтения следующего письма используйте новый id как activation_id.

GET /domain-email/messages

Список писем активации

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

Параметр	Обязателен	Описание
`email`	Да	Адрес из своей активации.
`sender`	Да	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.
`activation_id`	Нет	ID своей активации. Всегда передавайте в новых интеграциях; без него выбирается последняя.
`limit`	Нет	Размер страницы в пределах указанных ограничений.maximum: 100, minimum: 1, default: 20
`offset`	Нет	Смещение списка, начиная с 0.minimum: 0, default: 0

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/messages?activation_id=51&email=box%40example.com&sender=text.ru&limit=20&offset=0&token=USER_TOKEN

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

{
  "items": [
    {
      "uid": "a123",
      "from": "Text.ru <no-reply@text.ru>",
      "subject": "Код подтверждения"
    }
  ],
  "total": 1
}

items — список писем; total — количество; uid — ID письма, передавайте строкой без изменений; from — отправитель; subject — тема. Если возвращён content_status: available — содержимое доступно, expired — недоступно; available_until — срок доступности в Unix-секундах.

GET /domain-email/message

Прочитать письмо

Возвращает содержимое письма по uid из messages.

Параметр	Обязателен	Описание
`email`	Да	Адрес из своей активации.
`sender`	Да	Ключ сервиса (например text.ru) или точный адрес отправителя. Для чтения — from активации.
`uid`	Да	Строка из messages, в том числе a123. Не преобразовывайте в число.
`activation_id`	Нет	ID своей активации. Всегда передавайте в новых интеграциях; без него выбирается последняя.

Плюс пользовательская авторизация для каждого запроса.

https://YOUR_API_HOST/domain-email/message?activation_id=51&email=box%40example.com&sender=text.ru&uid=a123&token=USER_TOKEN

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

{
  "uid": "a123",
  "headers": {
    "from": "Text.ru <no-reply@text.ru>",
    "to": "box@example.com",
    "subject": "Код подтверждения",
    "date": "Sun, 01 Nov 2026 12:00:00 +0000"
  },
  "body": "Код подтверждения: 123456",
  "content_type": "text/plain",
  "text_body": "Код подтверждения: 123456",
  "plain_body": "Код подтверждения: 123456",
  "html_body": "",
  "has_html": false,
  "remote_content_blocked": false
}

uid — ID письма; headers — отправитель, получатель, тема и дата; body — содержимое; content_type — формат body; text_body/plain_body — текст; html_body — HTML; has_html — есть ли HTML; remote_content_blocked — внешние изображения заблокированы. available_until, если есть, — срок доступности в Unix-секундах. HTML отображайте в sandbox iframe без скриптов, текст — через textContent.

Коды ошибок

detail — описание ошибки: строка либо объект с полями error и reason.

{"detail":"token_invalid"}

HTTP	Значение
400 / 422	Некорректные параметры запроса.
401	Токен отсутствует или неверен (token_invalid).
402	Недостаточно средств (insufficient_balance).
403	Нет доступа. При direct_api_user_not_allowed обратитесь в поддержку.
404	Ресурс не найден.
409	domain_unavailable — домен недоступен; mailbox_service_reserved_by_another_user — адрес для сервиса занят; reorder_not_available — перезаказ недоступен; activation_payment_pending — оплата не завершена.
410	message_expired — содержимое письма больше недоступно.
422	invalid_parameters — проверьте параметры запроса.
429	Превышен лимит запросов. Retry-After — время ожидания в секундах.
500 / 502 / 503	service_unavailable или message_temporarily_unavailable — временная ошибка. payment_pending / payment_review — результат оплаты ещё не подтверждён; проверьте историю, не повторяйте покупку автоматически.

Ошибка содержит краткий код в detail, например:

{"detail":"domain_unavailable"}

После ошибки или потери ответа покупки сначала проверьте историю. Не повторяйте покупку автоматически.