Apply custom discountAnyone who rents OTP Gmail > 2000 Gmails per day for any service (except Facebook, Instagram, and Apple) and wants a private discount, feel free to message me! Discounts can be up to 50% off the original price for those registering accounts in large enough volumes.
New update - Buy ProxyWe've just added a new feature to buy super cheap proxies for those of you registering accounts. Feel free to check it out!

Документація API

Публічний API /v1: автентифікація за ключем API та автоматизація оренди скриньок зі свого програмного забезпечення

Ваш ключ API
Ви не ввійшли в акаунт: увійдіть, щоб отримати власний ключ API.
Надсилайте цей ключ у заголовку Authorization: Bearer <key> або в параметрі запиту ?api_key=<key>. Натисніть значок ока, щоб побачити ключ повністю; натисніть Створити новий ключ, коли його потрібно замінити (старий ключ одразу перестане працювати).

Огляд

Базовий URL
https://onemail.wtf
Автентифікація
Додавайте свій ключ API до кожного запиту: або в заголовок Authorization: Bearer og_xxx... (рекомендовано), або в рядок запиту ?api_key=og_xxx....
Idempotency-Key (запобігає дублюванню замовлень)
Кожен запит POST /v1/orders має містити заголовок Idempotency-Key: <новий UUID на замовлення>. Якщо час очікування запиту минув або з'єднання обірвалося, надішліть його ще раз із тим самим ключем: сервер поверне початкову відповідь замість створення ще одного замовлення. Створюйте новий UUID для кожного нового замовлення й використовуйте UUID повторно лише під час повторної спроби.
Багато замовлень одночасно: статус за один виклик
Орендуєте десятки чи сотні скриньок? Запитуйте їхній статус разом: POST /v1/orders/status повертає до 100 замовлень за виклик (рахується як один запит у ліміті), а GET /v1/orders показує список ваших замовлень — після перезапуску ?status=waiting_code поверне всі замовлення, що ще чекають на код. Кожна помилка також повідомляє, чи варто повторювати (error.retryable, error.retryAfterSec). Докладніше: розділ Статус багатьох замовлень.
Тип скриньки: Gmail або iCloud
За замовчуванням ви отримуєте скриньку @gmail.com. Щоб орендувати скриньку @icloud.com, додайте "domain": "icloud.com" до тіла POST /v1/orders. Якщо domain не вказано, це означає gmail.com: наявні інтеграції продовжують працювати без змін. iCloud доступний лише для сервісів, у яких поле icloud у GET /v1/services не дорівнює null; ціна iCloud може відрізнятися від ціни Gmail (див. icloud.price). Кожна відповідь із замовленням містить поле domain, яке показує, який тип скриньки використовує замовлення. Деякі сервіси також пропонують скриньки @gmx.com (наразі лише Pokemon, код pkm, склад 2): надішліть "domain": "gmx.com"; сервіс пропонує його, якщо в його offers[] у GET /v1/services є запис із domain = "gmx.com"; для будь-якого іншого сервісу ⇒ DOMAIN_UNAVAILABLE. gmx.com недоступний для партій.
Склади: один сервіс, кілька джерел скриньок
Сервіс може продаватися з кількох складів, кожен зі своєю ціною, наявністю та правилами кодів (масив offers[] у GET /v1/services). Надішліть "warehouse": 2 під час створення замовлення, щоб обрати склад; "warehouse": 99 ⇒ система обирає найдешевший склад із наявністю й переходить до наступного, якщо він вичерпається (ідеально для сервісів, що часто вичерпуються, як-от Facebook та Instagram); 0 ⇒ найдешевший склад із наявністю. Наявним клієнтам нічого змінювати не потрібно: якщо warehouse не вказано ⇒ склад 1, як раніше, а price, stock і icloud описують склад 1 (сервіси без складу 1 ⇒ найдешевший склад із наявністю). Докладніше: див. Склади.
Масова оренда (партії)
Партії купуються на сайті (сторінка «Масова оренда»); через API можна переглядати список партій і читати коди. Gmail (склад 1): кожна скринька має proxyUrl, посилання на код, якому не потрібен ключ API. iCloud (склад 3): приватні скриньки; читайте коди через GET /v1/batches/{id}/mails/{mailId}/codes або відкрийте readUrl на сайті. Докладніше: розділ «Масова оренда».
Купівля короткочасних акаунтів Gmail (магазин пошти)
Окрім оренди скриньок, ви можете купувати акаунти Gmail повністю з кількох складів: склад 1 — email, пароль, cookies + посилання на скриньку (також у JSON); склад 2 — email, пароль + швидке посилання для входу; склад 99 спершу бере найдешевший (сторінка «Купити короткочасний Gmail» на сайті). API робить усе, що й ця сторінка: показує склади, ціни й залишки, здійснює купівлю (потрібен Idempotency-Key), дозволяє стежити за доставкою, завантажувати акаунти й читати їхні листи. Докладніше: розділ «Магазин пошти».
Proxies
Buy HTTP proxies over the API: 5 types (Resident VN, VIP Resident VN, Datacenter VN, Resident US, Datacenter US) with a daily warranty — free replacement when one dies during the warranty. Same balance and prices as the website. #proxy
Дозвольте клієнтам самим читати коди (сторінка /otp)
Перепродаєте орендовані скриньки (на сайті або через API)? Увімкніть код доступу на сторінці «Акаунт», а потім надішліть клієнту посилання https://onemail.wtf/uk/otp#k7m2q9:[email protected] (k7m2q9 = ваш код доступу): він побачить останні коди цього email без входу в акаунт і ніколи не побачить цін чи вашого балансу; сторінка виконує лише безкоштовні дії (з вас нічого не списується).
JSON-посилання для програм і ботів (ваших або клієнта): візьміть посилання у вигляді шляху https://onemail.wtf/uk/otp/k7m2q9:[email protected] (воно відкриває сторінку /otp так само, як посилання з #) і додайте ?json ⇒ сервер поверне JSON рівно з тими даними, які показує сторінка: cards[] — по картці на кожен сервіс, орендований на цьому email (email, serviceName, state, items[] = до 5 останніх кодів / посилань, нові першими), — і serverTime. state: waiting чекає на перший код · listening чекає на новий код · received коди отримано · needs_owner продавець має продовжити · expired термін минув · banned скриньку заблоковано. Кілька email — через кому (не більше 50). Без API-ключа й cookie, CORS відкритий; лише читання («Завантажити новий OTP» / «Орендувати цю адресу знову» лишаються на сторінці /otp). Ті самі обмеження проти підбору, що й на сторінці: невірний код / для email немає замовлень для показу ⇒ 404 NOT_FOUND; повторні промахи або понад 30 запитів на хвилину для одного email ⇒ 429 RATE_LIMITED з retryAfter (секунди). Якщо додати ?json до посилання /otp#…, JSON не повернеться: браузер ніколи не надсилає на сервер частину після #.
curl "https://onemail.wtf/uk/otp/k7m2q9:[email protected]?json"
{
  "success": true,
  "data": {
    "cards": [
      {
        "ref": "Q3vX9kL2mP0aB7cD",
        "serviceCode": "fb",
        "serviceName": "Facebook",
        "logo": "/logos/fb.png?v=20261007",
        "domain": "gmail.com",
        "email": "[email protected]",
        "state": "received",
        "until": null,
        "items": [
          {
            "kind": "code",
            "value": "529170",
            "label": null,
            "at": 1760000405
          },
          {
            "kind": "code",
            "value": "381904",
            "label": null,
            "at": 1759999030
          }
        ],
        "total": 2,
        "canLoad": true
      }
    ],
    "serverTime": 1760000530
  }
}
Повні приклади коду на GitHub
Готові до запуску клієнти для Python, Node.js, PHP, C# (.NET) і curl: орендуйте скриньку, чекайте на код, автоматично скасовуйте для повернення коштів і перемикайтеся між iCloud та Gmail, коли наявність вичерпується: github.com/letoan0902/otpgmail-email-otp-api (англійською) · thue-otp-gmail (в'єтнамською). Примітка щодо Python: використовуйте requests замість «голого» urllib (його User-Agent за замовчуванням отримує 403 від CDN).
Вебхуки
Замість постійного опитування кожного замовлення зареєструйте один URL і отримуйте підписаний POST, щойно замовлення отримає новий код або його буде скасовано чи відшкодовано — див. Вебхуки.

Ендпоінти

GET/v1/balance
Повертає баланс акаунта (у VND) для ключа API, використаного в запиті.
Приклад
curl "https://onemail.wtf/v1/balance" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "balance": 25000
  }
}
Можливі помилки: UNAUTHORIZED
GET/v1/services
Показує список увімкнених сервісів: код, назва, ціна Gmail (у VND) і поточна наявність Gmail, блок icloud із ціною та наявністю для скриньок @icloud.com, а також масив offers[]: кожен склад, що продає сервіс, по одному запису на склад × тип скриньки (ціна, наявність, кількість кодів, правила). Дані кешуються: наявність оновлюється приблизно кожні 30–60 секунд, ціни рідше.
icloud = null означає, що сервіс ще не підтримує iCloud (постачальник його не пропонує або його тимчасово вимкнено): орендувати можна лише Gmail. Для сервісів із блоком icloud надішліть "domain": "icloud.com" під час створення замовлення, щоб отримати скриньку @icloud.com за ціною icloud.price. price / stock / icloud.price описують склад 1, куди потрапляють замовлення без warehouse (сервіси без складу 1 ⇒ найдешевший склад із наявністю); ціни й наявність по кожному складу є в offers[] (див. Склади). stock — число, яке публікує джерело (склад 1: оновлюється приблизно раз на 30 секунд), і це не обіцянка, що один виклик орендує стільки ж: скриньки видаються по одній, і джерело може вичерпатися посередині — тоді POST /v1/orders поверне менше замовлень і поле partial. Склади 2 і 4 так само показують числа своїх джерел.
Приклад
curl "https://onemail.wtf/v1/services" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": [
    {
      "code": "dr",
      "name": "OpenAI (ChatGPT)",
      "price": 350,
      "stock": 616525,
      "icloud": {
        "price": 630,
        "stock": 12464
      },
      "offers": [
        {
          "warehouse": 2,
          "domain": "gmail.com",
          "price": 350,
          "stock": 616525,
          "maxCodes": null,
          "rules": null,
          "fee": {
            "freeHours": 6,
            "paidPct": 50,
            "maxHours": 24
          },
          "isDefault": true
        },
        {
          "warehouse": 1,
          "domain": "gmail.com",
          "price": 630,
          "stock": 12464,
          "maxCodes": 3,
          "rules": null,
          "fee": null,
          "isDefault": false
        },
        {
          "warehouse": 1,
          "domain": "icloud.com",
          "price": 630,
          "stock": 12464,
          "maxCodes": 5,
          "rules": null,
          "fee": null,
          "isDefault": true
        }
      ],
      "note": null
    },
    {
      "code": "fb",
      "name": "Facebook",
      "price": 1590,
      "stock": 88,
      "icloud": null,
      "offers": [
        {
          "warehouse": 1,
          "domain": "gmail.com",
          "price": 1590,
          "stock": 88,
          "maxCodes": 10,
          "rules": null,
          "fee": null,
          "isDefault": false
        },
        {
          "warehouse": 4,
          "domain": "gmail.com",
          "price": 1580,
          "stock": 2310,
          "maxCodes": null,
          "rules": null,
          "fee": null,
          "isDefault": true
        }
      ],
      "note": null
    }
  ]
}
Можливі помилки: UNAUTHORIZED
POST/v1/orders
Створює замовлення на скриньку, що отримує коди підтвердження: за замовчуванням Gmail або iCloud, якщо надіслати domain: "icloud.com". Кошти з балансу списуються, щойно постачальник призначає скриньку. Повертає список замовлень (одне або кілька, якщо quantity > 1).
Часткова видача: quantity — це максимум
  • Скриньки видаються по одній. Якщо в постачальника вони закінчаться посередині (наприклад, на складі 1 у цю мить немає скриньок для цього сервісу), виклик зупиняється й повертає HTTP 200 з уже створеними замовленнями: data може бути коротшим за quantity, а списання відбувається лише за замовлення з data. Значення stock у GET /v1/services не гарантує, скільки отримає один виклик.
  • Тоді у відповіді поруч із data є ще поле верхнього рівня partial (якщо видано все, його немає — боти, що читають лише data, працюють без змін): requested, delivered, missing і reason = {code, message, retryable, retryAfterSec}, де code — помилка, що зупинила виклик (NO_MAILS_AVAILABLE, OUT_OF_STOCK, ALL_WAREHOUSES_EXHAUSTED, INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED…).
  • Нестача зазвичай тимчасова: на складі 1 за кілька секунд у постачальника часто знову є скриньки. Якщо reason.retryable = true, зачекайте reason.retryAfterSec секунд (3–5 с) і знову запросіть скриньки, яких бракує (missing), з НОВИМ Idempotency-Key (старий ключ лише повторить цю саму відповідь); повторюйте, доки не отримаєте всі.
  • Одразу після часткової видачі наступний виклик може повернути 409 WAREHOUSE_UNAVAILABLE / OUT_OF_STOCK або 503 NO_MAILS_AVAILABLE — це нормально: і далі робіть паузи по 3–5 с між викликами та здавайтеся, лише коли багато викликів поспіль невдалі (наприклад, 10 спроб — близько хвилини); тоді спробуйте пізніше або надішліть "warehouse": 99, щоб система перейшла на інші склади. retryable = false (INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED…) ⇒ спершу усуньте причину (поповніть баланс або дочекайтеся завершення відкритих замовлень).
  • Відповіді з помилкою містять ці самі два поля всередині error: error.retryable і error.retryAfterSec (наприклад, 409 OUT_OF_STOCK ⇒ true, 5; 402 INSUFFICIENT_BALANCE ⇒ false, null) — див. «Коди помилок».
Заголовок Idempotency-Key (UUID) обов'язковий. Створюйте новий UUID для кожної нової оренди; під час повторної спроби після тайм-ауту використовуйте ТОЙ САМИЙ ключ, щоб не створити дубльоване замовлення. Цей виклик чекає, поки постачальник призначить скриньку, тому зазвичай триває близько 0,3 секунди, але в години пік (рідко) може тривати до 10 секунд: встановіть тайм-аут клієнта приблизно 15 секунд, а не здавайтеся через 5 секунд і не повторюйте запит завчасно.
Параметри
НазваТипОбов'язковийОпис
servicestringТакКод сервісу (з GET /v1/services, напр. "ig", "tg", "fb")
quantitynumberНіМАКСИМАЛЬНА кількість скриньок для оренди (за замовчуванням 1; не більше 200 за запит) — якщо склад вичерпається посередині, ви отримаєте менше: рахуйте data[] і читайте partial
domainstringНіТип скриньки: "gmail.com" (за замовчуванням), "icloud.com" або "gmx.com". Якщо не вказано = gmail.com: наявним інтеграціям нічого змінювати не потрібно. iCloud можна орендувати лише для сервісів, у яких поле icloud у GET /v1/services не дорівнює null; "gmx.com" лише для сервісів з offers[].domain = "gmx.com" (наразі лише Pokemon, код pkm); інакше виклик завершується помилкою DOMAIN_UNAVAILABLE. Будь-яке інше значення ⇒ VALIDATION_ERROR.
warehousenumberНіСклад, з якого орендувати. Якщо не вказано = СКЛАД 1, точно так, як до появи кількох складів (сервіси без складу 1 переходять на найдешевший): наявним клієнтам нічого змінювати не потрібно. 0 = найдешевший склад із наявністю (пробується лише один склад). 1–4 = саме цей склад (з offers[].warehouse у GET /v1/services); якщо він не продає цей сервіс/тип скриньки, призупинений або в нього немає наявності ⇒ WAREHOUSE_UNAVAILABLE. 99 = АВТОМАТИЧНО: склади з наявністю пробуються від найдешевшого до найдорожчого, з переходом далі, коли склад вичерпано або він дає збій; якщо не лишилося жодного ⇒ ALL_WAREHOUSES_EXHAUSTED; рекомендовано для сервісів, що часто вичерпуються (Facebook, Instagram…). Див. Склади.
Приклад
# Створюйте випадковий Idempotency-Key для кожного НОВОГО замовлення
# ВИКОРИСТОВУЙТЕ той самий ключ повторно під час повторної спроби після тайм-ауту (запобігає дублюванню замовлень)
# domain: "gmail.com" (за замовчуванням, необов'язково) | "icloud.com" (оренда скриньки @icloud.com) | "gmx.com" (лише сервіси, які його пропонують, напр. Pokemon)
# warehouse: 0 | 1–4 | 99 (необов'язково: якщо не вказувати, залишається склад 1, як раніше; 0 = найдешевший склад із наявністю; 99 = автоматично, переходить далі, коли склад вичерпується; див. offers[] у GET /v1/services)
curl -X POST "https://onemail.wtf/v1/orders" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service":"ig","quantity":1,"domain":"gmail.com"}'
Приклад відповіді
{
  "success": true,
  "data": [
    {
      "orderId": "abc123xyz",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 1060,
      "otp": [],
      "codeDeadlineAt": 1753270000,
      "rentExpiresAt": 1753356400,
      "createdAt": 1753268200,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    }
  ]
}
Приклад відповіді — часткова видача (quantity 5, видано 2 скриньки)
{
  "success": true,
  "data": [
    {
      "orderId": "abc123xyz",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 1060,
      "otp": [],
      "codeDeadlineAt": 1753270000,
      "rentExpiresAt": 1753356400,
      "createdAt": 1753268200,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    },
    {
      "orderId": "jkl012mno",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 1060,
      "otp": [],
      "codeDeadlineAt": 1753270001,
      "rentExpiresAt": 1753356401,
      "createdAt": 1753268201,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    }
  ],
  "partial": {
    "requested": 5,
    "delivered": 2,
    "missing": 3,
    "reason": {
      "code": "NO_MAILS_AVAILABLE",
      "message": "No inboxes available for this service right now, please try again later",
      "retryable": true,
      "retryAfterSec": 5
    }
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, SERVICE_DISABLED, INSUFFICIENT_BALANCE, OUT_OF_STOCK, DOMAIN_UNAVAILABLE, WAREHOUSE_UNAVAILABLE, ALL_WAREHOUSES_EXHAUSTED, NO_MAILS_AVAILABLE, QUANTITY_EXCEEDED, WAITING_LIMIT_REACHED, RATE_LIMITED, DUPLICATE_REQUEST, PROVIDER_ERROR, MAINTENANCE
GET/v1/orders/{id}
Повертає замовлення за ID, зокрема коди, отримані на цей момент (otp[]). Опитуйте цей ендпоінт кожні 3–5 секунд, щоб підхопити код, поки замовлення має статус waiting_code.
Масив otp[] упорядковано за надходженням: найстаріший перший, НАЙНОВІШИЙ ОСТАННІЙ: читайте останній код через otp[otp.length - 1]. Під час кожного виклику система перевіряє в постачальника замовлення, що ще відкриті, у власному темпі кожного складу (кожні кілька секунд); частіші виклики просто повертають збережені дані. Після першого коду продовжуйте опитування: подальші коди (якщо сервіс надсилає більше одного) додаються в кінець otp[] без додаткової плати протягом строку замовлення; ліміт і часове вікно показано до оренди (maxCodes і fee в offers[]); щоб переконатися, що система очікує на новий код, викличте POST /v1/orders/{id}/next-code (для кожного складу; плату стягує лише склад 2 поза безкоштовним вікном). Якщо сервіс дозволяє лише один код на скриньку, otp[] зупиняється на цьому коді: відповіді залишаються звичайними, без помилки. Поле warehouse показує, який склад постачив скриньку (1–4); nextCodeFee — плата за додаткові коди (замовлення складів 2 і 3; null для складів 1 і 4), див. Склади. Починаючи з 2026-10-02 замовлення також містять nextCodeBlocked (true = скринька більше не може отримувати коди) і nextCodeBlockReason, причину: "email_banned" (email заблоковано сервісом: орендуйте новий), "activation_gone" (постачальник закрив скриньку), "hard_expired" (вікно кодів закінчилося), "max_codes" (отримано максимальну кількість кодів), null (не заблоковано / старіше замовлення без записаної причини). Це додані поля: наявним клієнтам нічого змінювати не потрібно. Замовлення, яке ще чекає на перший код, але чия скринька «померла» до терміну (найчастіше замовлення складу 2 з довгим очікуванням), завершується достроково: status "cancelled", повне повернення коштів, nextCodeBlocked = true і nextCodeBlockReason = "email_banned" (email заблоковано) або "activation_gone" (скриньки більше немає): орендуйте нову; у замовлення, яке просто дочекалося кінця терміну очікування, nextCodeBlockReason = null. Опитуєте багато замовлень? Надсилайте до 100 ID за виклик у POST /v1/orders/status замість окремого GET на кожне замовлення — ті самі об'єкти замовлень, один запит у ліміті.
Параметри
НазваТипОбов'язковийОпис
idstringТакID замовлення (orderId, повернений під час створення замовлення)
Приклад
curl "https://onemail.wtf/v1/orders/ORDER_ID" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "orderId": "abc123xyz",
    "service": "ig",
    "domain": "gmail.com",
    "email": "[email protected]",
    "status": "completed",
    "price": 1060,
    "otp": [
      {
        "code": "123456",
        "receivedAt": 1753268500
      },
      {
        "code": "789012",
        "receivedAt": 1753269000
      }
    ],
    "codeDeadlineAt": 1753270000,
    "rentExpiresAt": 1753356400,
    "createdAt": 1753268200,
    "warehouse": 1,
    "nextCodeFee": null,
    "listening": true,
    "listenUntil": 1753270500,
    "nextCodeBlocked": false,
    "nextCodeBlockReason": null
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND
POST/v1/orders/{id}/cancel
Скасовує замовлення й повертає 100% ціни. Дозволено лише поки замовлення має статус waiting_code І жодного коду не отримано.
Замовлення, що отримало код (навіть один), не можна скасувати чи повернути за нього кошти: це стосується і сайту, і API. Замовлення з rules.cancellable = false (сервіси власного складу, як-от Cointiply) скасувати не можна: щойно скриньку призначено, скасування й повернення коштів немає, а виклик скасування повертає ORDER_NOT_CANCELLABLE. Замовлення складу 3 для звичайних сервісів (rules.cancellable = true) можна скасувати, як і будь-які інші, до надходження коду.
Параметри
НазваТипОбов'язковийОпис
idstringТакID замовлення для скасування
Приклад
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/cancel" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json"
Приклад відповіді
{
  "success": true,
  "data": {
    "orderId": "abc123xyz",
    "service": "ig",
    "domain": "gmail.com",
    "email": "[email protected]",
    "status": "cancelled",
    "price": 1060,
    "otp": [],
    "codeDeadlineAt": 1753270000,
    "rentExpiresAt": 1753356400,
    "createdAt": 1753268200,
    "warehouse": 1,
    "nextCodeFee": null,
    "listening": false,
    "listenUntil": null,
    "nextCodeBlocked": false,
    "nextCodeBlockReason": null
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, ORDER_NOT_CANCELLABLE, PROVIDER_ERROR
POST/v1/orders/{id}/rerent
Орендує ТУ САМУ скриньку знову для замовлення сервісу власного складу (provider = "inventory", напр. Cointiply): створює НОВЕ замовлення на цій скриньці з новим вікном отримання за ціною rerentPriceVnd старого замовлення.
Працює, лише коли старе замовлення має canRerent = true (останнє замовлення цієї скриньки, попереднє вікно якого закінчилося або яке отримало всі свої листи). Гроші списуються, щойно виклик успішний: надішліть Idempotency-Key і використовуйте його повторно під час повторної спроби, щоб вас ніколи не списали двічі. Відповідь має вигляд { order, message }; order має ту саму форму, що й GET /v1/orders/{id}. Склад 2 (з 2026-10-09): замовлення, яке було скасовано, закінчилося за часом або прострочене (скриньку закрито): викликайте, коли canRerent = true (останнє замовлення цього email, і в email немає іншого активного замовлення). Система знову відкриває САМЕ ЦЕЙ email як НОВЕ замовлення (status = waiting_code) за ціною rerentPriceVnd (наразі 100% вашої ціни) і чекає 20 хв на лист, як для будь-якого замовлення складу 2: якщо листа немає, замовлення скасовується, а кошти повертаються на 100%. Email заблоковано сервісом ⇒ RERENT_EMAIL_BANNED; постачальник більше не може його відкрити ⇒ RERENT_MAIL_GONE; склад 2 тимчасово не працює ⇒ PROVIDER_ERROR; у жодному з трьох випадків кошти не списуються.
Параметри
НазваТипОбов'язковийОпис
idstringТакID попереднього замовлення на скриньку (того, де canRerent = true)
Приклад
# ВИКОРИСТОВУЙТЕ той самий ключ повторно під час повторної спроби після тайм-ауту (запобігає дублюванню замовлень)
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/rerent" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Idempotency-Key: $(uuidgen)"
Приклад відповіді
{
  "success": true,
  "data": {
    "order": {
      "orderId": "def456uvw",
      "service": "ctp",
      "domain": "icloud.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 3500,
      "otp": [],
      "codeDeadlineAt": 1753273500,
      "rentExpiresAt": 1753273500,
      "createdAt": 1753269000,
      "provider": "inventory",
      "rules": {
        "windowMinutes": 75,
        "maxCodes": 4,
        "cancellable": false,
        "refundOnTimeout": false,
        "rerentRatio": 0.5
      },
      "windowEndsAt": 1753273500,
      "canRerent": false,
      "rerentPriceVnd": 3500,
      "warehouse": 3,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    },
    "message": "Inbox rented again — a new 75-minute message window has started"
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, RERENT_NOT_AVAILABLE, RERENT_EMAIL_BANNED, RERENT_MAIL_GONE, INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED, RATE_LIMITED, DUPLICATE_REQUEST, PROVIDER_ERROR, MAINTENANCE
POST/v1/orders/{id}/next-code
Запитує наступний код на ТІЙ САМІЙ скриньці: працює для замовлень З УСІХ складів (склади 1–4), які вже отримали перший код (status = completed). Безкоштовно, окрім замовлень складу 2, чиє безкоштовне вікно закінчилося (nextCodeFee.feePriceVnd > 0): тоді надішліть confirmFee: true, щоб сплатити плату й відкрити ще одне вікно кодів (до жорсткого ліміту nextCodeFee.hardUntil). Вашому боту не потрібно знати склад: просто далі опитуйте GET /v1/orders/{id} — нові коди додаються до otp[] — і викликайте цей ендпоінт, коли хочете, щоб система очікувала на новий код.
Що робить цей виклик на кожному складі
  • Склад 1: система сама очікує на наступний код після кожного коду протягом строку замовлення (rentExpiresAt); виклик повертає 200 і нічого не змінює; коли скринька більше не може приймати коди (ліміт кодів вичерпано, скриньку закрито, термін минув) ⇒ 409 з nextCodeBlockReason.
  • Склад 2: знову відкриває скриньку в постачальника (reordered = true) і чекає 20 хв на лист; безкоштовно в межах безкоштовного вікна (nextCodeFee.feePriceVnd = 0), поза ним потрібно надіслати confirmFee = true (якщо немає ⇒ 409 NEXT_CODE_FEE_CONFIRM, нічого не списано). Плата залишається, лише якщо надійшов новий код: якщо коду немає протягом 20 хв ⇒ автоматичне повернення коштів. Після кожного коду система продовжує очікувати наступний ще 25 хв (listening = true, listenUntil).
  • Склад 3 (звичайні сервіси): відкриває коротке вікно прослуховування, безкоштовно в межах безкоштовного вікна (nextCodeFee.freeUntil); після нього ⇒ 409: скористайтеся POST /v1/orders/{id}/rerent. Сервіси власного складу, як-от Cointiply (rules.cancellable = false), не мають наступного коду (409): кожен лист з'являється сам протягом вікна. Склад 3 для Gmail (за сервісом): після кожного коду система перестає чекати — викличте цей метод, щоб чекати наступний, безкоштовно до rentExpiresAt (listening = true; повторний виклик під час очікування ⇒ 200, нічого не змінюється); строк минув ⇒ 409 hard_expired, скриньку закрито ⇒ 409 activation_gone.
  • Склад 4: повторно читає замовлення в постачальника й чекає на новий код, безкоштовно до rentExpiresAt.
200 = система очікує на новий код для цього замовлення (listening = true, listenUntil = коли очікування припиниться; reordered = true, якщо скриньку щойно відкрито знову; chargedVnd, якщо стягнуто плату), або новий код надійшов саме в момент вашого виклику (уже в order.otp). 409 = нове вікно очікування відкрити не вдалося: дивіться error.code; чому скринька не приймає більше кодів, зазначено в order.nextCodeBlockReason (GET /v1/orders/{id}). Замовлення, яке ще очікує на перший код (waiting_code) ⇒ 409, викликати поки не потрібно. Надсилайте Idempotency-Key з платними викликами (використовуйте його повторно під час повторної спроби, щоб вас ніколи не списали двічі). Постачальник недоступний ⇒ 502 PROVIDER_ERROR, спробуйте пізніше. Коди помилок 409 цього виклику: NEXT_CODE_FEE_CONFIRM (склад 2 потребує плати: викличте знову з confirmFee: true), EMAIL_BANNED (email заблоковано сервісом: орендуйте новий; error.details.blockReason = "email_banned"), ORDER_EXPIRED (термін минув, скриньку закрито, ліміт кодів вичерпано або в сервісу немає «наступного коду»: причина в order.nextCodeBlockReason), ORDER_NOT_CANCELLABLE (замовлення ще не отримало свого першого коду). Боти, які розглядають будь-який 409 від цього виклику як «більше кодів не буде», продовжують працювати без змін. refresh: true (склад 2): спочатку перевіряється новий лист (щойно отриманий видається, скринька не відкривається знову), потім скринька знову відкривається в постачальника — у безкоштовному вікні очікування починається заново на 20 хв; поза вікном строк очікування (listenUntil) не змінюється і нічого не списується. У відповіді додаються refreshed (true = щойно відкрито знову) і refreshAvailableAt (unix-секунди; до цього моменту повторне оновлення лише перевіряє листи; null = можна одразу). Інші склади: без ефекту (refreshed = false). Без refresh виклик працює точно як раніше.
Параметри
НазваТипОбов'язковийОпис
idstringТакID замовлення (orderId) — будь-який склад
confirmFeebooleanНіtrue = ви погоджуєтеся сплатити nextCodeFee.feePriceVnd, щоб відкрити ще одне вікно кодів. Не потрібно, поки feePriceVnd = 0.
refreshbooleanНіtrue = склад 2, замовлення чекає новий код (listening = true), але код не надходить: одразу знову відкрити скриньку в постачальника (оновити очікування) — попереднє очікування могло перестати отримувати листи на боці постачальника. Безкоштовно; не частіше одного разу на 5 с на замовлення. Замовлення не чекає ⇒ як звичайний виклик.
Приклад
# Безкоштовно (nextCodeFee дорівнює null або feePriceVnd = 0 — кожен склад, окрім складу 2 після його безкоштовного вікна): confirmFee не потрібен
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/next-code" \
  -H "Authorization: Bearer og_xxx..."

# Склад 2 після безкоштовного вікна: надішліть confirmFee = true, щоб сплатити nextCodeFee.feePriceVnd
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/next-code" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"confirmFee":true}'
Приклад відповіді
{
  "success": true,
  "data": {
    "order": {
      "orderId": "ghi789rst",
      "service": "dr",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "completed",
      "price": 350,
      "otp": [
        {
          "code": "482913",
          "receivedAt": 1753268300
        }
      ],
      "codeDeadlineAt": 1753269700,
      "rentExpiresAt": 1753354200,
      "createdAt": 1753267800,
      "warehouse": 2,
      "nextCodeFee": {
        "feePriceVnd": 0,
        "freeUntil": 1753311000,
        "hardUntil": 1753354200,
        "paidPct": 50,
        "freeHours": 6
      },
      "listening": true,
      "listenUntil": 1753269500,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    },
    "message": "Another code window is open — waiting for a new code",
    "listening": true,
    "listenUntil": 1753269500,
    "reordered": true
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, NEXT_CODE_FEE_CONFIRM, INSUFFICIENT_BALANCE, EMAIL_BANNED, ORDER_EXPIRED, ORDER_NOT_CANCELLABLE, PROVIDER_ERROR, DUPLICATE_REQUEST, MAINTENANCE

Статус багатьох замовлень за один виклик

Реселерам і ботам, які орендують багато скриньок, не варто надсилати окремий GET /v1/orders/{id} на кожне замовлення: POST /v1/orders/status читає до 100 замовлень за виклик з тими самими об'єктами замовлень, а GET /v1/orders показує список ваших замовлень зі збережених даних.
  • Опитуйте кожні 3–5 секунд через POST /v1/orders/status, до 100 ID замовлень за виклик — кожен виклик рахується як один запит у ліміті.
  • За кожен виклик система перевіряє в постачальника не більше 20 відкритих замовлень зі списку (спершу ті, що чекають перший код, потім ті, що найдовше не перевірялися), а решту повертає зі збережених даних; їх перевірять під час наступних викликів. Виклик відповідає приблизно за 3 секунди.
  • Прибирайте замовлення зі списку, щойно воно завершене: cancelled (кошти повернено) або completed, якщо більше кодів не потрібно.
  • ID, яких немає або які належать іншому акаунту, повертаються в missing (без 404) — приберіть і їх.
  • Після перезапуску поверніть усі відкриті замовлення через GET /v1/orders?status=waiting_code (ідіть за nextCursor) і продовжуйте опитування через POST /v1/orders/status.
POST/v1/orders/status
Повертає до 100 ваших замовлень за один виклик. Кожен елемент — саме те, що GET /v1/orders/{id} повертає для цього замовлення (status, otp[] з усіма отриманими кодами, warehouse…). Використовуйте, щоб опитувати одразу багато відкритих замовлень.
data зберігає порядок ids; повторювані ID ігноруються. ID, яких немає або які належать іншому акаунту, наведено в missing (без 404). Для відкритих замовлень система перевіряє постачальника так само, як GET /v1/orders/{id}, але не більше ніж для 20 замовлень за виклик — спершу ті, що чекають перший код, потім ті, що найдовше не перевірялися, — а решту повертає зі збережених даних (їх перевірять під час наступних викликів); виклик відповідає приблизно за 3 секунди. Один виклик — це один запит у ліміті, скільки б ID він не містив. Понад 100 ID, порожній список або ID не рядком ⇒ 400 VALIDATION_ERROR.
Параметри
НазваТипОбов'язковийОпис
idsstring[]ТакID замовлень (orderId) — від 1 до 100 за виклик
Приклад
# ID замовлень, на які ви чекаєте (orderId з POST /v1/orders), — до 100 за виклик
curl -X POST "https://onemail.wtf/v1/orders/status" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["ORDER_ID_1","ORDER_ID_2"]}'
Приклад відповіді
{
  "success": true,
  "data": [
    {
      "orderId": "abc123xyz",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "completed",
      "price": 1060,
      "otp": [
        {
          "code": "123456",
          "receivedAt": 1753268500
        }
      ],
      "codeDeadlineAt": 1753270000,
      "rentExpiresAt": 1753356400,
      "createdAt": 1753268200,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    },
    {
      "orderId": "jkl012mno",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 1060,
      "otp": [],
      "codeDeadlineAt": 1753270001,
      "rentExpiresAt": 1753356401,
      "createdAt": 1753268201,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    }
  ],
  "missing": [
    "zzz999qqq"
  ]
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED
GET/v1/orders
Список ваших замовлень, спершу найновіші, лише зі збережених даних — нових кодів у постачальника не запитує (це робить POST /v1/orders/status). Фільтр за статусом і часом створення; сторінки — через nextCursor.
Передайте nextCursor у параметр cursor, щоб отримати наступну сторінку; nextCursor = null ⇒ остання сторінка. Сторінки ніколи не повторюють і не пропускають замовлення, навіть якщо багато замовлень створено в одну секунду. Внутрішні статуси ніколи не виводяться (лише waiting_code, completed, cancelled і queued). Після перезапуску бота: GET /v1/orders?status=waiting_code&limit=200, ідіть за nextCursor, потім опитуйте ці замовлення через POST /v1/orders/status.
Параметри
НазваТипОбов'язковийОпис
statusstringНіЛише цей статус: waiting_code | completed | cancelled | queued (не вказано ⇒ усі)
sincenumberНіЛише замовлення, створені в цей unix-час (секунди) або пізніше
limitnumberНіЗамовлень на сторінці: 1–200 (за замовчуванням 50)
cursorstringНіnextCursor попередньої сторінки, без змін
Приклад
# Після перезапуску: зберіть усі замовлення, що ще чекають на код, сторінку за сторінкою
curl "https://onemail.wtf/v1/orders?status=waiting_code&limit=200" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": [
    {
      "orderId": "jkl012mno",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 1060,
      "otp": [],
      "codeDeadlineAt": 1753270001,
      "rentExpiresAt": 1753356401,
      "createdAt": 1753268201,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    },
    {
      "orderId": "abc123xyz",
      "service": "ig",
      "domain": "gmail.com",
      "email": "[email protected]",
      "status": "waiting_code",
      "price": 1060,
      "otp": [],
      "codeDeadlineAt": 1753270000,
      "rentExpiresAt": 1753356400,
      "createdAt": 1753268200,
      "warehouse": 1,
      "nextCodeFee": null,
      "listening": false,
      "listenUntil": null,
      "nextCodeBlocked": false,
      "nextCodeBlockReason": null
    }
  ],
  "nextCursor": "1753268200:abc123xyz"
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED

Склади

Кожен запис offers[] — це одна пропозиція = (сервіс, склад, тип скриньки). Перелічено лише склади, що зараз продають; склад, у якому тимчасово немає наявності, залишається в списку з stock = 0. Номери складів постійні: 1, 2, 3, 4: передавайте той самий номер у параметрі warehouse під час створення замовлення.
Наявним клієнтам нічого змінювати не потрібно. Якщо warehouse не вказано ⇒ поведінка як і раніше (склад 1: очікування 25 хв, додаткові коди надходять автоматично протягом 24-годинного строку замовлення, якщо сервіс надсилає більше одного); надішліть 0 ⇒ найдешевший склад із наявністю; надішліть 99 ⇒ автоматичний склад із переходом далі, коли склад вичерпується (див. одразу нижче); усі наявні поля залишаються як є, додаються лише нові поля (offers[], warehouse, nextCodeFee, listening, nextCodeBlocked…).
Автоматичний склад: warehouse = 99 (рекомендовано для сервісів, що часто вичерпуються)
Надішліть "warehouse": 99, і система орендує з найдешевшого складу з наявністю; якщо цей склад вичерпано або він дає збій, вона переходить до наступного в межах того самого виклику. Ідеально для сервісів, що часто вичерпуються, як-от Facebook та Instagram: вашому боту більше не потрібно читати offers[] і повторювати спроби склад за складом.
  • Порядок спроб: ціна від нижчої до вищої (напр. 1 500 → 1 600 → 1 700 VND); однакові ціни ⇒ спочатку склад із меншим номером.
  • Склади, що повідомляють про нульову наявність (stock = 0 в offers[]), ніколи не викликаються: час не витрачається.
  • Переходить далі, коли поточний склад вичерпано або він дає збій (OUT_OF_STOCK, NO_MAILS_AVAILABLE, WAREHOUSE_UNAVAILABLE, PROVIDER_ERROR).
  • Інші помилки повертаються одразу, без спроби наступного складу: INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED, QUANTITY_EXCEEDED, MAINTENANCE, SERVICE_DISABLED, DOMAIN_UNAVAILABLE…
  • quantity > 1: якщо першому складу не вистачає, решта береться з наступного — замовлення можуть охоплювати кілька складів; кожне замовлення містить warehouse і price складу, що його видав (і діють правила кодів цього складу).
  • Якщо перебрано всі склади й жодної скриньки орендувати не вдалося ⇒ ALL_WAREHOUSES_EXHAUSTED (HTTP 409, нічого не списано): спробуйте пізніше. Якщо орендовано лише частину скриньок, ви все одно отримаєте 200 з цими замовленнями.
Приклад: оренда Facebook Gmail із warehouse = 99
# warehouse: 99 — найдешевший склад із наявністю; немає наявності або збій ⇒ автоматично наступний склад
curl -X POST "https://onemail.wtf/v1/orders" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service":"fb","quantity":1,"domain":"gmail.com","warehouse":99}'
Поля offers[]
ПолеТипОпис
warehouse1 | 2 | 3 | 4Номер складу: 1, 2, 3 або 4.
domainstringТип скриньки пропозиції: gmail.com, icloud.com або gmx.com (додатковий домен: лише деякі сервіси, наразі Pokemon).
pricenumberЦіна однієї скриньки з цього складу (VND).
stocknumberЗалишок скриньок. 0 = немає в наявності: оренда зі складу 1 або 2 повертає WAREHOUSE_UNAVAILABLE; склад 4 усе одно пробується (його джерела часто видають пошту, хоча повідомляють 0) і повертає OUT_OF_STOCK, якщо нічого немає.
maxCodesnumber | nullМаксимум кодів, які може отримати одна скринька; null = без обмежень / невідомо (див. fee).
rulesobject | nullПравила вікна для складу 3 (windowMinutes, maxCodes, cancellable, refundOnTimeout, rerentRatio); null для складів 1, 2 і 4.
feeobject | nullВікно додаткових кодів: freeHours безкоштовних годин від оренди, далі кожне продовження коштує paidPct% ціни оренди, до maxHours годин від оренди (null = без обмежень). fee = null: плати немає — додаткові коди нічого не коштують протягом строку замовлення, якщо сервіс надсилає більше одного (до maxCodes), як на складі 1.
isDefaultbooleantrue для найдешевшого складу з наявністю (за однакових цін ⇒ менший номер складу): саме він використовується з warehouse = 0 і пробується першим з 99.
Правила за складами
ПравилоСклад 1Склад 2Склад 3Склад 4
Очікування першого коду25 хв20 хв25 хв ¹До 25 хв (у деяких джерел коротше: реальний крайній термін — codeDeadlineAt замовлення)
Немає кодуАвтоскасування, повернення 100%Автоскасування, повернення 100%Автоскасування, повернення 100% ¹Автоскасування, повернення 100%
Скасування до кодуТакТакТак ¹Так
Кодів на скринькуЗгідно з maxCodesБез обмеженьБез обмежень ¹Згідно з maxCodes (зазвичай null = без обмежень; 1 для деяких пропозицій)
Додаткові кодиБез додаткової плати протягом 24-годинного строку замовлення, якщо сервіс надсилає більше кодів; автоматично (додатковий виклик не потрібен). Скринька зазвичай залишається відкритою близько 25 хвилин після останнього коду.Безкоштовно fee.freeHours год (наразі Gmail 6 год, iCloud 12 год); далі кожне продовження коштує fee.paidPct% ціни через next-code, до fee.maxHours (Gmail 24 год, iCloud 10 днів)Без додаткової плати 24 години; далі орендуйте ту саму скриньку знову (rerent) за 50% ціни; з 2-ї повторної оренди (щонайменше через 20 год після попередньої) лише 25%Без додаткової плати протягом 24-годинного строку замовлення, як на складі 1: нові коди з'являються під час читання замовлення; next-code перечитує його одразу.
¹ Сервіси, що продаються лише з власного складу, як-от Cointiply (provider = "inventory", rules.cancellable = false), підпорядковуються rules: до rules.maxCodes листів протягом rules.windowMinutes хв, без скасування й без повернення коштів, якщо час минув без листа.
Склад 3 для Gmail (domain = gmail.com, rules.windowOnly = true): лише листи саме орендованого сервісу, надіслані після оренди. Перший код має прийти протягом rules.windowMinutes хв (до codeDeadlineAt); немає коду ⇒ автоскасування з поверненням 100 %; скасувати можна до першого коду. Після першого коду система перестає чекати, але замовлення лишається активним до rentExpiresAt: по наступний код викличте POST /v1/orders/{id}/next-code — безкоштовно до nextCodeFee.freeUntil (кожен виклик слухає rules.windowMinutes хв, listening = true, доки не прийде новий код); далі, до nextCodeFee.hardUntil, кожен виклик коштує nextCodeFee.feePriceVnd (надішліть confirmFee = true; якщо нового коду за цей раунд немає — повернення), як на складі 2. Після hardUntil ⇒ 409 hard_expired; пошта більше недоступна ⇒ 409 activation_gone (без оплати). Коли замовлення вийшло з активного списку, canRerent = true ⇒ POST /v1/orders/{id}/rerent знову орендує ту саму адресу за rerentPriceVnd. Сервіс Будь-який (ot): до перших rules.maxLetters листів після оренди (з'являються самі, без next-code); 0 листів ⇒ повернення 100 %.
nextCodeFee — плата за додаткові коди (замовлення складів 2 і 3)
Входить у GET /v1/orders/{id} та кожну відповідь із замовленням; null для замовлень складів 1 і 4 (додаткові коди безкоштовні). Склад 2: викликайте POST /v1/orders/{id}/next-code, коли потрібен ще один код: якщо feePriceVnd більше 0, потрібно надіслати confirmFee = true. Склад 3 (звичайні сервіси): коли безкоштовне вікно закінчилося, feePriceVnd — це ціна повторної оренди тієї самої скриньки (rerent).
ПолеТипОпис
feePriceVndnumberСума, що списується, якщо ви викличете next-code зараз; 0 = ще в межах безкоштовного вікна.
freeUntilnumber | nullКінець поточного безкоштовного вікна (unix-секунди).
hardUntilnumber | nullЖорсткий ліміт (unix-секунди): після цього часу кодів більше не буде.
paidPctnumber% ціни оренди, що стягується за кожне додаткове вікно.
freeHoursnumberБезкоштовні години одного вікна кодів (склад 2: Gmail 6, iCloud 12; склад 3: 24).
Приклад: отримати список складів, а потім орендувати з одного з них
# warehouse: 0 | 1–4 | 99 (необов'язково: якщо не вказувати, залишається склад 1, як раніше; 0 = найдешевший склад із наявністю; 99 = автоматично, переходить далі, коли склад вичерпується; див. offers[] у GET /v1/services)
curl -X POST "https://onemail.wtf/v1/orders" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"service":"dr","quantity":1,"domain":"gmail.com","warehouse":2}'
Приклад замовлення складу 2 (GET /v1/orders/{id})
{
  "success": true,
  "data": {
    "orderId": "ghi789rst",
    "service": "dr",
    "domain": "gmail.com",
    "email": "[email protected]",
    "status": "completed",
    "price": 350,
    "otp": [
      {
        "code": "482913",
        "receivedAt": 1753268300
      }
    ],
    "codeDeadlineAt": 1753269700,
    "rentExpiresAt": 1753354200,
    "createdAt": 1753267800,
    "warehouse": 2,
    "nextCodeFee": {
      "feePriceVnd": 175,
      "freeUntil": 1753289400,
      "hardUntil": 1753354200,
      "paidPct": 50,
      "freeHours": 6
    },
    "listening": false,
    "listenUntil": null,
    "nextCodeBlocked": false,
    "nextCodeBlockReason": null
  }
}

Масова оренда (партії)

Партії купуються на сайті (сторінка «Масова оренда»), а через API можна переглядати список партій і читати коди. Домен email визначає склад: Gmail = склад 1, iCloud = склад 3 (приватні скриньки).
  • Партія зберігається 24 год від купівлі: протягом цього часу читайте коди безкоштовно, без обмеження кількості кодів.
  • За скриньки, що не отримали код, кошти не повертаються; повертається (автоматично) лише нестача за кількістю.
  • Склад 1 (Gmail): кожна скринька має proxyUrl — GET повертає {"status":1,"code":"482913","all_codes":[...]} без ключа API (секретом є саме посилання: зберігайте його в таємниці). Ендпоінт кодів нижче також працює.
  • Склад 3 (iCloud): proxyUrl = null — читайте коди через ендпоінт нижче або відкрийте readUrl (вебсторінка). Кожна скринька закріплена за вашим акаунтом для цього сервісу; після закінчення терміну її все одно можна орендувати знову на сайті.
  • Листи без коду, який можна витягнути (вітальні листи, розсилки…), повертаються дослівно в code з isRaw: true (HTML або текст, до 20 000 символів).
Поля скриньки в партії (mails[])
ПолеТипОпис
idnumberID скриньки — параметр {mailId} ендпоінта кодів
emailstringАдреса email
urlstringСклад 1: = proxyUrl · склад 3: = readUrl (збережено для старіших скриптів / файлів експорту)
proxyUrlstring | nullСклад 1: посилання на код, що не потребує входу · склад 3: null
readUrlstringВебсторінка для читання кодів партії
codeCountnumberКількість отриманих кодів
lastCodestring | nullНайновіший код (необроблений лист: перші 300 символів; повний текст — в ендпоінті кодів)
lastIsRawbooleantrue = найновіший код є необробленим листом
checkedAtnumber | nullОстанній раз, коли система перевіряла постачальника щодо цієї скриньки (unix-секунди; null = ніколи)
GET/v1/batches
Ваші партії, найновіші першими (посторінково через page / pageSize, до 100). Кожна партія має warehouse (1 = Gmail, 3 = iCloud), status (active | expired | failed), expiresAt, codeCount і readUrl.
Параметри
НазваТипОбов'язковийОпис
pagenumberНіСторінка (за замовчуванням 1)
pageSizenumberНіПартій на сторінці (за замовчуванням 20, макс. 100)
Приклад
curl "https://onemail.wtf/v1/batches?page=1&pageSize=20" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "k3v9m2x7q1w8e5r4",
        "serviceCode": "lf",
        "serviceName": "Tiktok",
        "domain": "icloud.com",
        "warehouse": 3,
        "status": "active",
        "countRequested": 3,
        "countReceived": 3,
        "countDuplicate": 0,
        "countCharged": 3,
        "unitPriceVnd": 600,
        "quotedVnd": 1800,
        "chargedVnd": 1800,
        "refundVnd": 0,
        "holdHours": 24,
        "expiresAt": 1753354200,
        "createdAt": 1753267800,
        "readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
        "codeCount": 1,
        "rerentPriceVnd": null
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
Можливі помилки: UNAUTHORIZED
GET/v1/batches/{id}
Одна партія з її mails[]: візьміть id кожної скриньки, щоб прочитати її коди.
Партії Gmail (склад 1): proxyUrl кожної скриньки працює у ваших скриптах так само, як раніше. Партії iCloud (склад 3): proxyUrl = null, читайте коди через ендпоінт нижче. Прострочені партії iCloud містять rerentPriceVnd — ціну повторної оренди однієї скриньки окремо (здійснюється на сайті). Скринька, яку ви вже орендували повторно, може мати власну ціну в mails[].rerentPriceVnd (дешевше з 2-ї повторної оренди, щонайменше через 20 год після попередньої).
Параметри
НазваТипОбов'язковийОпис
idstringТакID партії (показано на сторінці «Масова оренда» та в readUrl)
Приклад
curl "https://onemail.wtf/v1/batches/BATCH_ID" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "id": "k3v9m2x7q1w8e5r4",
    "serviceCode": "lf",
    "serviceName": "Tiktok",
    "domain": "icloud.com",
    "warehouse": 3,
    "status": "active",
    "countRequested": 3,
    "countReceived": 3,
    "countDuplicate": 0,
    "countCharged": 3,
    "unitPriceVnd": 600,
    "quotedVnd": 1800,
    "chargedVnd": 1800,
    "refundVnd": 0,
    "holdHours": 24,
    "expiresAt": 1753354200,
    "createdAt": 1753267800,
    "readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
    "codeCount": 1,
    "rerentPriceVnd": null,
    "mails": [
      {
        "id": 812,
        "email": "[email protected]",
        "url": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
        "proxyUrl": null,
        "readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
        "fresh": true,
        "codeCount": 1,
        "lastCode": "482913",
        "lastCodeAt": 1753268500,
        "lastIsRaw": false,
        "checkedAt": 1753268507
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND
GET/v1/batches/{id}/mails/{mailId}/codes
Читає коди однієї скриньки партії: якщо настав час, система перевіряє постачальника, а потім повертає УСІ отримані коди, найстаріший першим — найновіший код останній у codes[].
Опитуйте кожні 5–10 секунд під час очікування (частіші виклики просто повертають збережені дані — polledAt не змінюється). Листи без коду, який можна витягнути, повертаються дослівно в code з isRaw: true. Прострочені партії й далі повертають збережені коди, але більше не перевіряються.
Параметри
НазваТипОбов'язковийОпис
idstringТакID партії
mailIdnumberТакID скриньки (mails[].id)
poll0 | 1Ні0 = лише читати збережені коди, не перевіряти постачальника (за замовчуванням 1)
Приклад
# Викликайте знову кожні 5–10 секунд під час очікування; найновіший код останній у codes[]
curl "https://onemail.wtf/v1/batches/BATCH_ID/mails/MAIL_ID/codes" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "mailId": 812,
    "codes": [
      {
        "code": "482913",
        "receivedAt": 1753268500,
        "isRaw": false
      }
    ],
    "polledAt": 1753268507,
    "mail": {
      "id": 812,
      "email": "[email protected]",
      "url": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
      "proxyUrl": null,
      "readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
      "fresh": true,
      "codeCount": 1,
      "lastCode": "482913",
      "lastCodeAt": 1753268500,
      "lastIsRaw": false,
      "checkedAt": 1753268507
    }
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, RATE_LIMITED

Buy live Gmail accounts (3 warehouses)

Buy short-lived Gmail accounts outright: you are charged when you order and the accounts arrive within seconds. There are three mail-shop warehouses (numbered separately from the OTP-rental warehouses 1–4), each with ONE price for any quantity. Prices returned by the API are YOUR account's prices (custom price if the admin set one) — exactly what you are charged.
Warehouses
WarehouseEach account deliversDefault priceStock
1gm_cookieemail · password · cookies · inboxUrl (inbox link) · inboxJsonUrl (emails as JSON) · loginUrl (quick sign-in link) · liveUrl (live-check link — Alive / Dead) · twoFaUrl (2FA link — just the 6 digits)3,300 VNDA number — published by the source, refreshed every minute. The source checks that accounts are live at purchase time, so you may get fewer — the shortfall is refunded (a partial order; warehouse 99: the rest goes to the next warehouse)
2gm_loginemail · password · loginUrl (quick login link — open it in a desktop browser) · otpUrl (Vinted OTP link — when delivers lists it)6,000 VNDA REFERENCE number from a source sharing the same stock (refreshed every minute; null when it cannot be read) — may be off by a few, never blocks a purchase; a shortfall becomes a partial order with the rest refunded
3gm_2faemail · password · recovery (recovery email — null when the source has none) · twofa (the 2FA KEY — 2FA is on) · twoFaUrl (2FA link — just the 6 digits) · cookies · loginUrl (quick sign-in link) · inboxUrl · inboxJsonUrl · liveUrl. Copy line / rawLine / .txt file: 7 cells joined by ---- (section below). NOT part of warehouse 99 — send warehouse: 33,300 VNDA number — published by the source, refreshed every minute (as warehouse 1). A shortfall becomes a partial order with the rest refunded
…Warehouses added later — see products[] (warehouse, code, delivers). A warehouse delivering a quick sign-in link + cookies: email · password · loginUrl (paste it into a browser to land straight in Gmail) · cookies · inboxUrl · inboxJsonUrl · liveUrl — the rawLine / .txt line has 5 ---- cells (section below)products[].priceVndSee products[].stock (published by the source — as warehouse 1). A shortfall becomes a partial order with the rest refunded
99As the warehouse that supplied each account (items[].warehouse)Price of the cheapest warehouse on sale (auto.priceVnd)Warehouses 1 / 2 only. Buys the cheapest warehouse first (auto.order); if it runs out midway the rest goes to the next warehouse at that warehouse's price (the difference is charged — refunded instead if your balance is short); every warehouse out ⇒ MAILSHOP_OUT_OF_STOCK, nothing charged
Вхід в акаунти складу 1 (без резервної пошти)
  • Акаунти складу 1 (gm_cookie) надходять без резервної пошти — ви отримуєте email, пароль, cookies і посилання на скриньку (inboxUrl / inboxJsonUrl), і більше нічого.
  • Рекомендований спосіб входу — імпорт cookies (cookies, JSON) у браузер: розширенням для імпорту cookies або через імпорт cookies у вашому антидетект-браузері, — а потім відкрийте Gmail: сесія вже авторизована, зазвичай без запиту пароля й без перевірки.
  • Потрібні лише коди чи листи? Читайте їх за inboxUrl (вебсторінка) або inboxJsonUrl (JSON) — без API-ключа й без входу в Google.
  • Вхід за паролем з нового пристрою чи IP може спричинити перевірку Google (резервна пошта, телефон або код) — цим акаунтам нічим її пройти, тож користуйтеся cookies або посиланням на скриньку.
  • Перепродаєте? Віддавайте своїм клієнтам cookies і посилання на скриньку — у .txt-вивантаженні (GET /v1/mail-shop/orders/{id}/download) усе це є одним рядком: email|password|cookies|inboxUrl — і попереджайте, що входити треба через cookies, а не за паролем.
  • Акаунти складу 2 (gm_login) натомість надходять із посиланням для швидкого входу (loginUrl) — відкрийте його в браузері на комп'ютері, щоб увійти.
  • На акаунтах складу 3 (gm_2fa) увімкнено 2FA: входьте за email + паролем + 6-значним кодом із ключа twofa (додайте його в Google Authenticator / TOTP-застосунок) або з twoFaUrl — так можна увійти й з телефона; на комп'ютері також можна імпортувати cookies / відкрити loginUrl, як на складі 1.
3 steps
  1. See warehouses & prices: GET /v1/mail-shop/products ⇒ products[] (per warehouse: priceVnd, stock, available, maxQty) + auto (warehouse 99: order, priceVnd). To see the total first, call GET /v1/mail-shop/quote.
  2. Buy: POST /v1/mail-shop/orders with {"warehouse": 1 | 2 | 3 | 99, "quantity": N} + header Idempotency-Key (a new UUID per purchase). The response is the order, usually already completed with items[].
  3. Get the accounts: read items[] (table below) or download the TXT GET /v1/mail-shop/orders/{id}/download. status = pending ⇒ poll GET /v1/mail-shop/orders/{id} every 5 seconds until completed / partial / failed.
# 1) warehouses, your prices, stock
curl "https://onemail.wtf/v1/mail-shop/products" -H "Authorization: Bearer og_xxx..."

# 2) buy (a warehouse from products[] or 99) — a NEW Idempotency-Key per purchase
curl -X POST "https://onemail.wtf/v1/mail-shop/orders" \
  -H "Authorization: Bearer og_xxx..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" --max-time 60 \
  -d '{"warehouse":99,"quantity":2}'

# 3) status "pending"? read the order again (or download the .txt)
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID" -H "Authorization: Bearer og_xxx..."
Fields of an account (items[])
ПолеТипОпис
lineNonumberPosition in the order (1, 2, …) — the {lineNo} of the inbox endpoints
warehousenumberWarehouse that supplied this account (1 · 2 · 3 · warehouses added later)
emailstringGmail address
passwordstringPassword
recoverystring?Recovery email — only when the source provides one (warehouse 1 with cookies has NONE — sign in with the cookies, see the sign-in notes above; warehouse 1 with a login link / warehouse 3: when the source provides it)
twofastring | nullWarehouse 3: the account's 2FA KEY (TOTP base32, upper case — add it to Google Authenticator / any TOTP app: SHA1 · 30 seconds · 6 digits) to get the code yourself at a password sign-in (on a phone too). null = the source gave no key (the code is still available via twoFaUrl). Warehouses 1 / 2 do not have this field
cookiesstring | nullWarehouse 1 / 3: login cookies (JSON) while the shop delivers cookies (the warehouse's delivers lists "cookies"); null while warehouse 1 delivers the source's login link instead of cookies
inboxUrlstring | nullWarehouse 1 / 3: inbox page without an API key (https://onemail.wtf/mail/{code}); null = link turned off
inboxJsonUrlstring | nullWarehouse 1 / 3: the same link + ?json ⇒ emails as JSON (section below)
twoFaUrlstring | nullWarehouse 1 / 3: the 2FA LINK (https://onemail.wtf/2fa/{code} — same code + expiry as inboxUrl): GET / open it in a browser ⇒ JUST the 6-digit 2FA code (section below). null = link turned off. The .txt file has this column when downloaded with ?twofa=1
inboxLinkExpiresAtnumber | nullWarehouse 1 / 3: when the link expires (unix seconds); null = no limit
loginUrlstring | nullThe QUICK SIGN-IN link — open it in a browser ⇒ sign in straight to the account. Warehouse 1 with cookies (31/10/2026) and warehouse 3: https://onemail.wtf/login/{code} (same code + expiry as inboxUrl; uses the cookies — null when the link is off / expired). Warehouse 1 with the source's login link (03/11/2026, accounts without cookies) and warehouse 2: the account sign-in link (no expiry; null when the source gave no link). The warehouse-1 .txt file has this column when downloaded with ?login=1, and BY DEFAULT when the order has warehouse-1 accounts with a source login link
liveUrlstring | nullWarehouse 1 / 3: the LIVE-CHECK link (https://onemail.wtf/live/{code} — same code + expiry as inboxUrl): open it in a browser ⇒ a light Alive / Dead page (the server asks the source whether the account is still alive); GET {liveUrl}?json ⇒ {alive, note} (section below). null = link off / expired
otpUrlstring | nullWarehouse 2: the account's Vinted OTP link — open it in a browser to see the code, ?json ⇒ JSON (section below). null = this account has no link
otpService"vinted" | nullWarehouse 2: the service of otpUrl
rawLinestringThe whole account on one line (cookies compacted) — copy it as is. Warehouse 3: ALWAYS 7 cells joined by ----, an empty cell is no: email----password----recovery----twofa----cookies----liveUrl----inboxUrl, a link in the line always ends with / (section below). A quick-sign-in-link + cookies warehouse: ALWAYS 5 cells email----password----recovery----loginUrl----cookies (section below)
Warehouse 3 — 2FA key + the 7-cell line (rawLine / .txt)
Every warehouse-3 account (gm_2fa) has 2FA on: twofa is the 2FA KEY (TOTP base32) — add it to Google Authenticator / any TOTP app (SHA1 · 30 seconds · 6 digits) to sign in with email + password + the 6-digit code, on a phone too; or get the code via twoFaUrl / GET /v1/mail-shop/orders/{id}/items/{lineNo}/2fa. It also has cookies + loginUrl (quick desktop sign-in with the extension, as warehouse 1), inboxUrl / inboxJsonUrl, liveUrl. The rawLine and every line of the .txt file: split on ----, an empty cell is no, ALWAYS 7 cells in the order email----password----recovery----twofa----cookies----liveUrl----inboxUrl (cookies is one-line JSON that may contain | but never ----; an expired / disabled link ⇒ no). A link in the line (liveUrl, inboxUrl) always ends with / — a link code may end with -, the / keeps it from merging into ----; the link works the same with the trailing / ({link}?json too), the JSON fields liveUrl / inboxUrl have no trailing /. Warehouse 3 is NOT part of warehouse 99 — buy it with {"warehouse": 3} or {"product": "gm_2fa"}.
{
  "lineNo": 1,
  "warehouse": 3,
  "email": "[email protected]",
  "password": "Zt4!wQ8m",
  "recovery": "[email protected]",
  "twofa": "K7QW3NXRB2YJ5MPTLZ4VDF6HCASA2EGU",
  "cookies": "[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000|q7…\"}]",
  "inboxUrl": "https://onemail.wtf/mail/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2",
  "inboxJsonUrl": "https://onemail.wtf/mail/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2?json",
  "loginUrl": "https://onemail.wtf/login/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2",
  "liveUrl": "https://onemail.wtf/live/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2",
  "twoFaUrl": "https://onemail.wtf/2fa/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2",
  "inboxLinkExpiresAt": 1762592400,
  "rawLine": "[email protected]!wQ8m----backup.mno91@example.com----K7QW3NXRB2YJ5MPTLZ4VDF6HCASA2EGU----[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000|q7…\"}]----https://onemail.wtf/live/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2/----https://onemail.wtf/mail/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2/"
}
email----password----recovery----twofa----cookies----liveUrl----inboxUrl
[email protected]!wQ8m----backup.mno91@example.com----K7QW3NXRB2YJ5MPTLZ4VDF6HCASA2EGU----[{"domain":".google.com","name":"SID","value":"g.a000|q7…"}]----https://onemail.wtf/live/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2/----https://onemail.wtf/mail/Wd3Lm8Qz5Rt1Ky7Pn4Xv9Bc2/
[email protected]!pL2d----no----no----[{"domain":".google.com","name":"SID","value":"g.a000|z1…"}]----https://onemail.wtf/live/Jr8Ns2Vb6Cx4Mq1Tz9Lk5Hw3/----https://onemail.wtf/mail/Jr8Ns2Vb6Cx4Mq1Tz9Lk5Hw3/
Quick-sign-in-link + cookies warehouses — the 5-cell line (rawLine / .txt)
A warehouse whose delivers lists both loginUrl and cookies (no twofa) gives two ways to sign in: loginUrl = the QUICK SIGN-IN link (https://onemail.wtf/api/mail-shop/login/{code}/ — paste it into a browser to land straight in Gmail, no API key, no expiry; the account may live only a short while after a link sign-in — read the warehouse's description / terms) and cookies (import them with a cookie extension — longer to set up). It also has inboxUrl / inboxJsonUrl (read the emails as for warehouse 1) and liveUrl; no recovery email (recovery only when the source gives one) and no 2FA. The rawLine and every line of the .txt file: ALWAYS 5 cells joined by ----, an empty cell is no: email----password----recovery----loginUrl----cookies — the FIRST 4 cells match the warehouse-2 line (email----password----no----loginUrl: tools that already split warehouse 2 keep working), cell 5 is the cookies as one-line JSON (may contain | and -). Split: the first 4 cells at the FIRST 4 ----, the rest is the cookies. The .txt file: first line email----password----recovery----loginUrl----cookies; the otp / twofa / login options do not apply.
{
  "lineNo": 1,
  "warehouse": 4,
  "email": "[email protected]",
  "password": "Rb5!tK9w",
  "cookies": "[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000|k2…\"}]",
  "inboxUrl": "https://onemail.wtf/mail/Hn4Bv7Lc2Qx9Mz5Tr8Wy3Kd6",
  "inboxJsonUrl": "https://onemail.wtf/mail/Hn4Bv7Lc2Qx9Mz5Tr8Wy3Kd6?json",
  "loginUrl": "https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.1.Xc8Lq2Vn7Tb4Rz1Mk6Hy9w/",
  "liveUrl": "https://onemail.wtf/live/Hn4Bv7Lc2Qx9Mz5Tr8Wy3Kd6",
  "inboxLinkExpiresAt": 1762592400,
  "rawLine": "[email protected]!tK9w----no----https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.1.Xc8Lq2Vn7Tb4Rz1Mk6Hy9w/----[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000|k2…\"}]"
}
email----password----recovery----loginUrl----cookies
[email protected]!tK9w----no----https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.1.Xc8Lq2Vn7Tb4Rz1Mk6Hy9w/----[{"domain":".google.com","name":"SID","value":"g.a000|k2…"}]
[email protected]!mJ6v----no----https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Tg5Ns1Kx8Pb3Lw7Qz2Vm4c/----[{"domain":".google.com","name":"SID","value":"g.a000|p7…"}]
Read the inbox as JSON (inboxJsonUrl)
GET {inboxJsonUrl} (= inboxUrl + ?json) returns the same JSON as GET /api/mailbox/{code}: email, letters[] (≤ max latest emails: from, subject, receivedAt, code — extracted code / link, content — sanitized HTML), total, etag, nextAt. No API key needed (the code in the link is the key — keep it private), CORS is open. Add &max=20|50|100|200 for more emails (default 10), &etag={previous etag} ⇒ unchanged emails come back as empty letters + unchanged: true. Reading one link faster than every 10 seconds ⇒ 429 (retryAfter); link off / wrong / expired ⇒ 404; account locked ⇒ 410.
curl "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d?json&max=20"
{
  "success": true,
  "data": {
    "email": "[email protected]",
    "letters": [
      {
        "key": "h:9f2c4e1a7b3d5c80",
        "from": "Instagram [email protected]",
        "subject": "350038 is your Instagram code",
        "receivedAt": 1760000520,
        "code": "350038",
        "content": "<html><body><p>Enter this confirmation code in the app: 350038</p></body></html>"
      }
    ],
    "max": 10,
    "total": 8,
    "fetchedAt": 1760000530,
    "cached": false,
    "etag": "f1c2a9d4e0b37a65",
    "unchanged": false,
    "nextAt": 1760000540,
    "expiresAt": 1762592400,
    "serverTime": 1760000530
  }
}
Read the Vinted OTP code (otpUrl)
A warehouse-2 account with otpUrl ⇒ open it in a browser to see the latest Vinted code (the page refreshes itself); GET {otpUrl}?json returns {status, code, service, email, checkedAt, retryAfter}: status = waiting (no code yet — ask again after retryAfter seconds) · ok (code = the latest code) · dead (codes can no longer be read for this account) · error (temporarily unreadable — ask again). No API key needed (the code in the link is the key — keep it private), CORS is open; the server reads the source at most every few seconds per account; more than 120 calls / minute / IP ⇒ 429.
curl "https://onemail.wtf/api/mail-shop/otp/p3x9k2m7q1w8e5r4.2.Zx8Kq2Lm4Np6Rt0Vw3Yb5c?json"
{
  "success": true,
  "data": {
    "status": "ok",
    "code": "4829",
    "service": "vinted",
    "email": "[email protected]",
    "checkedAt": 1760000530,
    "retryAfter": 5
  }
}
The 2FA code (twoFaUrl)
Some warehouse-1 accounts have 2-step verification (2FA) on — a password sign-in makes Google ask for a 6-digit code. GET {twoFaUrl} (or open it in a browser) returns text/plain with JUST the current 6 digits (no newline), a Refresh header = seconds until the next code + 1 (browsers reload by themselves), Cache-Control: no-store, open CORS — you can hand the link to your customers. Account without 2FA ⇒ 404 no 2fa; wrong / off / expired link ⇒ 404 not found; locked account ⇒ 410 gone; too fast / source hiccup ⇒ 429 / 502 retry (Retry-After header). With an API key: GET /v1/mail-shop/orders/{id}/items/{lineNo}/2fa ⇒ {none, code, expiresIn}. The server caches the code until it expires. The .txt file (GET /v1/mail-shop/orders/{id}/download): add ?twofa=1 ⇒ a last twoFaUrl column (off by default — the old layout is unchanged).
curl "https://onemail.wtf/2fa/Q7xK2mP9vL4tR8wN3cB6yH1d"
# 424819
Check that an account is alive (liveUrl)
Every warehouse-1 account has a liveUrl (https://onemail.wtf/live/{code} — same code + expiry as inboxUrl: regenerating / turning off the inbox link changes / turns off this link too). Open it in a browser ⇒ a light Alive / Dead page (English by default, ?lang=vi ⇒ Vietnamese). GET {liveUrl}?json returns {alive, note}: alive = true (alive, can receive mail) / false (no longer accessible); note = a short explanation. The server asks the source for you and caches the result (alive: 1 minute; dead: 5 minutes) — repeated calls for the same account do not hit the source again. No API key needed (the code in the link is the key — keep it private), CORS is open — you can hand the link to your customers. Wrong / off / expired link ⇒ 404; not a warehouse-1 account ⇒ 409; too fast ⇒ 429 (Retry-After); source hiccup ⇒ 502 (ask again later). The .txt file has NO such column.
curl "https://onemail.wtf/live/Q7xK2mP9vL4tR8wN3cB6yH1d?json"
{
  "success": true,
  "data": {
    "alive": true,
    "note": "The account is active and can receive mail."
  }
}
Order statuses
СтатусОпис
pendingBeing delivered — accounts that arrived are in items[]; poll again in 5 seconds
completedFully delivered. Final.
partialDelivered short — the shortfall was refunded (refundVnd; message = the reason + the source's own words when it gave any). Final.
failedNothing delivered — fully refunded (message as above). Final.
refundedRefunded by an admin (refundVnd). Final.
Rules
  • Money: chargedVnd = Σ route[].quantity × unitPriceVnd (a 99 order split across warehouses ⇒ two legs in route). Shortfalls are refunded automatically (refundVnd). Delivered accounts are not refunded — the only warranty is the warehouse's terms (read them first).
  • Idempotency-Key is required (400 without it): retrying with the SAME key after a timeout returns the same order and charges nothing more; a new key buys again. Use a client timeout of at least 60 seconds.
  • Limits: at most 500 accounts per order (and the warehouse's maxQty), 600 purchases per minute for your account (web + API share it), 1800 inbox reads per hour. Above ⇒ 429 RATE_LIMITED.
  • Common errors: MAILSHOP_OUT_OF_STOCK 409 (details.stock = how many you can buy now) · MAILSHOP_QTY_LIMIT 400 (details.max) · INSUFFICIENT_BALANCE 402 · MAILSHOP_DISABLED 503 (warehouse / section paused) · MAILSHOP_SUPPLIER_ERROR 502 (the source refused at once — a failed order was recorded and refunded, details.orderId) · VALIDATION_ERROR 400 (warehouse not 1 | 2 | 3 | 99, warehouse and product disagree, missing Idempotency-Key…).
  • Terms (warranty only for the first sign-in within 2 hours, accounts last ~6–24 hours) are in each warehouse's terms; the API does not ask you to accept them (the web asks once). API orders show up in your web history (channel = api) and vice versa.
GET/v1/mail-shop/products
The mail-shop warehouses + automatic warehouse 99. products[]: warehouse (the number to use in quote / orders), code (product code, e.g. gm_cookie), delivers (fields of every account — read this, do not infer from the number), priceVnd (YOUR price), listPriceVnd (list price), stock, available, maxQty (most one order can take now). auto: order (the warehouses 99 buys from, in order), priceVnd (cheapest warehouse), available. New warehouses may be added; a warehouse that is not open yet is absent from products[].
Warehouse 1 / 3 stock = what the source publishes (refreshed every minute; the source checks accounts are live at purchase time, so you may get fewer — the shortfall is refunded). Warehouse 2 = a reference number from a source sharing the same stock, may be off by a few (null = could not be read — just buy); a shortfall becomes a partial order with the rest refunded. available = false ⇒ do not buy from that warehouse (out of stock / paused). Prices can change — read the catalog again before a large purchase.
Приклад
curl "https://onemail.wtf/v1/mail-shop/products" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "products": [
      {
        "warehouse": 1,
        "code": "gm_cookie",
        "name": "Short-lived live Gmail — with cookies + inbox link",
        "description": "Short-lived personal Gmail account. You get the email · password · login cookies · an inbox link (add ?json to read the emails as JSON) · a quick login link.",
        "terms": "• Warranty covers ONLY the first successful sign-in, within 2 hours of purchase.\n• These Gmail accounts typically last 6–24 hours: use them right after purchase.",
        "delivers": [
          "email",
          "password",
          "cookies",
          "inboxUrl",
          "inboxJsonUrl",
          "loginUrl"
        ],
        "priceVnd": 3300,
        "listPriceVnd": 3300,
        "stock": 1840,
        "available": true,
        "maxQty": 500
      },
      {
        "warehouse": 2,
        "code": "gm_login",
        "name": "Short-lived live Gmail — with a quick login link",
        "description": "Short-lived personal Gmail account that has been used on a few services. You get the email · password · a quick login link.",
        "terms": "• Warranty covers ONLY the first successful sign-in, within 2 hours of purchase.\n• Sign in with the link in a DESKTOP BROWSER.",
        "delivers": [
          "email",
          "password",
          "loginUrl"
        ],
        "priceVnd": 6000,
        "listPriceVnd": 6000,
        "stock": 141,
        "available": true,
        "maxQty": 100
      },
      {
        "warehouse": 3,
        "code": "gm_2fa",
        "name": "Short-lived live Gmail — with 2FA key + cookies",
        "description": "Short-lived personal Gmail account with 2FA ENABLED — you can sign in on a phone too. You get the email · password · recovery email (if any) · the 2FA key + a 2FA code link · login cookies · an inbox link · an account live-check link.",
        "terms": "• Warranty covers ONLY the first successful sign-in, within 2 hours of purchase.\n• These Gmail accounts typically last 6–24 hours: use them right after purchase.",
        "delivers": [
          "email",
          "password",
          "recovery",
          "twofa",
          "twoFaUrl",
          "cookies",
          "loginUrl",
          "inboxUrl",
          "inboxJsonUrl",
          "liveUrl"
        ],
        "priceVnd": 3300,
        "listPriceVnd": 3300,
        "stock": 920,
        "available": true,
        "maxQty": 500
      }
    ],
    "auto": {
      "warehouse": 99,
      "priceVnd": 3300,
      "available": true,
      "order": [
        1,
        2
      ]
    }
  }
}
Можливі помилки: UNAUTHORIZED
GET/v1/mail-shop/quote
Call quote to see the total first (nothing is reserved). Warehouse 99 ⇒ route[] = planned split by known stock; available = false ⇒ that quantity cannot be bought right now.
Параметри
НазваТипОбов'язковийОпис
warehousenumberНіMail-shop warehouse = a `warehouse` number from products[] of GET /v1/mail-shop/products (each lists its fields in `delivers`; warehouses can be added — do not assume only 1 / 2 / 3), or 99 = automatic, cheapest first among the warehouses in auto.order. Send warehouse OR product
productstringНіInstead of warehouse: the `code` of a warehouse in GET /v1/mail-shop/products (e.g. gm_cookie, gm_login, gm_2fa)
quantitynumberНіNumber of accounts (default 1)
Приклад
curl "https://onemail.wtf/v1/mail-shop/quote?warehouse=99&quantity=10" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "warehouse": 99,
    "quantity": 10,
    "unitPriceVnd": 3300,
    "totalVnd": 38400,
    "available": true,
    "stock": null,
    "maxQty": 500,
    "route": [
      {
        "warehouse": 1,
        "quantity": 8,
        "unitPriceVnd": 3300
      },
      {
        "warehouse": 2,
        "quantity": 2,
        "unitPriceVnd": 6000
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, MAILSHOP_PRODUCT_NOT_FOUND
POST/v1/mail-shop/orders
Buy: you are charged at once, then the system buys from the source and delivers. The response is the order — usually already completed with items[]; status = pending ⇒ poll GET /v1/mail-shop/orders/{id} every 5 seconds. The call waits up to about 16 seconds for the delivery.
Idempotency-Key is required (400 without it). Not enough stock ⇒ MAILSHOP_OUT_OF_STOCK (error.details.stock = how many you can buy now, nothing charged); over the per-order limit ⇒ MAILSHOP_QTY_LIMIT (error.details.max). 502 MAILSHOP_SUPPLIER_ERROR = the source refused at once: a failed order was recorded and fully refunded (error.details.orderId) — retry with a new key.
Параметри
НазваТипОбов'язковийОпис
warehousenumberНіMail-shop warehouse = a `warehouse` number from products[] of GET /v1/mail-shop/products (each lists its fields in `delivers`; warehouses can be added — do not assume only 1 / 2 / 3), or 99 = automatic, cheapest first among the warehouses in auto.order. Send warehouse OR product
productstringНіInstead of warehouse: the `code` of a warehouse in GET /v1/mail-shop/products (e.g. gm_cookie, gm_login, gm_2fa)
quantitynumberНіNumber of accounts (default 1)
Idempotency-KeystringТакHeader: a new UUID for every new purchase — reuse it only to retry that same purchase
Приклад
# Idempotency-Key обов'язковий: новий UUID на кожну купівлю; використовуйте той самий ключ повторно лише для повторної спроби після тайм-ауту
# warehouse: a number from GET /v1/mail-shop/products (its "delivers" lists the fields) · 99 = cheapest first
curl -X POST "https://onemail.wtf/v1/mail-shop/orders" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 60 \
  -d '{"warehouse":99,"quantity":5}'
Приклад відповіді
{
  "success": true,
  "data": {
    "id": "p3x9k2m7q1w8e5r4",
    "requestedWarehouse": 99,
    "warehouse": 1,
    "productCode": "gm_cookie",
    "quantity": 2,
    "deliveredCount": 2,
    "unitPriceVnd": 3300,
    "chargedVnd": 9300,
    "refundVnd": 0,
    "status": "completed",
    "channel": "api",
    "route": [
      {
        "warehouse": 1,
        "quantity": 1,
        "unitPriceVnd": 3300
      },
      {
        "warehouse": 2,
        "quantity": 1,
        "unitPriceVnd": 6000
      }
    ],
    "message": null,
    "createdAt": 1760000400,
    "completedAt": 1760000409,
    "items": [
      {
        "lineNo": 1,
        "warehouse": 1,
        "email": "[email protected]",
        "password": "Pw7Xq!k3d",
        "rawLine": "[email protected]|Pw7Xq!k3d||[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000…\"}]",
        "cookies": "[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000…\"}]",
        "inboxUrl": "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "inboxJsonUrl": "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d?json",
        "loginUrl": "https://onemail.wtf/login/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "liveUrl": "https://onemail.wtf/live/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "twoFaUrl": "https://onemail.wtf/2fa/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "inboxLinkExpiresAt": 1762592400
      },
      {
        "lineNo": 2,
        "warehouse": 2,
        "email": "[email protected]",
        "password": "Qp9!rT2",
        "rawLine": "[email protected]!rT2----no----https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Fk3Wq8Ln5Tz1Vb7Mc4Rx6y",
        "loginUrl": "https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Fk3Wq8Ln5Tz1Vb7Mc4Rx6y",
        "otpUrl": "https://onemail.wtf/api/mail-shop/otp/p3x9k2m7q1w8e5r4.2.Zx8Kq2Lm4Np6Rt0Vw3Yb5c",
        "otpService": "vinted"
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, MAILSHOP_PRODUCT_NOT_FOUND, MAILSHOP_DISABLED, MAILSHOP_QTY_LIMIT, MAILSHOP_OUT_OF_STOCK, INSUFFICIENT_BALANCE, MAILSHOP_SUPPLIER_ERROR, RATE_LIMITED, DUPLICATE_REQUEST, MAINTENANCE
GET/v1/mail-shop/orders
Your mail-shop orders, newest first (page / pageSize, up to 100 per page) — without items[]: fetch an order to get its accounts. Orders bought on the web are listed too (channel = web).
Параметри
НазваТипОбов'язковийОпис
pagenumberНіPage (default 1)
pageSizenumberНіOrders per page (default 20, max 100)
Приклад
curl "https://onemail.wtf/v1/mail-shop/orders?page=1&pageSize=20" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "p3x9k2m7q1w8e5r4",
        "requestedWarehouse": 99,
        "warehouse": 1,
        "productCode": "gm_cookie",
        "quantity": 2,
        "deliveredCount": 2,
        "unitPriceVnd": 3300,
        "chargedVnd": 9300,
        "refundVnd": 0,
        "status": "completed",
        "channel": "api",
        "route": [
          {
            "warehouse": 1,
            "quantity": 1,
            "unitPriceVnd": 3300
          },
          {
            "warehouse": 2,
            "quantity": 1,
            "unitPriceVnd": 6000
          }
        ],
        "message": null,
        "createdAt": 1760000400,
        "completedAt": 1760000409
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
Можливі помилки: UNAUTHORIZED
GET/v1/mail-shop/orders/{id}
One order with every account delivered so far (an order still delivering already shows what has arrived). route[] = which warehouse, how many, at what price.
Poll every 5 seconds while status = pending; completed / partial / failed / refunded are final. An order of many warehouse-1 accounts (cookies) can weigh several MB — stop polling once it is final.
Параметри
НазваТипОбов'язковийОпис
idstringТакOrder ID (data.id returned by the purchase)
Приклад
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "id": "p3x9k2m7q1w8e5r4",
    "requestedWarehouse": 99,
    "warehouse": 1,
    "productCode": "gm_cookie",
    "quantity": 2,
    "deliveredCount": 2,
    "unitPriceVnd": 3300,
    "chargedVnd": 9300,
    "refundVnd": 0,
    "status": "completed",
    "channel": "api",
    "route": [
      {
        "warehouse": 1,
        "quantity": 1,
        "unitPriceVnd": 3300
      },
      {
        "warehouse": 2,
        "quantity": 1,
        "unitPriceVnd": 6000
      }
    ],
    "message": null,
    "createdAt": 1760000400,
    "completedAt": 1760000409,
    "items": [
      {
        "lineNo": 1,
        "warehouse": 1,
        "email": "[email protected]",
        "password": "Pw7Xq!k3d",
        "rawLine": "[email protected]|Pw7Xq!k3d||[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000…\"}]",
        "cookies": "[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000…\"}]",
        "inboxUrl": "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "inboxJsonUrl": "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d?json",
        "loginUrl": "https://onemail.wtf/login/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "liveUrl": "https://onemail.wtf/live/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "twoFaUrl": "https://onemail.wtf/2fa/Q7xK2mP9vL4tR8wN3cB6yH1d",
        "inboxLinkExpiresAt": 1762592400
      },
      {
        "lineNo": 2,
        "warehouse": 2,
        "email": "[email protected]",
        "password": "Qp9!rT2",
        "rawLine": "[email protected]!rT2----no----https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Fk3Wq8Ln5Tz1Vb7Mc4Rx6y",
        "loginUrl": "https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Fk3Wq8Ln5Tz1Vb7Mc4Rx6y",
        "otpUrl": "https://onemail.wtf/api/mail-shop/otp/p3x9k2m7q1w8e5r4.2.Zx8Kq2Lm4Np6Rt0Vw3Yb5c",
        "otpService": "vinted"
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND
GET/v1/mail-shop/orders/{id}/download
The delivered accounts as .txt (text/plain), separated by |. The FIRST LINE is the column header: warehouse 1 email|password|cookies|inboxUrl · warehouse 2 email|password|loginUrl · a 99 order with both warehouses ⇒ email|password|cookies|inboxUrl|loginUrl (missing cells empty).
cookies is one-line JSON and may contain | — split email and password at the first two |, the link at the last | (with extra columns ⇒ the links after cookies at the last | separators — links never contain |; read the header line for their order). Nothing delivered yet ⇒ 409 VALIDATION_ERROR. Add <c>?otp=1</c> ⇒ warehouse 2 gets a LAST column <c>otpUrl</c> (the Vinted OTP link — empty when the account has none): email|password|loginUrl|otpUrl. Without it ⇒ exactly the columns above. Add <c>?twofa=1</c> ⇒ warehouse 1 gets a LAST column <c>twoFaUrl</c> (the 2FA link — same code as inboxUrl; GET ⇒ just the 6 digits; empty when the link is off / expired): email|password|cookies|inboxUrl|twoFaUrl. Combines with <c>otp=1</c> — fixed column order: …|loginUrl|otpUrl|twoFaUrl (a 99 order with both warehouses). Without it ⇒ the default layout above. Add <c>?login=1</c> ⇒ warehouse 1 gets a <c>loginUrl</c> column (the QUICK SIGN-IN link — same code as inboxUrl; open it ⇒ sign in straight to the account; empty when the link is off / expired): email|password|cookies|inboxUrl|loginUrl. The loginUrl column comes BEFORE twoFaUrl when combined with <c>?twofa=1</c>. Without it ⇒ the default layout above. WAREHOUSE 3 (gm_2fa) has its OWN layout, separated by <c>----</c> (cookies may contain |): the first line is <c>email----password----recovery----twofa----cookies----liveUrl----inboxUrl</c>, every account is ALWAYS 7 cells in that order, an empty cell reads <c>no</c> (an expired / disabled link too), a link always ends with <c>/</c> — split on <c>----</c>. The otp / twofa / login options do not apply to warehouse 3. A <b>quick-sign-in-link + cookies</b> warehouse (added later — its <c>delivers</c> lists both loginUrl and cookies) has its OWN layout, separated by <c>----</c>: the first line is <c>email----password----recovery----loginUrl----cookies</c>, every account is ALWAYS 5 cells (an empty cell reads <c>no</c>) — the first 4 cells as the warehouse-2 line, the cookies are everything after the fourth <c>----</c>. The otp / twofa / login options do not apply. While warehouse 1 delivers the source's LOGIN LINK instead of cookies (warehouse 1's delivers has no "cookies" — see GET /v1/mail-shop/products), an order with such warehouse-1 accounts gets the <c>loginUrl</c> column BY DEFAULT (no <c>?login=1</c> needed): email|password|cookies|inboxUrl|loginUrl — the cookies cell is empty, loginUrl = the account's sign-in link (empty when the source gave no link). Read the header line for the column order.
Параметри
НазваТипОбов'язковийОпис
idstringТакOrder ID (data.id returned by the purchase)
Приклад
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/download" \
  -H "Authorization: Bearer og_xxx..." \
  -o mail-ORDER_ID.txt
Приклад відповіді
email|password|cookies|inboxUrl
[email protected]|Pw7Xq!k3d|[{"domain":".google.com","name":"SID","value":"g.a000…"}]|https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d
Можливі помилки: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR
GET/v1/mail-shop/orders/{id}/items/{lineNo}/inbox
Latest emails of a WAREHOUSE-1 / WAREHOUSE-3 account (sender, subject, time, extracted code / link, sanitized full email). Without an API key: GET the account's inboxJsonUrl (same emails, JSON).
max = 10 (default) | 20 | 50 | 100 | 200 — more emails take longer (up to about a minute). Cached for 15 seconds; every real read counts toward the hourly limit. 409 VALIDATION_ERROR = a warehouse-2 account (no inbox reading); 409 PROVIDER_ERROR with details.dead = the account was locked or removed.
Параметри
НазваТипОбов'язковийОпис
idstringТакOrder ID (data.id returned by the purchase)
lineNonumberТакAccount number within the order (items[].lineNo)
maxnumberНіNumber of latest emails: 10 (default), 20, 50, 100 or 200
Приклад
# Warehouse 1 accounts only; max = 10 | 20 | 50 | 100 | 200
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/inbox?max=20" \
  -H "Authorization: Bearer og_xxx..." \
  --max-time 70

# Same emails without an API key: GET the account's inboxJsonUrl
curl "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d?json&max=20"
Приклад відповіді
{
  "success": true,
  "data": {
    "email": "[email protected]",
    "letters": [
      {
        "key": "h:9f2c4e1a7b3d5c80",
        "from": "Instagram [email protected]",
        "subject": "350038 is your Instagram code",
        "receivedAt": 1760000520,
        "code": "350038",
        "content": "<html><body><p>Enter this confirmation code in the app: 350038</p></body></html>"
      }
    ],
    "max": 10,
    "total": 8,
    "fetchedAt": 1760000530,
    "cached": false
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PROVIDER_ERROR
GET/v1/mail-shop/orders/{id}/items/{lineNo}/status
Is a bought warehouse-1 / warehouse-3 account still alive: live = true / false, or null when it cannot be determined. Counts toward the hourly inbox-read limit.
Параметри
НазваТипОбов'язковийОпис
idstringТакOrder ID (data.id returned by the purchase)
lineNonumberТакAccount number within the order (items[].lineNo)
Приклад
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/status" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "email": "[email protected]",
    "live": true,
    "reason": null,
    "checkedAt": 1760000600
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PROVIDER_ERROR
GET/v1/mail-shop/orders/{id}/items/{lineNo}/2fa
The current 2FA code (6-digit TOTP, changes every 30 seconds) of a warehouse-1 account — some warehouse-1 accounts have 2-step verification on (Google asks for a code at a password sign-in). none = true ⇒ the account has no 2FA (code / expiresIn null). expiresIn = seconds the code stays valid — ask again after that. Without an API key: GET the account's twoFaUrl (the body is just the 6 digits).
The server caches the code until it expires (every call within those 30 seconds gets the same code) — it does NOT count toward the hourly inbox-read limit. Calling too fast ⇒ 429 (retryAfterSec); a warehouse-2 account ⇒ 409; a locked account ⇒ 409 (details.dead). Warehouse 3: every account has 2FA on — the code is computed from the account's 2FA key (<c>items[].twofa</c>; you can compute it yourself with standard TOTP: SHA1 · 30 seconds · 6 digits), so there is always a code.
Параметри
НазваТипОбов'язковийОпис
idstringТакOrder ID (data.id returned by the purchase)
lineNonumberТакAccount number within the order (items[].lineNo)
Приклад
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/2fa" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "none": false,
    "code": "424819",
    "expiresIn": 24
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PROVIDER_ERROR

Proxies

Buy HTTP proxies over the API — same catalog, prices, balance and rules as the website (same server, same orders). Proxies come as ip:port:user:pass (HTTP CONNECT + plain HTTP); EVERY proxy has a port of its own (port) — no two proxies ever share an ip:port, so tools that group proxies by ip:port keep each one apart. You are charged ONCE per order; anything not delivered is refunded automatically, once (refundVnd). The proxy section may be closed for now ⇒ every call answers 503 PROXY_DISABLED.
What you can buy (warehouses)
WarehouseYou getDays (days)Dead proxy
1HTTP proxies with a daily warranty: Resident VN, VIP Resident VN, Datacenter VN, Resident US, Datacenter US — pick from products[]. Every type is delivered as the same kind of host:port:user:pass string of ours (a port + user / pass of its own per proxy)Your choice of WARRANTY days (days 1…warranty.maxDays, default 30). Price per proxy ≈ basePriceVnd (includes 1 day) + (days − 1) × perDayVnd rounded up to warranty.roundTo — the EXACT figure: GET /v1/proxy/quote. The warranty days are the TERM OF USE: at warrantyUntil the proxy stops working (its port closes — connection / login refused); to keep it, renew BEFORE it ends (same string, same port), once ended ⇒ buy a new oneDead within the warranty ⇒ POST /v1/proxy/items/replace swaps it for FREE: your proxy string STAYS THE SAME (same id, same proxy), only the outgoing IP changes — nothing to reconfigure (at least 3 replacements per proxy — replacementsLeft); cannot be swapped at once ⇒ pending (waiting), it completes by itself. Buy with autoReplace: true (+autoReplace.priceVnd per proxy) ⇒ the system replaces a dead IP BY ITSELF, no replace call needed
2A private rotating-IP proxy rented by the day — NO LONGER SOLD (not in catalog any more); rentals you already have keep working / changing IP / renewing until they endRENTAL days (daysMeaning: "rental") — revoked at expiresAt; renewing before that keeps the same stringDead IP ⇒ POST /v1/proxy/items/{id}/change-ip moves it to another IP, the proxy string STAYS THE SAME (only while the IP is dead — alive ⇒ 409 PROXY_IP_ALIVE)
Three steps
  1. GET /v1/proxy/catalog ⇒ pick a product with warranty.available: true (basePriceVnd + perDayVnd per day is YOUR price; stock = how many you can buy now).
  2. POST /v1/proxy/orders {productId, days, quantity} (+ autoReplace: true if you want the system to replace a dead IP by itself) + an Idempotency-Key header (REQUIRED) ⇒ the order + items[] (one proxy each, the string is proxy).
  3. Manage: GET /v1/proxy/items (filter with view, type), check live, warranty / replace, renew, export .txt.
# warehouse 1: productId from GET /v1/proxy/catalog (products[].productId) + warranty days (1–maxDays, default 30)
# "autoReplace": true (optional, + products[].autoReplace.priceVnd per proxy) = the system replaces a dead IP by itself
# warehouse 2: {"planId": products[].plans[].id} · one NEW Idempotency-Key per purchase, reuse it to retry
curl -X POST "https://onemail.wtf/v1/proxy/orders" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 60 \
  -d '{"productId":5,"days":30,"quantity":5,"autoReplace":true}'
Proxy fields (items[])
ПолеТипОпис
idstringProxy ID — use it in every /v1/proxy/items… call
proxystringThe ip:port:user:pass string to paste into your tool (other formats: POST /v1/proxy/items/export)
host · port · username · passwordstring · numberThe parts of the proxy string (HTTP). port is THIS proxy's own port (one port per proxy) — kept when renewing / replacing
kho1 | 21 = proxy with a warranty (the 5 types on sale) · 2 = private rotating-IP rental (no longer sold)
statusstringactive · pending_replace (warehouse 1 — waiting for a replacement) · expired · replaced (see replacedBy) · revoked
healthstringlive · dead · unknown — from the last check (lastCheckAt)
exitIp · latencyMsstring | null · number | nullOutgoing IP + latency measured at the last check
warrantyUntilnumber | nullWarehouse 1: end of warranty (Unix seconds); warehouse 2: null
expiresAtnumber | nullEnd of use (Unix seconds) if any — the proxy stops at that time (renew before to keep it); null = no separate end of use
replacementsLeftnumber | nullWarehouse 1: free replacements left; null = no limit on the number of replacements (still only while the proxy is dead within the warranty) · warehouse 2: null
intermediateobject | nullAlways null for newly bought proxies — the "intermediate proxy" option has been REMOVED (the proxy string is already our own). Kept for compatibility
autoReplacebooleantrue = bought with "Intermediate proxy — auto-replace the IP when it dies": the system checks the proxy every 5 minutes and switches a dead IP to a new one by itself (same proxy string + port) within the warranty. Chosen at purchase only; renewals keep it
autoReplaceStatusobject | null{state, count, lastAt} when autoReplace — state: on (auto-replacing) · stopped (free replacements used up — no more auto replacement); count = automatic replacements so far; lastAt = the latest one (Unix seconds). null when not chosen
replacedBy · replacesstring | nullUsually null: a warranty swap keeps the same proxy (same id + string). Only very old proxies (before 06 Nov 2026) carry a new / old proxy ID here
actionsobject{check, warranty, replace, changeIp, renew} — which calls work for this proxy right now (computed by the server — do not guess)
Warranty / replace outcomes
outcomeОпис
aliveStill alive — nothing to replace
eligibleDead + under warranty + replacements left ⇒ call replace
replaced(replace) swapped — the proxy to use is newItem (its id / string may stay the same when only the outgoing IP changed — always use newItem.proxy)
pendingReported, waiting for a replacement — the new proxy arrives by itself (check GET /v1/proxy/items/{id} again in a few minutes)
expiredWarranty ended
limitNo free replacements left (replacementsLeft = 0)
not_eligibleDoes not apply (warehouse 2 / replaced / revoked / expired)
failed(replace) could not swap right now — try again later
not_foundNot a proxy of your account
Rules
  • Idempotency-Key is REQUIRED for POST /v1/proxy/orders and POST /v1/proxy/items/renew (missing ⇒ 400). Timed out / network error ⇒ resend with the SAME key: you get the same order back, never a second charge.
  • Orders usually finish at once (completed). Rarely the answer is processing (still being delivered) ⇒ poll GET /v1/proxy/orders/{id} every 3–5 s. partial = fewer delivered, the rest refunded (refundVnd); total failure ⇒ 502 PROXY_SUPPLIER_ERROR + error.details.orderId (refunded).
  • Out of stock ⇒ 409 PROXY_OUT_OF_STOCK (error.details.stock) and nothing is charged; retryable: true ⇒ wait retryAfterSec and try again (with a NEW key).
  • Warehouse 1 — warranty: warranty only CHECKS (alive / dead / in or out of warranty / waiting); replace SWAPS (free for you). A pasted list (lookup) only matches your own account's proxies — anything else ⇒ not_mine.
  • Auto IP replace (an option at purchase — autoReplace: true, +products[].autoReplace.priceVnd per proxy, added AFTER the unit price is rounded): the system checks every 5 minutes; a dead IP is double-checked and then replaced by a new one, same string; the proxy log shows replace with data.auto: true. Free replacements used up ⇒ autoReplaceStatus.state = stopped. Not chosen ⇒ as before: call warranty / replace yourself. Option temporarily off ⇒ autoReplace.available: false, buying with it ⇒ 409 PROXY_NOT_ELIGIBLE (details.reason: "auto_replace_unavailable", nothing charged).
  • Renew: renew-quote shows the price first, renew charges ONCE for the whole set (same warehouse — mixed ⇒ 400). Warehouse 1 = more warranty days, same proxy (only before its end of use); warehouse 2 = more rental days (only before it expires).
  • Proxy-section limits (shared by web + API): buying + renewing per the shop settings (default 20 calls / minute); check / warranty / lookup / replace / change IP 120 calls / minute ⇒ 429 RATE_LIMITED.
GET/v1/proxy/catalog
Proxy catalog (the 5 types with a per-day warranty — the warehouse-2 rental card is no longer sold). <c>products[]</c>: <c>kho</c>, <c>productId</c>, <c>type</c> + <c>grade</c> + <c>nameKey</c> (neutral name — empty <c>name</c> ⇒ name it from <c>nameKey</c>), <c>stock</c>, <c>daysMeaning</c>. Warehouse 1: <c>warranty</c> = {<c>basePriceVnd</c> (price per proxy INCLUDING 1 warranty day), <c>perDayVnd</c> (+ per extra warranty day), <c>minDays</c>, <c>maxDays</c>, <c>defaultDays</c> (30), <c>quickDays</c>, <c>roundTo</c> (the total per proxy is rounded up to this), <c>available</c>} + <c>plans</c> = [the per-day plan at 30 days]; <c>intermediate</c> is always <c>null</c> (the old option was removed); <c>autoReplace</c> = {<c>available</c>, <c>priceVnd</c>} — the "auto-replace the IP when it dies" option (+<c>priceVnd</c> per proxy when you buy with <c>autoReplace: true</c>). Temporarily not for sale (maintenance) ⇒ <c>available: false</c>, <c>stock: 0</c>. Warehouse 2: <c>plans[]</c> = {<c>id</c> (the planId to rent), <c>days</c>, <c>priceVnd</c>, <c>listPriceVnd</c>, <c>customPrice</c>, <c>available</c>}. <c>maxQuantity</c> = most proxies per order.
Приклад
curl "https://onemail.wtf/v1/proxy/catalog" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "enabled": true,
    "kho1Enabled": true,
    "kho2Enabled": true,
    "maxQuantity": 100,
    "formats": [
      "colon",
      "at",
      "url"
    ],
    "products": [
      {
        "key": "k1-5",
        "kho": 1,
        "productId": 5,
        "type": "datacenter_vn",
        "grade": "good",
        "nameKey": "datacenter_vn.good",
        "name": "",
        "description": "",
        "protocol": "http",
        "stock": 1476,
        "daysMeaning": "warranty",
        "plans": [
          {
            "id": 17,
            "kho": 1,
            "days": 30,
            "priceVnd": 1400,
            "listPriceVnd": 1400,
            "customPrice": false,
            "available": true
          }
        ],
        "warranty": {
          "planId": 17,
          "minDays": 1,
          "maxDays": 90,
          "defaultDays": 30,
          "quickDays": [
            7,
            15,
            30,
            60,
            90
          ],
          "basePriceVnd": 450,
          "perDayVnd": 30,
          "listBasePriceVnd": 450,
          "listPerDayVnd": 30,
          "customPrice": false,
          "roundTo": 100,
          "available": true
        },
        "intermediate": null,
        "autoReplace": {
          "available": true,
          "priceVnd": 50
        }
      },
      {
        "key": "k1-4",
        "kho": 1,
        "productId": 4,
        "type": "datacenter_us",
        "grade": "good",
        "nameKey": "datacenter_us.good",
        "name": "",
        "description": "",
        "protocol": "http",
        "stock": 810,
        "daysMeaning": "warranty",
        "plans": [
          {
            "id": 13,
            "kho": 1,
            "days": 30,
            "priceVnd": 1200,
            "listPriceVnd": 1200,
            "customPrice": false,
            "available": true
          }
        ],
        "warranty": {
          "planId": 13,
          "minDays": 1,
          "maxDays": 90,
          "defaultDays": 30,
          "quickDays": [
            7,
            15,
            30,
            60,
            90
          ],
          "basePriceVnd": 600,
          "perDayVnd": 20,
          "listBasePriceVnd": 600,
          "listPerDayVnd": 20,
          "customPrice": false,
          "roundTo": 100,
          "available": true
        },
        "intermediate": null,
        "autoReplace": {
          "available": true,
          "priceVnd": 50
        }
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, PROXY_DISABLED
GET/v1/proxy/quote
Total (nothing is reserved) + your available balance (<c>enough</c>). Warehouse 1: <c>productId</c> + <c>days</c> ⇒ <c>unitPriceVnd</c> = price incl. 1 day + (days − 1) × per-day price, rounded up; <c>autoReplace=1</c> ⇒ plus <c>autoReplacePriceVnd</c> (auto-replace a dead IP — added AFTER rounding). An <c>intermediate</c> parameter is ignored (always <c>false</c>). Warehouse 2: <c>planId</c>.
Параметри
НазваТипОбов'язковийОпис
productIdnumberНіWarehouse 1 — <c>products[].productId</c>
daysnumberНіWarehouse 1 — warranty days 1…<c>warranty.maxDays</c> (default 30)
autoReplacebooleanНіWarehouse 1 — <c>1</c> = with "auto-replace the IP when it dies" (+<c>autoReplace.priceVnd</c> per proxy)
planIdnumberНіWarehouse 2 — plan <c>products[].plans[].id</c> (warehouse 1: the per-day plan is accepted too)
quantitynumberНіNumber of proxies (default 1)
Приклад
curl "https://onemail.wtf/v1/proxy/quote?productId=5&days=30&autoReplace=1&quantity=5" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "planId": 17,
    "productId": 5,
    "kho": 1,
    "type": "datacenter_vn",
    "days": 30,
    "intermediate": false,
    "intermediatePriceVnd": 0,
    "autoReplace": true,
    "autoReplacePriceVnd": 50,
    "quantity": 5,
    "unitPriceVnd": 1450,
    "totalVnd": 7250,
    "stock": 1476,
    "maxQuantity": 100,
    "balanceVnd": 250000,
    "enough": true
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_PLAN_NOT_FOUND, PROXY_QTY_LIMIT, PROXY_NOT_ELIGIBLE, PROXY_DISABLED
POST/v1/proxy/orders
Buy proxies. Warehouse 1: <c>{productId, days, quantity}</c> (days default 30; <c>autoReplace: true</c> = with "auto-replace the IP when it dies", + <c>autoReplace.priceVnd</c> per proxy; an old warehouse-1 <c>planId</c> is still accepted; an old <c>intermediate</c> field is ignored). Warehouse 2: <c>{planId, quantity}</c>. Charged ONCE, delivered at once — the response carries <c>items[]</c>. Out of stock ⇒ 409, nothing charged; temporarily cannot deliver (maintenance) ⇒ 503 <c>PROXY_UNAVAILABLE</c>, nothing charged (retry later); fewer delivered ⇒ <c>partial</c> + the rest refunded; total failure ⇒ 502 (refunded). Success is 200 (the website gets 201).
Use a client timeout of at least 60 s. Lost connection ⇒ resend with the SAME Idempotency-Key.
Параметри
НазваТипОбов'язковийОпис
productIdnumberНіWarehouse 1 — <c>products[].productId</c>
daysnumberНіWarehouse 1 — warranty days 1…<c>warranty.maxDays</c> (default 30)
autoReplacebooleanНіWarehouse 1 — <c>true</c> = "Intermediate proxy — auto-replace the IP when it dies" (+<c>autoReplace.priceVnd</c> per proxy, default <c>false</c>): the system replaces a dead IP by itself; not chosen ⇒ call <c>replace</c> yourself when a proxy dies
planIdnumberНіWarehouse 2 — plan <c>products[].plans[].id</c> from the catalog (send <c>productId</c> OR <c>planId</c>)
quantitynumberТакNumber of proxies (≤ <c>maxQuantity</c>)
Idempotency-KeystringТакA new UUID per purchase; reuse it when retrying
Приклад
# warehouse 1: productId from GET /v1/proxy/catalog (products[].productId) + warranty days (1–maxDays, default 30)
# "autoReplace": true (optional, + products[].autoReplace.priceVnd per proxy) = the system replaces a dead IP by itself
# warehouse 2: {"planId": products[].plans[].id} · one NEW Idempotency-Key per purchase, reuse it to retry
curl -X POST "https://onemail.wtf/v1/proxy/orders" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 60 \
  -d '{"productId":5,"days":30,"quantity":5,"autoReplace":true}'
Приклад відповіді
{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5f6g7h8",
    "kho": 1,
    "kind": "buy",
    "planId": 17,
    "type": "datacenter_vn",
    "nameKey": "datacenter_vn.good",
    "quantity": 1,
    "days": 30,
    "unitPriceVnd": 1450,
    "totalVnd": 1450,
    "refundVnd": 0,
    "status": "completed",
    "deliveredCount": 1,
    "source": "api",
    "intermediate": false,
    "intermediateFailed": 0,
    "autoReplace": true,
    "autoReplacePriceVnd": 50,
    "errorCode": null,
    "errorMessage": null,
    "createdAt": 1793952000,
    "completedAt": 1793952003,
    "items": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "orderId": "a1b2c3d4e5f6g7h8",
        "kho": 1,
        "type": "resident_vn",
        "protocol": "http",
        "host": "203.0.113.50",
        "port": 23817,
        "username": "u7hk2m9qzt4w",
        "password": "Lp2Qa8xT4w9cNb3e",
        "proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
        "status": "active",
        "health": "live",
        "exitIp": "198.51.100.21",
        "latencyMs": 182,
        "lastCheckAt": 1793952060,
        "lastOkAt": 1793952060,
        "expiresAt": 1794556800,
        "warrantyUntil": 1794556800,
        "replacementsLeft": 3,
        "replaceCount": 0,
        "replacedBy": null,
        "replaces": null,
        "intermediate": null,
        "autoReplace": true,
        "autoReplaceStatus": {
          "state": "on",
          "count": 1,
          "lastAt": 1794020400
        },
        "actions": {
          "check": true,
          "warranty": true,
          "replace": false,
          "changeIp": false,
          "renew": true
        },
        "createdAt": 1793952003
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, INSUFFICIENT_BALANCE, PROXY_PLAN_NOT_FOUND, PROXY_QTY_LIMIT, PROXY_NOT_ELIGIBLE, PROXY_OUT_OF_STOCK, PROXY_SUPPLIER_ERROR, PROXY_UNAVAILABLE, PROXY_DISABLED, RATE_LIMITED, DUPLICATE_REQUEST, MAINTENANCE
GET/v1/proxy/orders
Your proxy orders (purchases + renewals), newest first, paginated. No <c>items</c> — open one with <c>GET /v1/proxy/orders/{id}</c>.
Параметри
НазваТипОбов'язковийОпис
pagenumberНіPage (from 1)
pageSizenumberНі1–200, default 20
khonumberНі1 | 2
kindstringНі<c>buy</c> | <c>renew</c>
typestringНіType: <c>resident_vn</c> · <c>vip_resident_vn</c> · <c>datacenter_vn</c> · <c>resident_us</c> · <c>datacenter_us</c>
Приклад
curl "https://onemail.wtf/v1/proxy/orders?page=1&pageSize=20" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1b2c3d4e5f6g7h8",
        "kho": 1,
        "kind": "buy",
        "planId": 17,
        "type": "datacenter_vn",
        "nameKey": "datacenter_vn.good",
        "quantity": 1,
        "days": 30,
        "unitPriceVnd": 1450,
        "totalVnd": 1450,
        "refundVnd": 0,
        "status": "completed",
        "deliveredCount": 1,
        "source": "api",
        "intermediate": false,
        "intermediateFailed": 0,
        "autoReplace": true,
        "autoReplacePriceVnd": 50,
        "errorCode": null,
        "errorMessage": null,
        "createdAt": 1793952000,
        "completedAt": 1793952003
      },
      {
        "id": "z9x8c7v6b5n4m3l2",
        "kho": 1,
        "kind": "buy",
        "planId": 17,
        "type": "datacenter_vn",
        "nameKey": "datacenter_vn.good",
        "quantity": 10,
        "days": 30,
        "unitPriceVnd": 1400,
        "totalVnd": 14000,
        "refundVnd": 4200,
        "status": "partial",
        "deliveredCount": 7,
        "source": "api",
        "intermediate": false,
        "intermediateFailed": 0,
        "autoReplace": false,
        "autoReplacePriceVnd": 0,
        "errorCode": "PROXY_OUT_OF_STOCK",
        "errorMessage": "Delivered 7/10 proxies — 4,200 VND refunded for the rest",
        "createdAt": 1793952000,
        "completedAt": 1793952004
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 20
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLED
GET/v1/proxy/orders/{id}
One order + <c>items[]</c> (a renewal: the proxies renewed). Poll it while <c>status</c> = <c>processing</c>.
Параметри
НазваТипОбов'язковийОпис
idstringТакOrder ID
Приклад
curl "https://onemail.wtf/v1/proxy/orders/ORDER_ID" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5f6g7h8",
    "kho": 1,
    "kind": "buy",
    "planId": 17,
    "type": "datacenter_vn",
    "nameKey": "datacenter_vn.good",
    "quantity": 1,
    "days": 30,
    "unitPriceVnd": 1450,
    "totalVnd": 1450,
    "refundVnd": 0,
    "status": "completed",
    "deliveredCount": 1,
    "source": "api",
    "intermediate": false,
    "intermediateFailed": 0,
    "autoReplace": true,
    "autoReplacePriceVnd": 50,
    "errorCode": null,
    "errorMessage": null,
    "createdAt": 1793952000,
    "completedAt": 1793952003,
    "items": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "orderId": "a1b2c3d4e5f6g7h8",
        "kho": 1,
        "type": "resident_vn",
        "protocol": "http",
        "host": "203.0.113.50",
        "port": 23817,
        "username": "u7hk2m9qzt4w",
        "password": "Lp2Qa8xT4w9cNb3e",
        "proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
        "status": "active",
        "health": "live",
        "exitIp": "198.51.100.21",
        "latencyMs": 182,
        "lastCheckAt": 1793952060,
        "lastOkAt": 1793952060,
        "expiresAt": 1794556800,
        "warrantyUntil": 1794556800,
        "replacementsLeft": 3,
        "replaceCount": 0,
        "replacedBy": null,
        "replaces": null,
        "intermediate": null,
        "autoReplace": true,
        "autoReplaceStatus": {
          "state": "on",
          "count": 1,
          "lastAt": 1794020400
        },
        "actions": {
          "check": true,
          "warranty": true,
          "replace": false,
          "changeIp": false,
          "renew": true
        },
        "createdAt": 1793952003
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, PROXY_DISABLED
GET/v1/proxy/items
Your proxies. <c>view</c>: <c>active</c> (in use — default) · <c>expiring</c> (ends within 24 h) · <c>dead</c> (in use but dead) · <c>expired</c> (expired / replaced / revoked) · <c>all</c>. <c>counts</c> = how many in each filter.
Параметри
НазваТипОбов'язковийОпис
viewstringНіFilter (see above)
khonumberНі1 | 2
typestringНіType: <c>resident_vn</c> · <c>vip_resident_vn</c> · <c>datacenter_vn</c> · <c>resident_us</c> · <c>datacenter_us</c>
qstringНіSearch host / user / exit IP / id
orderIdstringНіOnly the proxies of one order
page · pageSizenumberНіPagination (pageSize 1–200)
Приклад
curl "https://onemail.wtf/v1/proxy/items?view=active&pageSize=100" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "p7w2n8x4c1v9b3m6",
        "orderId": "q9w8e7r6t5y4u3i2",
        "kho": 2,
        "type": "private_vn",
        "protocol": "http",
        "host": "203.0.113.50",
        "port": 18450,
        "username": "rx7k2m9q",
        "password": "Tz4w8Lp2Qa",
        "proxy": "203.0.113.50:18450:rx7k2m9q:Tz4w8Lp2Qa",
        "status": "active",
        "health": "dead",
        "exitIp": "198.51.100.77",
        "latencyMs": null,
        "lastCheckAt": 1793952060,
        "lastOkAt": 1793948400,
        "expiresAt": 1794556800,
        "warrantyUntil": null,
        "replacementsLeft": null,
        "replaceCount": 1,
        "replacedBy": null,
        "replaces": null,
        "intermediate": null,
        "autoReplace": false,
        "autoReplaceStatus": null,
        "actions": {
          "check": true,
          "warranty": false,
          "replace": false,
          "changeIp": true,
          "renew": true
        },
        "createdAt": 1793952000
      },
      {
        "id": "k3m9x2p7q1w8e5r4",
        "orderId": "a1b2c3d4e5f6g7h8",
        "kho": 1,
        "type": "resident_vn",
        "protocol": "http",
        "host": "203.0.113.50",
        "port": 23817,
        "username": "u7hk2m9qzt4w",
        "password": "Lp2Qa8xT4w9cNb3e",
        "proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
        "status": "active",
        "health": "live",
        "exitIp": "198.51.100.21",
        "latencyMs": 182,
        "lastCheckAt": 1793952060,
        "lastOkAt": 1793952060,
        "expiresAt": 1794556800,
        "warrantyUntil": 1794556800,
        "replacementsLeft": 3,
        "replaceCount": 0,
        "replacedBy": null,
        "replaces": null,
        "intermediate": null,
        "autoReplace": true,
        "autoReplaceStatus": {
          "state": "on",
          "count": 1,
          "lastAt": 1794020400
        },
        "actions": {
          "check": true,
          "warranty": true,
          "replace": false,
          "changeIp": false,
          "renew": true
        },
        "createdAt": 1793952003
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "counts": {
      "active": 2,
      "expiring": 0,
      "dead": 1,
      "expired": 0,
      "all": 2
    }
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLED
GET/v1/proxy/items/{id}
One proxy + its history (<c>events[]</c>: buy, deliver, check, warranty, replace, IP change, renew…) + traffic per day (warehouse 2 — <c>usage[]</c>).
Параметри
НазваТипОбов'язковийОпис
idstringТакProxy ID
Приклад
curl "https://onemail.wtf/v1/proxy/items/PROXY_ID" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "item": {
      "id": "k3m9x2p7q1w8e5r4",
      "orderId": "a1b2c3d4e5f6g7h8",
      "kho": 1,
      "type": "resident_vn",
      "protocol": "http",
      "host": "203.0.113.50",
      "port": 23817,
      "username": "u7hk2m9qzt4w",
      "password": "Lp2Qa8xT4w9cNb3e",
      "proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
      "status": "active",
      "health": "live",
      "exitIp": "198.51.100.21",
      "latencyMs": 182,
      "lastCheckAt": 1793952060,
      "lastOkAt": 1793952060,
      "expiresAt": 1794556800,
      "warrantyUntil": 1794556800,
      "replacementsLeft": 3,
      "replaceCount": 0,
      "replacedBy": null,
      "replaces": null,
      "intermediate": null,
      "autoReplace": true,
      "autoReplaceStatus": {
        "state": "on",
        "count": 1,
        "lastAt": 1794020400
      },
      "actions": {
        "check": true,
        "warranty": true,
        "replace": false,
        "changeIp": false,
        "renew": true
      },
      "createdAt": 1793952003
    },
    "events": [
      {
        "id": 871,
        "type": "check",
        "ok": true,
        "actor": "api",
        "at": 1793952060,
        "data": {
          "health": "live",
          "exitIp": "203.0.113.21"
        }
      },
      {
        "id": 870,
        "type": "deliver",
        "ok": true,
        "actor": "system",
        "at": 1793952003,
        "data": {
          "days": 7
        }
      }
    ],
    "usage": []
  }
}
Можливі помилки: UNAUTHORIZED, PROXY_ITEM_NOT_FOUND, PROXY_DISABLED
POST/v1/proxy/items/check
Check proxies now (up to 200 IDs): <c>health</c>, <c>exitIp</c>, <c>latencyMs</c>, <c>error</c> (<c>timeout</c> · <c>connect</c> · <c>auth</c> · <c>bad_response</c> · <c>unavailable</c>). IDs that are not yours ⇒ <c>found: false</c>.
Параметри
НазваТипОбов'язковийОпис
idsstring[]ТакProxy IDs (≤ 200)
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/check" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"]}'
Приклад відповіді
{
  "success": true,
  "data": {
    "results": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "found": true,
        "health": "live",
        "exitIp": "203.0.113.21",
        "latencyMs": 182,
        "checkedAt": 1794038400,
        "error": null
      },
      {
        "id": "nope",
        "found": false,
        "health": "unknown",
        "exitIp": null,
        "latencyMs": null,
        "checkedAt": null,
        "error": null
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLED
POST/v1/proxy/items/warranty
Warehouse 1 — CHECK the warranty (no swap yet): <c>outcome</c> per the outcome table, <c>warrantyUntil</c>, <c>replacementsLeft</c>. <c>eligible</c> ⇒ call <c>replace</c>.
Параметри
НазваТипОбов'язковийОпис
idsstring[]ТакProxy IDs (≤ 200)
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/warranty" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"]}'
Приклад відповіді
{
  "success": true,
  "data": {
    "results": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "kho": 1,
        "health": "dead",
        "outcome": "eligible",
        "warrantyUntil": 1794556800,
        "replacementsLeft": 3,
        "checkedAt": 1794038400
      },
      {
        "id": "m1n2b3v4c5x6z7l8",
        "kho": 1,
        "health": "dead",
        "outcome": "expired",
        "warrantyUntil": 1793952000,
        "replacementsLeft": 2,
        "checkedAt": 1794038400
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLED
POST/v1/proxy/items/lookup
Bulk warranty by pasting a list (≤ 2,000 lines; accepts <c>ip:port:user:pass</c>, <c>user:pass@ip:port</c>, <c>http://user:pass@ip:port</c>… or just <c>user:pass</c>). Each line: an <c>error</c> (<c>invalid</c> · <c>not_mine</c> · <c>duplicate</c>) or a <c>result</c> (as <c>warranty</c>). Pass <c>eligibleIds</c> straight to <c>replace</c> ("replace every dead proxy under warranty").
Параметри
НазваТипОбов'язковийОпис
textstringТакThe list, one proxy per line
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/lookup" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"text":"203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e\nhttp://x:[email protected]:8080"}'
Приклад відповіді
{
  "success": true,
  "data": {
    "lines": [
      {
        "lineNo": 1,
        "input": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
        "error": null,
        "itemId": "k3m9x2p7q1w8e5r4",
        "result": {
          "id": "k3m9x2p7q1w8e5r4",
          "kho": 1,
          "health": "dead",
          "outcome": "eligible",
          "warrantyUntil": 1794556800,
          "replacementsLeft": 3,
          "checkedAt": 1794038400
        }
      },
      {
        "lineNo": 2,
        "input": "http://x:[email protected]:8080",
        "error": "not_mine",
        "itemId": null,
        "result": null
      }
    ],
    "eligibleIds": [
      "k3m9x2p7q1w8e5r4"
    ],
    "summary": {
      "total": 2,
      "mine": 1,
      "notMine": 1,
      "invalid": 0,
      "alive": 0,
      "eligible": 1,
      "expired": 0
    }
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED, PROXY_DISABLED
POST/v1/proxy/items/replace
Warehouse 1 — SWAP dead proxies under warranty (free for you, at least 3 times per proxy — see <c>replacementsLeft</c>). <c>replaced</c> ⇒ <c>newItem</c> is THE SAME proxy (same <c>id</c>, same <c>proxy</c> string — nothing to reconfigure), only the outgoing IP is new; <c>pending</c> ⇒ waiting, it completes by itself. Alive / out of warranty / no replacements left ⇒ no swap.
Параметри
НазваТипОбов'язковийОпис
idsstring[]ТакProxy IDs (≤ 200) — e.g. eligibleIds from lookup
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/replace" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"]}'
Приклад відповіді
{
  "success": true,
  "data": {
    "results": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "outcome": "replaced",
        "newItem": {
          "id": "k3m9x2p7q1w8e5r4",
          "orderId": "a1b2c3d4e5f6g7h8",
          "kho": 1,
          "type": "resident_vn",
          "protocol": "http",
          "host": "203.0.113.50",
          "port": 23817,
          "username": "u7hk2m9qzt4w",
          "password": "Lp2Qa8xT4w9cNb3e",
          "proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
          "status": "active",
          "health": "unknown",
          "exitIp": null,
          "latencyMs": null,
          "lastCheckAt": null,
          "lastOkAt": null,
          "expiresAt": 1794556800,
          "warrantyUntil": 1794556800,
          "replacementsLeft": 2,
          "replaceCount": 1,
          "replacedBy": null,
          "replaces": null,
          "intermediate": null,
          "autoReplace": true,
          "autoReplaceStatus": {
            "state": "on",
            "count": 1,
            "lastAt": 1794020400
          },
          "actions": {
            "check": true,
            "warranty": true,
            "replace": false,
            "changeIp": false,
            "renew": true
          },
          "createdAt": 1793952003
        }
      },
      {
        "id": "m1n2b3v4c5x6z7l8",
        "outcome": "expired",
        "newItem": null
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLED
POST/v1/proxy/items/{id}/change-ip
Warehouse 2 — move to another IP while the current IP is DEAD (re-checked right before the change). The proxy string stays the same; only the outgoing IP changes (<c>fromIp</c> ⇒ <c>toIp</c>). IP still alive ⇒ 409 <c>PROXY_IP_ALIVE</c>.
Параметри
НазваТипОбов'язковийОпис
idstringТакProxy ID (warehouse 2)
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/PROXY_ID/change-ip" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{}'
Приклад відповіді
{
  "success": true,
  "data": {
    "item": {
      "id": "p7w2n8x4c1v9b3m6",
      "orderId": "q9w8e7r6t5y4u3i2",
      "kho": 2,
      "type": "private_vn",
      "protocol": "http",
      "host": "203.0.113.50",
      "port": 18450,
      "username": "rx7k2m9q",
      "password": "Tz4w8Lp2Qa",
      "proxy": "203.0.113.50:18450:rx7k2m9q:Tz4w8Lp2Qa",
      "status": "active",
      "health": "live",
      "exitIp": "198.51.100.91",
      "latencyMs": 140,
      "lastCheckAt": 1793952060,
      "lastOkAt": 1793948400,
      "expiresAt": 1794556800,
      "warrantyUntil": null,
      "replacementsLeft": null,
      "replaceCount": 2,
      "replacedBy": null,
      "replaces": null,
      "intermediate": null,
      "autoReplace": false,
      "autoReplaceStatus": null,
      "actions": {
        "check": true,
        "warranty": false,
        "replace": false,
        "changeIp": false,
        "renew": true
      },
      "createdAt": 1793952000
    },
    "fromIp": "198.51.100.77",
    "toIp": "198.51.100.91"
  }
}
Можливі помилки: UNAUTHORIZED, PROXY_ITEM_NOT_FOUND, PROXY_IP_ALIVE, PROXY_NOT_ELIGIBLE, PROXY_OUT_OF_STOCK, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLED
POST/v1/proxy/items/renew-quote
Price of renewing proxies by N days (same warehouse): price per proxy, the new end (<c>newEnd</c>), total + whether your balance covers it. Warehouse 1: price per proxy = N × the per-day warranty price of the proxy type, rounded up; N ≤ <c>warranty.maxDays</c> (90).
Параметри
НазваТипОбов'язковийОпис
idsstring[]ТакProxy IDs (≤ 200, same warehouse)
daysnumberТакWarehouse 1: 1–90 · warehouse 2: 1–365
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/renew-quote" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"],"days":7}'
Приклад відповіді
{
  "success": true,
  "data": {
    "kho": 1,
    "days": 7,
    "items": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "unitPriceVnd": 200,
        "newEnd": 1795161600
      }
    ],
    "totalVnd": 200,
    "balanceVnd": 250000,
    "enough": true
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_ITEM_NOT_FOUND, PROXY_NOT_ELIGIBLE, PROXY_DISABLED
POST/v1/proxy/items/renew
Renew — one <c>kind: "renew"</c> order, charged ONCE; proxies that could not be renewed are refunded (<c>partial</c>). Warehouse 1 adds warranty days; warehouse 2 adds rental days and keeps the proxy string.
Параметри
НазваТипОбов'язковийОпис
idsstring[]ТакProxy IDs (≤ 200, same warehouse)
daysnumberТак1–365
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/renew" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"],"days":7}'
Приклад відповіді
{
  "success": true,
  "data": {
    "id": "r1e2n3e4w5o6r7d8",
    "kho": 1,
    "kind": "renew",
    "planId": 17,
    "type": "datacenter_vn",
    "nameKey": "datacenter_vn.good",
    "quantity": 1,
    "days": 7,
    "unitPriceVnd": 200,
    "totalVnd": 200,
    "refundVnd": 0,
    "status": "completed",
    "deliveredCount": 1,
    "source": "api",
    "intermediate": false,
    "intermediateFailed": 0,
    "autoReplace": true,
    "autoReplacePriceVnd": 50,
    "errorCode": null,
    "errorMessage": null,
    "createdAt": 1793952000,
    "completedAt": 1793952003,
    "items": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "orderId": "a1b2c3d4e5f6g7h8",
        "kho": 1,
        "type": "resident_vn",
        "protocol": "http",
        "host": "203.0.113.50",
        "port": 23817,
        "username": "u7hk2m9qzt4w",
        "password": "Lp2Qa8xT4w9cNb3e",
        "proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
        "status": "active",
        "health": "live",
        "exitIp": "198.51.100.21",
        "latencyMs": 182,
        "lastCheckAt": 1793952060,
        "lastOkAt": 1793952060,
        "expiresAt": 1794556800,
        "warrantyUntil": 1795161600,
        "replacementsLeft": 3,
        "replaceCount": 0,
        "replacedBy": null,
        "replaces": null,
        "intermediate": null,
        "autoReplace": true,
        "autoReplaceStatus": {
          "state": "on",
          "count": 1,
          "lastAt": 1794020400
        },
        "actions": {
          "check": true,
          "warranty": true,
          "replace": false,
          "changeIp": false,
          "renew": true
        },
        "createdAt": 1793952003
      }
    ]
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, INSUFFICIENT_BALANCE, PROXY_ITEM_NOT_FOUND, PROXY_NOT_ELIGIBLE, PROXY_SUPPLIER_ERROR, PROXY_DISABLED, RATE_LIMITED, DUPLICATE_REQUEST, MAINTENANCE
POST/v1/proxy/items/export
Download a .txt list (text/plain), one proxy per line: <c>format</c> = <c>colon</c> (ip:port:user:pass — default) · <c>at</c> (user:pass@ip:port) · <c>url</c> (http://user:pass@ip:port). By <c>ids</c> (≤ 5,000) or by <c>view</c> + <c>kho</c>.
Параметри
НазваТипОбов'язковийОпис
idsstring[]НіProxy IDs (≤ 5,000)
view · kho · typestring · number · stringНіInstead of ids: filters as in GET /v1/proxy/items
formatstringНі<c>colon</c> | <c>at</c> | <c>url</c>
whichstringНіKept for compatibility: <c>proxy</c> (default). New proxies have no intermediate (the option was removed) ⇒ <c>intermediate</c> returns nothing, <c>both</c> = same as <c>proxy</c>
Приклад
curl -X POST "https://onemail.wtf/v1/proxy/items/export" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"view":"active","format":"url"}'
Приклад відповіді
http://u7hk2m9qzt4w:[email protected]:23817
http://rx7k2m9q:[email protected]:18450
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLED

Життєвий цикл замовлення

СтатусОпис
Очікує кодНове замовлення, що очікує на перший код. Опитуйте GET /v1/orders/{id} кожні 3–5 секунд.
ЗавершеноПерший код надійшов: статус змінюється одразу. Ще коди можуть надходити, якщо сервіс надсилає більше одного (без додаткової плати протягом строку замовлення; ліміт і вікно залежать від складу); продовжуйте опитування, і кожен новий код з'являтиметься в кінці otp[].
СкасованоКошти повернено на 100%. Відбувається, коли ви викликаєте /cancel (до надходження будь-якого коду) або коли код не надійшов до codeDeadlineAt (щонайбільше 25 хв).
Важливі примітки:
  • Опитуйте GET /v1/orders/{id} кожні 3–5 секунд, поки замовлення має статус waiting_code, щоб вчасно підхопити код.
  • Щойно надходить перший код, статус одразу змінюється на completed.
  • Немає коду до codeDeadlineAt (щонайбільше 25 хв; склад 2: 20 хв; деякі джерела складу 4 коротші) ⇒ система скасовує замовлення й повертає 100% (status = cancelled).
  • Масив otp[] упорядковано так: найстаріший перший, найновіший останній. Читайте останній код через otp[otp.length - 1] (Python: otp[-1]).
  • Замовлення completed й далі отримує коди автоматично: продовжуйте опитувати GET /v1/orders/{id}, і кожен новий код з'являтиметься в кінці otp[]. Додаткові коди нічого не коштують протягом строку замовлення, якщо сервіс надсилає більше одного; ліміт і часове вікно показано до оренди (maxCodes і fee в offers[]; на складі 1 скринька зазвичай залишається відкритою близько 25 хвилин після останнього коду). Щоб явно запросити ще один код (напр. щоб увійти після реєстрації): POST /v1/orders/{id}/next-code — працює на кожному складі, а плату стягує лише склад 2 поза безкоштовним вікном.
  • Якщо сервіс дозволяє лише один код на скриньку, otp[] зупиняється на цьому коді. Відповіді залишаються звичайними, без помилки: ви самі вирішуєте, коли припинити опитування.
  • otp[].code — це зазвичай короткий код (цифри / літери) або посилання. Лист без коду, який можна витягнути (вітальні листи, розсилки, незвичні формати кодів…), доставляється дослівно (HTML або текст) у otp[].code: розглядайте його як повний лист, якщо він довший за 80 символів, містить розрив рядка або є HTML, і шукайте в ньому код чи посилання самостійно.
  • POST /v1/orders чекає, поки постачальник призначить скриньку, тому зазвичай триває ~0,3 секунди, але в години пік (рідко) може тривати до 10 секунд. Встановіть тайм-аут клієнта ≈ 15 секунд, а не здавайтеся через 5 секунд і не повторюйте запит завчасно, а коли повторюєте, використовуйте той самий Idempotency-Key.
  • Замовлення, що отримало код, не можна скасувати чи повернути за нього кошти: виклик скасування повертає ORDER_NOT_CANCELLABLE.
  • Щоб орендувати скриньку @icloud.com, надішліть "domain": "icloud.com" під час створення замовлення (для Gmail поле не вказуйте; наявним ботам нічого змінювати не потрібно). Якщо сервіс не підтримує iCloud або iCloud тимчасово вимкнено, ви отримаєте DOMAIN_UNAVAILABLE: перейдіть на Gmail, і оренда одразу пройде. Життєвий цикл, правила скасування й повернення коштів та спосіб читання кодів цілком такі самі, як для Gmail.
  • Сервіси власного складу (provider = "inventory", напр. Cointiply, див. GET /v1/services) працюють лише з iCloud; кожен лист надходить як посилання в otp[].code разом із kind, label і повним текстом листа в text. Замовлення отримує до rules.maxCodes листів протягом rules.windowMinutes хв (до windowEndsAt), його не можна скасувати (ORDER_NOT_CANCELLABLE), а якщо час минув без листа, воно стає cancelled без повернення коштів. Щоб і далі отримувати на тій самій скриньці, викличте POST /v1/orders/{id}/rerent, поки canRerent дорівнює true (ціна: rerentPriceVnd). Усі інші сервіси / замовлення мають provider = "standard" — з 2026-10-24 provider має лише два значення: "standard" | "inventory" (фактичний склад — у warehouse); порівнюйте лише з "inventory".
  • Замовлення складу 2 (warehouse = 2): коди безкоштовні fee.freeHours год; коли безкоштовне вікно закривається, нові коди перестають надходити — викличте POST /v1/orders/{id}/next-code з confirmFee = true (сплативши nextCodeFee.feePriceVnd), щоб відкрити ще одне вікно, до nextCodeFee.hardUntil. Замовлення складу 3 для звичайних сервісів: безкоштовні коди 24 години, скасування можливе до надходження коду, потім використовуйте rerent. Замовлення складу 4: нові коди потрапляють в otp[] під час читання замовлення, безкоштовно до rentExpiresAt; для джерела з одним кодом nextCodeBlockReason після першого коду стає "max_codes".
  • Багато замовлень одночасно? Опитуйте до 100 за виклик через POST /v1/orders/status — див. розділ Статус багатьох замовлень за один виклик.

Ліміти запитів

Ліміти діють на кожен ключ API (акаунт може мати власні ліміти; інакше діють типові ліміти сайту):
  • 100 запитів/секунду — короткі сплески протягом кількох секунд
  • 3000 запитів/хвилину — загальний трафік за хвилину
Перевищення ліміту повертає HTTP 429 із заголовком Retry-After: <seconds> і тілом {"success":false,"error":{"code":"RATE_LIMITED",...}}. Зачекайте кількість секунд, указану в заголовку, перш ніж повторювати. Тіло помилки містить те саме число секунд у error.retryAfterSec (разом з error.retryable = true).

Коди помилок

Кожна помилка має однакову форму: {"success":false,"error":{"code":"...","message":"...","retryable":false,"retryAfterSec":null}}
З 2026-10-17 кожна помилка /v1 має ще error.retryable і error.retryAfterSec (додані поля — наявним клієнтам нічого змінювати не треба; details не змінюється). retryable = true ⇒ той самий виклик може вдатися пізніше: зачекайте retryAfterSec секунд (ціле число ≥ 1) і надішліть його знову — немає в наявності / немає скриньок / склад призупинено / помилка постачальника ⇒ 5 с; 429 RATE_LIMITED ⇒ заголовок Retry-After; 409 DUPLICATE_REQUEST, поки перший запит із тим самим Idempotency-Key ще виконується ⇒ 2 с. retryable = false (retryAfterSec = null) ⇒ повторний виклик не допоможе, доки ви не усунете причину (баланс, ліміт очікувальних замовлень, параметри, ключ API…). partial.reason у POST /v1/orders дотримується тих самих правил. У разі відповіді 409 «немає в наявності» (OUT_OF_STOCK, WAREHOUSE_UNAVAILABLE, ALL_WAREHOUSES_EXHAUSTED) зачекайте повні retryAfterSec секунд перед повтором — раніший повтор зазвичай повертає ту саму відповідь — і перед новою орендою перевірте stock / offers[].stock у GET /v1/services; за вже орендованими замовленнями стежте через вебхуки, а не частим опитуванням.
Приклади відповідей з помилкою
HTTP/1.1 409 Conflict
{
  "success": false,
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "This service is currently out of stock",
    "retryable": true,
    "retryAfterSec": 5
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 1
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded, retry after 1s",
    "retryable": true,
    "retryAfterSec": 1
  }
}

HTTP/1.1 402 Payment Required
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to rent an inbox",
    "retryable": false,
    "retryAfterSec": null
  }
}
Код помилкиHTTPretryable · retryAfterSecЗначення
UNAUTHORIZED401false · nullКлюч API недійсний або відсутній.
ACCOUNT_LOCKED403false · nullАкаунт заблоковано: усі запити з його ключем відхиляються. Зверніться до підтримки.
FORBIDDEN403false · nullАкаунт перестав бути активним, поки обробляли оренду (його щойно заблокували).
NOT_FOUND404false · nullУ вашому акаунті немає замовлення / партії / скриньки з таким ID (замовлення іншого акаунта також повертають 404).
VALIDATION_ERROR400false · nullПараметри запиту недійсні (неправильний тип, відсутнє обов'язкове поле тощо).
INSUFFICIENT_BALANCE402false · nullБаланс акаунта замалий, щоб оплатити замовлення.
SERVICE_DISABLED409false · nullКоду сервісу не існує або сервіс тимчасово вимкнено. Візьміть точний код із GET /v1/services.
OUT_OF_STOCK409true · 5У сервісу немає вільних скриньок (для обраного типу скриньки) на момент запиту.
DOMAIN_UNAVAILABLE409false · nullСервіс не пропонує обраний тип скриньки: iCloud ще не підтримується / тимчасово вимкнений, або в сервісу немає скриньок gmx.com. Надішліть domain "gmail.com" (або не вказуйте поле), щоб орендувати Gmail.
WAREHOUSE_UNAVAILABLE409true · 5 / falseОбраний склад не продає цей сервіс/тип скриньки, призупинений або щойно вичерпався. Оберіть інший склад з offers[] або надішліть warehouse = 99, щоб система обрала склад із наявністю. Якщо цей склад (або всі склади, що продають цей сервіс) недоступний для вашого акаунта, retryable = false — повторний виклик не допоможе, використайте інший склад.
ALL_WAREHOUSES_EXHAUSTED409true · 5Лише з warehouse = 99: перебрано всі склади з наявністю (від найдешевшого), і на всіх немає наявності або вони дають збій — або всі склади повідомляють про нульову наявність. Нічого не списано; спробуйте пізніше.
NO_MAILS_AVAILABLE503true · 5У постачальника не лишилося скриньок для цього сервісу (тимчасово немає).
QUANTITY_EXCEEDED400false · nullquantity перевищує максимум на запит (наразі 200).
WAITING_LIMIT_REACHED429false · nullЗабагато замовлень одночасно очікують на код (понад ліміт одночасних замовлень waiting_code вашого акаунта): зачекайте, поки частина завершиться, і орендуйте знову.
ORDER_NOT_CANCELLABLE409false · nullЗамовлення не можна скасувати: можливо, воно вже має код або більше не має статусу waiting_code. next-code також повертає цей код, коли замовлення ще не отримало свого першого коду.
RERENT_NOT_AVAILABLE409false · nullЗамовлення не можна орендувати знову. Склад 3: це не останнє замовлення скриньки, скриньку більше не закріплено за вашим акаунтом або попереднє вікно отримання ще відкрите. Склад 2: замовлення ще не закрите (воно ще може отримувати коди: скористайтеся next-code), воно надто старе для повторної оренди, у email є інше активне замовлення або сервіс призупинено. Склади 1 і 4 не мають повторної оренди.
RERENT_EMAIL_BANNED409false · nullПовторна оренда складу 2: постачальник повідомляє, що email заблоковано сервісом (email banned): його не можна орендувати знову; кошти не списуються.
RERENT_MAIL_GONE409false · nullПовторна оренда складу 2: постачальник більше не може відкрити цей email — орендуйте новий; кошти не списуються.
NEXT_CODE_FEE_CONFIRM409false · nullБезкоштовне вікно замовлення складу 2 закінчилося: викличте next-code знову з confirmFee: true, щоб сплатити плату (nextCodeFee.feePriceVnd). Нічого не списано.
EMAIL_BANNED409false · nullEmail заблоковано сервісом (постачальник повідомляє email banned): він не може отримувати більше кодів; орендуйте новий. З 2026-10-02 (раніше було ORDER_EXPIRED, той самий HTTP 409).
ORDER_EXPIRED409false · nullЗамовлення не може отримувати більше кодів: його термін минув (rentExpiresAt / nextCodeFee.hardUntil), постачальник закрив скриньку, ліміт кодів (maxCodes) вичерпано або в сервісу немає «наступного коду». Причина вказана в order.nextCodeBlockReason.
RATE_LIMITED429true · = Retry-AfterПонад 100 запитів/секунду або 3000 запитів/хвилину на ваш ключ API (акаунт може мати власні ліміти). Заголовок Retry-After повідомляє, скільки секунд чекати. На складі 2 POST /v1/orders і /rerent також повертають цей код, коли акаунт за останні 60 хвилин скасував багато замовлень складу 2 без коду, а код отримали лише небагато: оренда зі складу 2 призупиняється, доки частка скасувань не знизиться ("warehouse": 99 теж зупиняється там із цією помилкою — тим часом оберіть інший склад). Facebook / Instagram (fb, fbb, ig) — виняток.
DUPLICATE_REQUEST409true · 2 / falseIdempotency-Key уже використовувався з іншими даними або іншим ендпоінтом, або перший запит із цим ключем ще виконується (повторіть за мить). Створіть новий ключ, щоб зробити ще одне замовлення.
PROVIDER_ERROR502true · 5Помилка від постачальника скриньок (тимчасова: повторіть через кілька секунд).
MAINTENANCE503false · nullСистема на технічному обслуговуванні: створення й скасування замовлень призупинено.
MAILSHOP_DISABLED503false · nullКупівлю короткочасних Gmail призупинено або цей продукт вимкнено: спробуйте пізніше.
MAILSHOP_PRODUCT_NOT_FOUND404false · nullПродукту з таким кодом немає: візьміть точний код із GET /v1/mail-shop/products.
MAILSHOP_OUT_OF_STOCK409false · nullНедостатньо в наявності для цієї кількості за поточною ціною: error.details.stock = скільки акаунтів можна купити зараз.
MAILSHOP_QTY_LIMIT400false · nullquantity перевищує максимум на замовлення (наразі 500): error.details.max.
MAILSHOP_SUPPLIER_ERROR502false · nullДжерело одразу відмовило в купівлі: невдале замовлення записано, а гроші повернено (error.details.orderId). Спробуйте пізніше з новим Idempotency-Key.
PROXY_DISABLED503false · nullРозділ проксі або цей склад проксі тимчасово закритий — спробуйте пізніше.
PROXY_PLAN_NOT_FOUND404false · nullТарифу немає або він зараз не продається — знову прочитайте GET /v1/proxy/catalog.
PROXY_OUT_OF_STOCK409true · 5Недостатньо проксі для цієї кількості — error.details.stock = скільки можна купити зараз (якщо замовлення вже оплачене, за error.details.orderId зроблено повернення).
PROXY_QTY_LIMIT400false · nullКількість більша за максимум на замовлення — error.details.max.
PROXY_SUPPLIER_ERROR502true · 5Проксі не вдалося видати: замовлення не виконане, за невидану частину зроблено повернення (error.details.orderId). Повторіть з новим Idempotency-Key.
PROXY_ITEM_NOT_FOUND404false · nullЦього проксі немає у вашому акаунті.
PROXY_NOT_ELIGIBLE409false · nullЦя дія недоступна для цього проксі (інший склад, замінений, відкликаний або прострочений) — error.details.reason.
PROXY_IP_ALIVE409false · nullЗміну IP відхилено: поточна IP ще працює (змінити можна лише мертву IP).
PROXY_WARRANTY_EXPIRED409false · nullГарантія проксі закінчилася.
PROXY_UNAVAILABLE503true · 5Сервіс проксі тимчасово недоступний — нічого не списано (або повернено); повторіть за кілька секунд.
INTERNAL500false · nullНеочікувана помилка сервера: спробуйте пізніше; якщо вона повторюється, зверніться до підтримки.

Вебхуки (push-сповіщення)

Зареєструйте один URL на акаунт, і ми надсилатимемо на нього підписану JSON-подію методом POST, щойно замовлення отримає новий код (order.code) або його буде скасовано / відшкодовано (order.cancelled). Вебхуки необов'язкові й охоплюють усі замовлення акаунта (веб і API). Доставка — за принципом «найкращої спроби»: залиште рідке опитування як запасний варіант (див. нижче).
Налаштування за 3 кроки
  1. PUT /v1/webhook із вашим URL (і за бажанням events) — збережіть data.secret (64 шістнадцяткові символи): він потрібен для перевірки кожної доставки. Повторний виклик PUT зберігає той самий secret.
  2. POST /v1/webhook/test — ми одразу надсилаємо подію ping і повертаємо, що відповів ваш сервер (ok, httpStatus, error).
  3. Ваш ендпоінт має відповісти будь-яким 2xx протягом 5 секунд — спершу відповідайте, потім обробляйте подію. Усе інше (3xx, 4xx, 5xx, тайм-аут, помилка з'єднання) вважається невдачею та повторюється.
URL має починатися з http:// або https:// (з дійсним сертифікатом) і бути доступним з інтернету: localhost, приватні, link-local, multicast і зарезервовані адреси (10.x, 172.16–31.x, 192.168.x, 169.254.x, fc00::/7, fe80::/10…) та власні сервери Почта відхиляються з VALIDATION_ERROR. Ім'я хоста повторно розв'язується перед кожною доставкою. Перенаправлення не виконуються — реєструйте кінцевий URL.
Формат запиту
Кожна доставка — це HTTP-запит POST на ваш URL з тілом JSON (UTF-8) і такими заголовками:
ЗаголовокЗначення
Content-Typeapplication/json
User-AgentПочта-Webhook/1
X-Почта-EventНазва події: order.code, order.cancelled або ping
X-Почта-DeliveryУнікальний ID події (UUID) — збігається з deliveryId у тілі й не змінюється під час повторів
X-Почта-TimestampUnix-час (секунди) підпису цієї спроби — збігається з sentAt у тілі
X-Почта-Signaturesha256= + hex у нижньому регістрі від HMAC-SHA256 над timestamp + "." + сире тіло з ключем — вашим secret
Перевірка підпису
Обчисліть HMAC-SHA256 з вашим secret як ключем над X-Почта-Timestamp + . + сирим тілом запиту у вигляді hex у нижньому регістрі та порівняйте зі значенням після sha256= за сталий час. Ключ — сам рядок secret із 64 символів (його байти UTF-8, не декодуйте hex). Використовуйте сирі байти: розбір і повторна серіалізація JSON змінюють їх. Відхиляйте мітки часу, що відрізняються від вашого годинника більш ніж на 5 хвилин (захист від повторів).
Приклади приймача (Python і Node використовують лише стандартну бібліотеку; команда curl надсилає на ваш приймач правильно підписану тестову доставку)
# Локальний тест: надішліть своєму приймачу доставку, підписану точно так, як наша
SECRET="9f2c6d1e8b7a4f3c5e0d2b1a6c9e8f7d3b5a1c2e4f6a8b0d9c7e5f3a1b2c4d6e"
TS=$(date +%s)
BODY='{"event":"ping","deliveryId":"6f1d2c3b-8a9e-4f70-b1c2-d3e4f5a6b7c8","sentAt":'$TS'}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST "http://localhost:8080/" \
  -H "Content-Type: application/json" \
  -H "X-Почта-Event: ping" \
  -H "X-Почта-Delivery: 6f1d2c3b-8a9e-4f70-b1c2-d3e4f5a6b7c8" \
  -H "X-Почта-Timestamp: $TS" \
  -H "X-Почта-Signature: sha256=$SIG" \
  -d "$BODY"
Події
ПодіяКоли надсилається
order.codeЗамовлення отримало новий код — одна подія на кожен код, зокрема наступні коди на тій самій скриньці. code — новий код; otp перелічує всі коди замовлення на цей момент, від старих до нових (як у GET /v1/orders/{id}; лише новий код, якщо тіло перевищило б 64 КБ).
order.cancelledЗамовлення скасовано або відшкодовано — один раз на замовлення: код не надійшов до терміну (timeout), скасовано вами (user) чи адміністратором (admin), або відшкодовано через збій складу (provider). refundVnd = сума у VND, повернена на баланс (0, якщо правила сервісу не передбачають повернення).
pingЛише від POST /v1/webhook/test.
Поля події
ПолеТипОпис
eventstringНазва події (також у заголовку X-Почта-Event)
deliveryIdstringУнікальний ID події (UUID, = X-Почта-Delivery) — збережіть, щоб пропускати дублікати
sentAtnumberUnix-час цієї спроби (= X-Почта-Timestamp)
orderIdstringID замовлення — той самий, що в GET /v1/orders/{id}
servicestringКод сервісу
warehouse1 | 2 | 3 | 4 | nullСклад 1–4, що видав скриньку; null, якщо замовлення так і не отримало скриньку
domainstringДомен скриньки: gmail.com, icloud.com або gmx.com
emailstring | nullАдреса орендованої скриньки
codestringЛише order.code: новий код — може бути й посиланням або повним листом, як otp[].code
receivedAtnumberЛише order.code: Unix-час надходження коду
statusstringСтатус замовлення на цей момент: completed для order.code, cancelled для order.cancelled (якщо адміністратор відшкодовує замовлення, що вже має коди, статус лишається completed)
otparrayЛише order.code: усі коди на цей момент, [{code, receivedAt}], від старих до нових
reasonstringЛише order.cancelled: timeout | user | admin | provider
refundVndnumberЛише order.cancelled: VND, повернені на баланс (0 = без повернення)
nextCodeBlockReasonstringЛише order.cancelled і лише коли скринька більше не може отримувати коди: email_banned | activation_gone | hard_expired | max_codes (як у GET /v1/orders/{id}). У замовлення, завершеного достроково через блокування / зникнення скриньки, reason лишається timeout і є це поле; при звичайному тайм-ауті поля немає
Приклад тіла — order.code
{
  "event": "order.code",
  "deliveryId": "6f1d2c3b-8a9e-4f70-b1c2-d3e4f5a6b7c8",
  "sentAt": 1760700125,
  "orderId": "k3m9x2p7q1w8e5r4",
  "service": "fb",
  "warehouse": 1,
  "domain": "gmail.com",
  "email": "[email protected]",
  "code": "482913",
  "receivedAt": 1760700124,
  "status": "completed",
  "otp": [
    {
      "code": "482913",
      "receivedAt": 1760700124
    }
  ]
}
Приклад тіла — order.cancelled
{
  "event": "order.cancelled",
  "deliveryId": "0b7e4c2a-5d1f-4e8b-9a3c-2f6d8e1b4a7c",
  "sentAt": 1760701630,
  "orderId": "p8v2n5c1x7z3m9k4",
  "service": "ig",
  "warehouse": 2,
  "domain": "gmail.com",
  "email": "[email protected]",
  "reason": "timeout",
  "refundVnd": 1500,
  "status": "cancelled"
}
Приклад тіла — ping
{
  "event": "ping",
  "deliveryId": "3c9a1e7f-2b4d-4c6e-8f0a-5d7b9c1e3a2f",
  "sentAt": 1760700000
}
Повтори, пауза та історія
  • Невдала доставка повторюється через 10 с, 1 хв, 5 хв, 30 хв і 2 год (5 повторів); якщо й останній повтор невдалий, подію відкидають (failed).
  • 50 невдалих спроб поспіль (за всіма подіями) ставлять вебхук на паузу: GET /v1/webhook показує pausedAt, нічого не надсилається, нові події не стають у чергу.
  • Щоб відновити: знову викличте PUT /v1/webhook (можна з тим самим URL) або виконайте успішний POST /v1/webhook/test — після цього події з черги буде надіслано.
  • GET /v1/webhook/deliveries показує останні 100 доставок зі статусом, кількістю спроб і останньою помилкою; історія зберігається 7 днів.
Дублікати й порядок
Та сама подія може прийти кілька разів (наприклад, якщо ваша відповідь 2xx загубилася), а події можуть приходити не за порядком (кілька надсилаються паралельно). Зберігайте оброблені deliveryId і пропускайте повтори; для замовлення спирайтеся на його найсвіжіші дані (otp, status), а не на порядок надходження.
Опитування як запасний варіант
Вебхуки можуть затримуватися (повтори) або губитися (вебхук на паузі, ваш сервер недоступний). Залиште рідке опитування — наприклад, GET /v1/orders/{id} кожні 30–60 с для замовлень, які ще в waiting_code, — і вважайте об'єкт замовлення з API джерелом істини.
PUT/v1/webhook
Реєструє або оновлює вебхук акаунта. Перший виклик створює його й повертає новий secret; наступні виклики зберігають secret, знову вмикають вебхук і відновлюють його, якщо він був на паузі. Без events: обидві події для нового вебхука, без змін для наявного. URL має бути публічною адресою — інакше 400 VALIDATION_ERROR (причина в error.details.problem).
Параметри
НазваТипОбов'язковийОпис
urlstringТакВаш ендпоінт (http:// або https://, публічна адреса, не більше 2048 символів)
eventsstring[]НіЯкі події надсилати: ["order.code", "order.cancelled"] (за замовчуванням обидві)
Приклад
# Збережіть data.secret — він потрібен для перевірки кожної доставки
curl -X PUT "https://onemail.wtf/v1/webhook" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example/otpgmail-webhook","events":["order.code","order.cancelled"]}'
Приклад відповіді
{
  "success": true,
  "data": {
    "url": "https://your-server.example/otpgmail-webhook",
    "events": [
      "order.code",
      "order.cancelled"
    ],
    "enabled": true,
    "secret": "9f2c6d1e8b7a4f3c5e0d2b1a6c9e8f7d3b5a1c2e4f6a8b0d9c7e5f3a1b2c4d6e",
    "pausedAt": null,
    "consecutiveFailures": 0,
    "createdAt": 1760699000,
    "updatedAt": 1760699000
  }
}
Можливі помилки: UNAUTHORIZED, VALIDATION_ERROR
GET/v1/webhook
Вебхук вашого акаунта, зокрема secret, pausedAt і consecutiveFailures. data дорівнює null, якщо вебхук не зареєстровано.
Приклад
curl "https://onemail.wtf/v1/webhook" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "url": "https://your-server.example/otpgmail-webhook",
    "events": [
      "order.code",
      "order.cancelled"
    ],
    "enabled": true,
    "secret": "9f2c6d1e8b7a4f3c5e0d2b1a6c9e8f7d3b5a1c2e4f6a8b0d9c7e5f3a1b2c4d6e",
    "pausedAt": 1760705400,
    "consecutiveFailures": 50,
    "createdAt": 1760699000,
    "updatedAt": 1760705400
  }
}
Можливі помилки: UNAUTHORIZED
DELETE/v1/webhook
Видаляє вебхук; події, що чекають у черзі, відкидаються. Завжди 200 — data.deleted дорівнює false, якщо видаляти не було чого.
Приклад
curl -X DELETE "https://onemail.wtf/v1/webhook" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "deleted": true
  }
}
Можливі помилки: UNAUTHORIZED
POST/v1/webhook/test
Одразу надсилає подію ping на ваш URL і повідомляє результат: ok (ваш сервер відповів 2xx), httpStatus, durationMs, error. Успішний тест відновлює вебхук на паузі. Не більше 10 тестів на хвилину; 503 MAINTENANCE, поки вебхуки вимкнено в усій системі.
Приклад
curl -X POST "https://onemail.wtf/v1/webhook/test" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": {
    "ok": true,
    "httpStatus": 200,
    "durationMs": 143,
    "error": null,
    "deliveryId": "3c9a1e7f-2b4d-4c6e-8f0a-5d7b9c1e3a2f"
  }
}
Відповідь 200, коли ваш сервер не відповідає 2xx
{
  "success": true,
  "data": {
    "ok": false,
    "httpStatus": 500,
    "durationMs": 88,
    "error": "HTTP 500",
    "deliveryId": "7d2b9f4e-1c6a-4e3b-8d5f-0a9c2e7b1f4d"
  }
}
Можливі помилки: UNAUTHORIZED, NOT_FOUND, RATE_LIMITED, MAINTENANCE
GET/v1/webhook/deliveries
Останні доставки, спершу нові (зберігаються 7 днів): status = queued (наступна спроба в nextAt) | delivered | failed | paused, з attempts, lastHttpStatus і lastError. Тіла подій не повертаються.
Параметри
НазваТипОбов'язковийОпис
limitnumberНіКількість доставок, 1–100 (за замовчуванням 100)
Приклад
curl "https://onemail.wtf/v1/webhook/deliveries?limit=20" \
  -H "Authorization: Bearer og_xxx..."
Приклад відповіді
{
  "success": true,
  "data": [
    {
      "id": "0b7e4c2a-5d1f-4e8b-9a3c-2f6d8e1b4a7c",
      "event": "order.cancelled",
      "orderId": "p8v2n5c1x7z3m9k4",
      "status": "queued",
      "attempts": 1,
      "lastHttpStatus": 503,
      "lastError": "HTTP 503",
      "nextAt": 1760701640,
      "createdAt": 1760701630,
      "deliveredAt": null
    },
    {
      "id": "6f1d2c3b-8a9e-4f70-b1c2-d3e4f5a6b7c8",
      "event": "order.code",
      "orderId": "k3m9x2p7q1w8e5r4",
      "status": "delivered",
      "attempts": 1,
      "lastHttpStatus": 200,
      "lastError": null,
      "nextAt": null,
      "createdAt": 1760700124,
      "deliveredAt": 1760700125
    }
  ]
}
Можливі помилки: UNAUTHORIZED