API для почты: аренда Gmail и iCloud и получение кодов по HTTP

Последнее обновление: 10 октября 2026 г.

API OTPGmail — это REST API, через который программа арендует настоящий ящик @gmail.com или @icloud.com и получает код подтверждения или ссылку из пришедшего письма: создаёте заказ, раз в 3–5 секунд опрашиваете его и забираете код из ответа в JSON. Если код не пришёл за время ожидания (не более 25 минут), заказ отменяется сам, и 100 % стоимости возвращается на баланс.

Это не Gmail API от Google — тот работает с вашим собственным ящиком через OAuth — и не API Почты России. В русскоязычной среде автоматизации такие сервисы называют «почтовыми активациями»; здесь речь именно о них, в рамках правил платформ, где вы регистрируетесь.

Быстрый старт

1. Создайте аккаунт OTPGmail на странице регистрации и пополните баланс в USDT или USDC.
2. Возьмите ключ API на странице «Профиль»: он начинается с og_, срока действия у него нет, а перевыпустить его можно там же.
3. Передавайте ключ в заголовке Authorization: Bearer <ключ> (или параметром ?api_key=, если заголовок неудобен).
4. Ответы приходят в едином формате: {"success": true, "data": ...} при успехе и {"success": false, "error": {"code": ..., "message": ...}} при ошибке.

Отдельной платы за API нет: аренда через API стоит столько же, сколько в веб-приложении, и списывается с того же баланса.

Основные запросы

Пример на curl — аренда ящика для GitHub (git) и опрос заказа:

HOST=otpgmail.net
KEY=og_ваш_ключ
curl -s -X POST "https://$HOST/v1/orders" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service": "git", "domain": "gmail.com"}'
# в ответе data — список; берём data[0].orderId и data[0].email
curl -s "https://$HOST/v1/orders/ORDER_ID" -H "Authorization: Bearer $KEY"

Опрос заказа и коды

Опрашивайте GET /v1/orders/{id} раз в 3–5 секунд. Статус waiting_code значит, что код ещё ждём; completed — код пришёл и лежит в списке otp; cancelled — заказ отменён; если по правилам источника положен возврат, деньги уже на балансе. Новые коды добавляются в конец otp, поэтому последний полученный код — последний элемент. У части сервисов вместо цифр приходит ссылка подтверждения — тогда ссылка будет в поле code.

Дополнительные коды не стоят ничего сверх цены аренды в пределах срока заказа, если сервис присылает больше одного кода; многие сервисы присылают только один. У источников с платным продлением новое окно открывается запросом next-code: вне окна без доплаты API требует явного подтверждения платы полем confirmFee: true, иначе вернёт NEXT_CODE_FEE_CONFIRM.

Ошибки и лимиты

• NO_MAILS_AVAILABLE, OUT_OF_STOCK — ящики для сервиса закончились; деньги не списаны.
• DOMAIN_UNAVAILABLE — у сервиса нет варианта iCloud или он временно выключен.
• WAREHOUSE_UNAVAILABLE, ALL_WAREHOUSES_EXHAUSTED — выбранный источник или все источники недоступны; деньги не списаны.
• INSUFFICIENT_BALANCE — не хватает баланса.
• ORDER_NOT_CANCELLABLE — код уже пришёл или правила сервиса не допускают отмену.
• RATE_LIMITED (HTTP 429) — превышен лимит; подождите столько секунд, сколько указано в Retry-After.
• VALIDATION_ERROR — неверный параметр или код сервиса.

Лимит по умолчанию — 20 запросов в секунду и 900 в минуту на ключ. В одном запросе можно арендовать до 200 ящиков полем quantity. На каждый новый заказ отправляйте заголовок Idempotency-Key с уникальным значением: если запрос оборвался, повтор с тем же ключом вернёт уже созданный заказ, а не выдаст второй ящик. Таймаут на стороне клиента разумно ставить около 15 секунд.

Gmail, iCloud и выбор источника

Параметр domain принимает gmail.com (по умолчанию) или icloud.com. Ящики iCloud обычно дешевле Gmail — в зависимости от сервиса; удобная схема — запросить iCloud, а при DOMAIN_UNAVAILABLE или NO_MAILS_AVAILABLE повторить с Gmail.

Один сервис может продаваться из нескольких источников — у каждого своя цена, наличие и правила получения кодов. Параметр warehouse задаёт выбор: без него используется источник по умолчанию, 0 — источник с наименьшей ценой в наличии, 99 — перебор от дешёвого к дорогому, пока не найдётся ящик. Правила источника возвращаются вместе с заказом и описаны в документации API.

Пакеты через API

Пакеты до 200 ящиков покупаются на сайте, а через API их можно читать: GET /v1/batches, GET /v1/batches/{id} и коды конкретного ящика по пути /v1/batches/{id}/mails/{mailId}/codes. У пакетов Gmail каждому ящику выдаётся своя ссылка для получения кода в JSON, которая работает без ключа API, — храните такие ссылки в секрете. За ящики пакета, на которые код не пришёл, деньги не возвращаются.

Примеры и интеграции

• API для получения кода из почты на Python — готовый код на requests, обработка ошибок и фикстура для автотестов.
• ZennoPoster и BAS — запросы, пути в JSON и цикл ожидания для шаблонов.
• Правила возврата для заказов через API те же, что и в приложении: возврат и гарантия.

Ключ API личный: не передавайте и не перепродавайте его третьим лицам без письменного согласия OTPGmail. Соблюдайте правила сервисов, в которых регистрируетесь; OTPGmail не отвечает за использование не по назначению.

Часто задаваемые вопросы

Это Gmail API от Google?

Нет. Gmail API от Google даёт доступ к вашему собственному ящику через OAuth. API OTPGmail выдаёт арендованный адрес и возвращает код из пришедшего письма; входить в ящик не нужно.

Сколько стоит доступ к API?

Отдельной платы нет. Вы платите только за арендованные ящики — по тем же ценам, что и в веб-приложении, с того же баланса.

Можно ли купить Gmail-аккаунты через API?

Да: Gmail-аккаунты на короткий срок покупаются через эндпоинты /v1/mail-shop. Пакеты покупаются только на сайте; через API доступны аренда ящиков, опрос заказов и чтение кодов пакетов.

Что делать при ошибке NO_MAILS_AVAILABLE?

Деньги не списаны. Повторите запрос позже, попробуйте другой тип адреса или параметр warehouse со значением 99, чтобы система сама перебрала источники.