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 documentation

Public API /v1 — authenticate with an API key and automate inbox rentals from your own software

Your API key
You are not logged in — log in to get your own API key.
Send this key in the Authorization: Bearer <key> header or the ?api_key=<key> query parameter. Click the eye icon to reveal the full key; click Generate new key when you need to replace it (the old key stops working immediately).

Overview

Base URL
https://onemail.wtf
Authentication
Add your API key to every request, either in the Authorization: Bearer og_xxx... header (recommended) or in the ?api_key=og_xxx... query string.
Idempotency-Key (prevents duplicate orders)
Every POST /v1/orders request should include the Idempotency-Key: <new UUID per order> header. If the request times out or the connection drops, send it again with the same key — the server returns the original response instead of creating another order. Generate a new UUID for each new order and reuse a UUID only when retrying.
Many orders at once: bulk status
Renting tens or hundreds of inboxes? Read them in bulk: POST /v1/orders/status returns up to 100 orders per call (one request against your rate limit), and GET /v1/orders lists your orders — after a restart, ?status=waiting_code gives back every order still waiting for a code. Every error also says whether to retry (error.retryable, error.retryAfterSec). Details: the Bulk status section.
Inbox type: Gmail or iCloud
By default you get an @gmail.com inbox. To rent an @icloud.com inbox, add "domain": "icloud.com" to the POST /v1/orders body. Omitting domain means gmail.com — existing integrations keep working without changes. iCloud is available only for services whose icloud field is not null in GET /v1/services; the iCloud price may differ from the Gmail price (see icloud.price). Every order response includes a domain field that tells you which inbox type the order uses. Some services also offer @gmx.com inboxes (currently only Pokemon, code pkm, warehouse 2): send "domain": "gmx.com" — a service offers it when its offers[] in GET /v1/services has an entry with domain = "gmx.com"; any other service ⇒ DOMAIN_UNAVAILABLE. gmx.com is not available for batches.
Warehouses: one service, several inbox sources
A service can be sold from several warehouses, each with its own price, stock and code rules (the offers[] array in GET /v1/services). Send "warehouse": 2 when creating an order to pick one; "warehouse": 99 ⇒ the system picks the cheapest warehouse with stock and moves on to the next one if it runs out (ideal for services that often run out, such as Facebook and Instagram); 0 ⇒ the cheapest warehouse with stock. Existing clients need no changes: omit warehouse ⇒ warehouse 1 as before, and price, stock and icloud describe warehouse 1 (services without warehouse 1 ⇒ the cheapest warehouse with stock). Details: see Warehouses.
Bulk rental (batches)
Batches are bought on the web (the Bulk rental page); the API lets you list batches and read codes. Gmail (Warehouse 1): every inbox has a proxyUrl — a code link that needs no API key. iCloud (Warehouse 3): private inboxes; read codes with GET /v1/batches/{id}/mails/{mailId}/codes or open readUrl on the web. Details: the Bulk rental section.
Buy short-lived Gmail accounts (mail shop)
Besides renting inboxes, you can buy whole Gmail accounts from the mail-shop warehouses — warehouse 1: email, password, cookies + an inbox link (also as JSON); warehouse 2: email, password + a quick login link; warehouse 99 picks the cheapest one first (the Buy short-lived Gmail page on the web). The API does everything that page does: see warehouses, prices and stock, buy (Idempotency-Key required), follow the delivery, download the accounts and read their emails. Details: the Buy live Gmail accounts section.
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
Let your customers read codes themselves (the /otp page)
Reselling inboxes you rented (on the web or through the API)? Turn on a share code on your Account page, then send your customer the link https://onemail.wtf/en/otp#k7m2q9:[email protected] (k7m2q9 = your share code) — they see the latest codes of that email without logging in and never see prices or your balance; the page only performs free actions (it never charges you).
JSON link for tools / bots (yours or your customer's): take the path-style link https://onemail.wtf/en/otp/k7m2q9:[email protected] (it opens the /otp page just like the # link) and add ?json ⇒ the server returns JSON with exactly what the page shows: cards[] — one card per service rented on that email (email, serviceName, state, items[] = up to 5 latest codes / links, newest first) — plus serverTime. state: waiting for the first code · listening waiting for a new code · received has codes · needs_owner the seller must extend it · expired · banned inbox locked. Several emails: separate them with commas (up to 50). No API key, no cookies, CORS is open; read-only (“Load new OTP” / “Rent this email again” stay on the /otp page). Same anti-guessing limits as the page: wrong code / no order to show for the email ⇒ 404 NOT_FOUND; repeated misses or more than 30 reads per minute for one email ⇒ 429 RATE_LIMITED with retryAfter (seconds). Adding ?json to a /otp#… link does NOT return JSON: browsers never send the part after # to the server.
curl "https://onemail.wtf/en/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
  }
}
Complete sample code on GitHub
Ready-to-run clients for Python, Node.js, PHP, C# (.NET) and curl — rent an inbox, wait for the code, cancel automatically for a refund, and switch between iCloud and Gmail when stock runs out: github.com/letoan0902/otpgmail-email-otp-api (English) · thue-otp-gmail (Vietnamese). Python note: use requests rather than bare urllib (its default User-Agent gets a 403 from the CDN).
Webhooks
Instead of polling every order, register one URL and receive a signed POST as soon as an order gets a new code or is cancelled / refunded — see Webhooks.

Endpoints

GET/v1/balance
Returns the account balance (in VND) for the API key used in the request.
Example
curl "https://onemail.wtf/v1/balance" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "success": true,
  "data": {
    "balance": 25000
  }
}
Possible errors: UNAUTHORIZED
GET/v1/services
Lists the enabled services — code, name, Gmail price (in VND) and current Gmail stock, an icloud block with the price and stock for @icloud.com inboxes, and an offers[] array: every warehouse selling the service, one entry per warehouse × inbox type (price, stock, number of codes, rules). The data is cached: stock is refreshed about every 30–60 seconds, prices less often.
icloud = null means the service does not support iCloud yet (the provider does not offer it, or it is temporarily disabled) — only Gmail can be rented. For services with an icloud block, send "domain": "icloud.com" when creating the order to get an @icloud.com inbox at icloud.price. price / stock / icloud.price describe warehouse 1 — where orders without warehouse go (services without warehouse 1 ⇒ the cheapest warehouse with stock); per-warehouse prices and stock are in offers[] (see Warehouses). stock is the number the source publishes (warehouse 1: refreshed about every 30 seconds), not a promise that one call can rent that many: inboxes are allocated one at a time and the source can run out midway — POST /v1/orders then returns fewer orders plus a partial field. Warehouses 2 and 4 likewise show their sources' numbers.
Example
curl "https://onemail.wtf/v1/services" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
    }
  ]
}
Possible errors: UNAUTHORIZED
POST/v1/orders
Creates an order for an inbox that receives verification codes — Gmail by default, or iCloud when you send domain: "icloud.com". Your balance is charged as soon as the provider allocates the inbox. Returns a list of orders (one, or several when quantity > 1).
Partial delivery: quantity is a maximum
  • Inboxes are allocated one at a time. If the provider runs out midway (for example, warehouse 1 has no more inboxes for that service at that moment), the call stops and returns HTTP 200 with the orders created so far — data can be shorter than quantity, and you are charged only for the orders in data. The stock in GET /v1/services does not promise how many one call will get.
  • The response then also carries a top-level partial field next to data (absent when everything was delivered, so bots that only read data keep working): requested, delivered, missing and reason = {code, message, retryable, retryAfterSec}, where code is the error that stopped the call (NO_MAILS_AVAILABLE, OUT_OF_STOCK, ALL_WAREHOUSES_EXHAUSTED, INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED…).
  • Running out is usually temporary — at warehouse 1 the provider often has inboxes again a few seconds later. When reason.retryable = true, wait reason.retryAfterSec seconds (3–5 s), then request the missing inboxes again with a NEW Idempotency-Key (the old key only replays this same response); repeat until you have them all.
  • Right after a partial delivery the next call may return 409 WAREHOUSE_UNAVAILABLE / OUT_OF_STOCK or 503 NO_MAILS_AVAILABLE — that is normal: keep pausing 3–5 s between calls and give up only when many calls in a row fail (for example 10 attempts, about a minute); then try again later, or send "warehouse": 99 to let the system move on to other warehouses. retryable = false (INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED…) ⇒ fix the cause first (top up, or wait for open orders to finish).
  • Error responses carry the same two fields inside error: error.retryable and error.retryAfterSec (for example 409 OUT_OF_STOCK ⇒ true, 5; 402 INSUFFICIENT_BALANCE ⇒ false, null) — see Error codes.
The Idempotency-Key header (a UUID) is required. Generate a new UUID for each new rental; when retrying after a timeout, reuse the SAME key to avoid creating a duplicate order. This call waits for the provider to allocate an inbox, so it usually takes about 0.3 seconds but can take up to 10 seconds at peak times (rare) — set your client timeout to about 15 seconds rather than giving up after 5 seconds and retrying early.
Parameters
NameTypeRequiredDescription
servicestringYesService code (from GET /v1/services, e.g. "ig", "tg", "fb")
quantitynumberNoMAXIMUM number of inboxes to rent (default 1; at most 200 per request) — if the warehouse runs out midway you get fewer: count data[] and read partial
domainstringNoInbox type: "gmail.com" (default), "icloud.com" or "gmx.com". Omitted = gmail.com — existing integrations need no changes. iCloud can be rented only for services whose icloud field is not null in GET /v1/services; "gmx.com" only for services with offers[].domain = "gmx.com" (currently only Pokemon, code pkm) — otherwise the call fails with DOMAIN_UNAVAILABLE. Any other value ⇒ VALIDATION_ERROR.
warehousenumberNoWarehouse to rent from. Omitted = WAREHOUSE 1, exactly as before multi-warehouse (services without warehouse 1 fall back to the cheapest) — existing clients need no changes. 0 = the cheapest warehouse with stock (only one warehouse is tried). 1–4 = that exact warehouse (from offers[].warehouse in GET /v1/services); if it does not sell this service/inbox type, is paused or is out of stock ⇒ WAREHOUSE_UNAVAILABLE. 99 = AUTOMATIC: warehouses with stock are tried from cheapest to most expensive, moving on when one is out of stock or failing; none left ⇒ ALL_WAREHOUSES_EXHAUSTED — recommended for services that often run out (Facebook, Instagram…). See Warehouses.
Example
# Generate a random Idempotency-Key for every NEW order
# REUSE the same key when retrying after a timeout (prevents duplicate orders)
# domain: "gmail.com" (default, optional) | "icloud.com" (rent an @icloud.com inbox) | "gmx.com" (only services offering it, e.g. Pokemon)
# warehouse: 0 | 1–4 | 99 (optional — omit it to keep warehouse 1 as before; 0 = cheapest warehouse with stock; 99 = automatic, moves on when a warehouse runs out; see offers[] in 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"}'
Sample response
{
  "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
    }
  ]
}
Sample response — partial delivery (quantity 5, 2 inboxes delivered)
{
  "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
    }
  }
}
Possible errors: 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}
Returns an order by ID, including the codes received so far (otp[]). Poll this endpoint every 3–5 seconds to pick up the code while the order is in the waiting_code status.
The otp[] array is ordered by arrival: oldest first, NEWEST LAST — read the latest code with otp[otp.length - 1]. On every call the system checks the provider for orders that are still open, at each warehouse's own pace (every few seconds) — calling more often just returns the stored data. After the first code, keep polling: further codes (if the service sends more than one) are appended to the end of otp[] at no extra charge within the order period — the limit and time window are shown before you rent (maxCodes and fee in offers[]); to make sure the system is waiting for a new code, call POST /v1/orders/{id}/next-code (every warehouse; only warehouse 2 outside its free window charges a fee). If the service allows only one code per inbox, otp[] stops at that code — responses stay normal, with no error. The warehouse field tells you which warehouse supplied the inbox (1–4); nextCodeFee is the fee for more codes (warehouse 2 and 3 orders; null for warehouses 1 and 4) — see Warehouses. Since 2026-10-02 orders also carry nextCodeBlocked (true = the inbox cannot receive any more codes) and nextCodeBlockReason — the reason: "email_banned" (the email was locked by the service — rent a new one), "activation_gone" (the provider closed the inbox), "hard_expired" (the code window has ended), "max_codes" (the maximum number of codes was received), null (not blocked / older order with no recorded reason). These are added fields — existing clients need no changes. An order still waiting for its first code whose inbox dies before the deadline (mostly warehouse 2 orders with a long wait) ends early: status "cancelled", fully refunded, nextCodeBlocked = true and nextCodeBlockReason = "email_banned" (the email was locked) or "activation_gone" (the inbox is gone) — rent a new one; an order that simply reached its wait deadline has nextCodeBlockReason = null. Polling many orders? Send up to 100 IDs per call to POST /v1/orders/status instead of one GET per order — same order objects, one request against your rate limit.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (the orderId returned when the order was created)
Example
curl "https://onemail.wtf/v1/orders/ORDER_ID" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
  }
}
Possible errors: UNAUTHORIZED, NOT_FOUND
POST/v1/orders/{id}/cancel
Cancels the order and refunds 100% of the price. Allowed only while the order is in the waiting_code status AND no code has been received.
An order that has received a code (even a single one) cannot be cancelled or refunded — this applies to both the website and the API. Orders with rules.cancellable = false (own-inventory services such as Cointiply) cannot be cancelled: once the inbox is assigned there is no cancellation or refund — the cancel call returns ORDER_NOT_CANCELLABLE. Warehouse-3 orders of regular services (rules.cancellable = true) can be cancelled like any other order before a code arrives.
Parameters
NameTypeRequiredDescription
idstringYesID of the order to cancel
Example
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/cancel" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json"
Sample response
{
  "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
  }
}
Possible errors: UNAUTHORIZED, NOT_FOUND, ORDER_NOT_CANCELLABLE, PROVIDER_ERROR
POST/v1/orders/{id}/rerent
Rents the SAME inbox again for an order of an own-inventory service (provider = "inventory", e.g. Cointiply): creates a NEW order on that inbox with a fresh receiving window, priced at the old order's rerentPriceVnd.
Only works when the old order has canRerent = true (the latest order of that inbox, whose previous window has ended or received all its emails). You are charged as soon as it succeeds — send an Idempotency-Key and reuse it when retrying so you are never charged twice. The response is { order, message }; order has the same shape as GET /v1/orders/{id}. Warehouse 2 (since 2026-10-09): an order that was cancelled, timed out or expired (inbox closed) — call it when canRerent = true (the latest order of that email, and the email has no other active order). The system reopens that EXACT email as a NEW order (status = waiting_code) priced at rerentPriceVnd (currently 100% of your price) and waits 20 minutes for an email like any warehouse 2 order — no email means it is cancelled and refunded 100%. Email locked by the service ⇒ RERENT_EMAIL_BANNED; the provider can no longer reopen it ⇒ RERENT_MAIL_GONE; warehouse 2 temporarily down ⇒ PROVIDER_ERROR — none of the three charges you.
Parameters
NameTypeRequiredDescription
idstringYesID of the inbox's previous order (the one with canRerent = true)
Example
# REUSE the same key when retrying after a timeout (prevents duplicate orders)
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/rerent" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Idempotency-Key: $(uuidgen)"
Sample response
{
  "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"
  }
}
Possible errors: 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
Asks for the next code on the SAME inbox — works for orders from EVERY warehouse (warehouse 1–4) that already received their first code (status = completed). Free, except warehouse-2 orders whose free window has ended (nextCodeFee.feePriceVnd > 0): then send confirmFee: true to pay the fee and open another code window (up to the hard limit nextCodeFee.hardUntil). Your bot does not need to know the warehouse: keep polling GET /v1/orders/{id} — new codes are appended to otp[] — and call this endpoint when you want the system to wait for a new code.
What this call does in each warehouse
  • Warehouse 1: the system waits for the next code by itself after every code within the order period (rentExpiresAt) — the call returns 200 and changes nothing; once the inbox can take no more codes (code limit reached, inbox closed, expired) ⇒ 409 with nextCodeBlockReason.
  • Warehouse 2: reopens the inbox at the provider (reordered = true) and waits 20 minutes for an email; free inside the free window (nextCodeFee.feePriceVnd = 0), outside it you must send confirmFee = true (missing ⇒ 409 NEXT_CODE_FEE_CONFIRM, nothing charged). The fee is kept only if a new code arrives — no code within 20 minutes ⇒ automatic refund. After every code, the system keeps waiting for the next one for 25 more minutes (listening = true, listenUntil).
  • Warehouse 3 (regular services): reopens a short listening window, free inside the free window (nextCodeFee.freeUntil); after it ⇒ 409 — use POST /v1/orders/{id}/rerent. Own-inventory services such as Cointiply (rules.cancellable = false) have no next code (409): every email shows up by itself during the window. Warehouse 3 on Gmail (per service): after each code the system stops waiting — call this to wait for the next one, free until rentExpiresAt (listening = true; calling again while waiting ⇒ 200, nothing changes); expired ⇒ 409 hard_expired, inbox closed ⇒ 409 activation_gone.
  • Warehouse 4: re-reads the order at the provider and waits for a new code, free until rentExpiresAt.
200 = the system is waiting for a new code for this order (listening = true, listenUntil = when it stops; reordered = true when the inbox was just reopened; chargedVnd when a fee was taken), or a new code arrived right as you called (already in order.otp). 409 = no new waiting window could be opened — read error.code; why the inbox takes no more codes is in order.nextCodeBlockReason (GET /v1/orders/{id}). An order still waiting for its first code (waiting_code) ⇒ 409, no need to call yet. Send an Idempotency-Key with paid calls (reuse it when retrying so you are never charged twice). Provider unreachable ⇒ 502 PROVIDER_ERROR, try again later. 409 error codes of this call: NEXT_CODE_FEE_CONFIRM (warehouse 2 needs the fee — call again with confirmFee: true), EMAIL_BANNED (the email was locked by the service — rent a new one; error.details.blockReason = "email_banned"), ORDER_EXPIRED (expired, inbox closed, code limit reached, or the service has no "next code" — the reason is in order.nextCodeBlockReason), ORDER_NOT_CANCELLABLE (the order has not received its first code yet). Bots that treat any 409 from this call as "no more codes" keep working unchanged. refresh: true (warehouse 2): first checks for a new email (one that just arrived is delivered, no reopen), then reopens the inbox at the provider — inside the free window the wait restarts for 20 minutes; outside it the wait keeps its end time (listenUntil) and nothing is charged. The response adds refreshed (true = reopened now) and refreshAvailableAt (unix seconds; before it another refresh only checks for mail; null = allowed now). Other warehouses: no effect (refreshed = false). Without refresh the call behaves exactly as before.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (orderId) — any warehouse
confirmFeebooleanNotrue = you agree to pay nextCodeFee.feePriceVnd to open another code window. Not needed while feePriceVnd = 0.
refreshbooleanNotrue = warehouse 2, the order is waiting for a new code (listening = true) but none arrives: reopen the inbox at the provider right now (refresh the wait) — the old wait may have stopped receiving mail on the provider side. Free; at most once per 5 s per order. Order not waiting ⇒ same as a normal call.
Example
# Free (nextCodeFee is null or feePriceVnd = 0 — every warehouse except warehouse 2 after its free window): no confirmFee needed
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/next-code" \
  -H "Authorization: Bearer og_xxx..."

# Warehouse 2 after its free window: send confirmFee = true to pay 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}'
Sample response
{
  "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
  }
}
Possible errors: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, NEXT_CODE_FEE_CONFIRM, INSUFFICIENT_BALANCE, EMAIL_BANNED, ORDER_EXPIRED, ORDER_NOT_CANCELLABLE, PROVIDER_ERROR, DUPLICATE_REQUEST, MAINTENANCE

Bulk status: many orders per call

Resellers and bots that rent many inboxes should not send one GET /v1/orders/{id} per order: POST /v1/orders/status reads up to 100 orders per call, with the same order objects, and GET /v1/orders lists your orders from stored data.
  • Poll every 3–5 seconds with POST /v1/orders/status, up to 100 order IDs per call — each call counts as one request against your rate limit.
  • Each call checks the provider for at most 20 open orders of the list (orders waiting for their first code first, then the least recently checked) and returns the rest from stored data; those are checked on the next calls. A call answers within about 3 seconds.
  • Drop an order from your list once it is final: cancelled (refunded), or completed when you need no more codes.
  • IDs that do not exist or belong to another account come back in missing (no 404) — drop them too.
  • After a restart, get every open order back with GET /v1/orders?status=waiting_code (follow nextCursor), then resume polling with POST /v1/orders/status.
POST/v1/orders/status
Returns up to 100 of your orders in one call. Each element is exactly what GET /v1/orders/{id} returns for that order (status, otp[] with every code received, warehouse…). Use it to poll many open orders at once.
data keeps the order of ids; duplicate IDs are ignored. IDs that do not exist or belong to another account are listed in missing (no 404). For open orders the system checks the provider just like GET /v1/orders/{id}, but for at most 20 orders per call — those waiting for their first code first, then the least recently checked — and returns the others from stored data (they are checked on the next calls); a call answers within about 3 seconds. One call counts as one request against your rate limit, however many IDs it carries. More than 100 IDs, an empty list or non-string IDs ⇒ 400 VALIDATION_ERROR.
Parameters
NameTypeRequiredDescription
idsstring[]YesOrder IDs (orderId) — 1 to 100 per call
Example
# Order IDs you are waiting on (orderId from POST /v1/orders) — up to 100 per call
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"]}'
Sample response
{
  "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"
  ]
}
Possible errors: UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED
GET/v1/orders
Lists your orders, newest first, from stored data only — it does not ask the provider for new codes (POST /v1/orders/status does). Filter by status and creation time; page with nextCursor.
Pass nextCursor as cursor to get the next page; nextCursor = null ⇒ last page. Pages never repeat or skip an order, even when many orders were created in the same second. Internal states are never listed (only waiting_code, completed, cancelled and queued). After your bot restarts: GET /v1/orders?status=waiting_code&limit=200, follow nextCursor, then poll those orders with POST /v1/orders/status.
Parameters
NameTypeRequiredDescription
statusstringNoOnly this status: waiting_code | completed | cancelled | queued (omitted ⇒ all of them)
sincenumberNoOnly orders created at or after this unix time (seconds)
limitnumberNoOrders per page: 1–200 (default 50)
cursorstringNonextCursor of the previous page, passed unchanged
Example
# After a restart: collect every order still waiting for a code, page by page
curl "https://onemail.wtf/v1/orders?status=waiting_code&limit=200" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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"
}
Possible errors: UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED

Warehouses

Each offers[] entry is one offer = (service, warehouse, inbox type). Only warehouses currently selling are listed; a warehouse that is temporarily out of stock stays in the list with stock = 0. Warehouse numbers are fixed: 1, 2, 3, 4 — pass the same number in the warehouse parameter when creating an order.
Existing clients need no changes. Omit warehouse ⇒ the same behaviour as before (warehouse 1: 25-minute wait, extra codes arrive automatically within the 24-hour order period when the service sends more than one); send 0 ⇒ cheapest warehouse with stock; send 99 ⇒ automatic warehouse, moving on when one runs out (see right below); every existing field stays as it is — only new fields are added (offers[], warehouse, nextCodeFee, listening, nextCodeBlocked…).
Automatic warehouse: warehouse = 99 (recommended for services that often run out)
Send "warehouse": 99 and the system rents from the cheapest warehouse with stock; if that warehouse is out of stock or failing, it moves on to the next one within the same call. Ideal for services that often run out, such as Facebook and Instagram — your bot no longer has to read offers[] and retry warehouse by warehouse.
  • Order tried: price from low to high (e.g. 1,500 → 1,600 → 1,700 VND); equal prices ⇒ lower warehouse number first.
  • Warehouses reporting zero stock (stock = 0 in offers[]) are never called — no time wasted.
  • Moves on when the current warehouse is out of stock or failing (OUT_OF_STOCK, NO_MAILS_AVAILABLE, WAREHOUSE_UNAVAILABLE, PROVIDER_ERROR).
  • Other errors are returned right away, without trying the next warehouse: INSUFFICIENT_BALANCE, WAITING_LIMIT_REACHED, QUANTITY_EXCEEDED, MAINTENANCE, SERVICE_DISABLED, DOMAIN_UNAVAILABLE…
  • quantity > 1: if the first warehouse runs short, the rest comes from the next one — orders may span several warehouses; each order carries the warehouse and price of the warehouse that issued it (and follows that warehouse's code rules).
  • If every warehouse was tried and no inbox could be rented ⇒ ALL_WAREHOUSES_EXHAUSTED (HTTP 409, nothing charged) — try again later. If only some inboxes were rented, you still get 200 with those orders.
Example: rent Facebook Gmail with warehouse = 99
# warehouse: 99 — cheapest warehouse with stock; out of stock or failing ⇒ next warehouse automatically
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[] fields
FieldTypeDescription
warehouse1 | 2 | 3 | 4Warehouse number: 1, 2, 3 or 4.
domainstringInbox type of the offer: gmail.com, icloud.com or gmx.com (extra domain — only some services, currently Pokemon).
pricenumberPrice of one inbox from this warehouse (VND).
stocknumberInboxes left. 0 = out of stock — renting from warehouse 1 or 2 then returns WAREHOUSE_UNAVAILABLE; warehouse 4 is still tried (its sources often deliver although they report 0) and returns OUT_OF_STOCK when nothing is available.
maxCodesnumber | nullMaximum codes one inbox can receive; null = unlimited / unknown (see fee).
rulesobject | nullWindow rules for warehouse 3 (windowMinutes, maxCodes, cancellable, refundOnTimeout, rerentRatio); null for warehouses 1, 2 and 4.
feeobject | nullExtra-code window: freeHours free hours from the rental, then each extension costs paidPct% of the rental price, up to maxHours hours from the rental (null = no limit). fee = null: no fee — extra codes cost nothing within the order period when the service sends more than one (up to maxCodes), as in warehouse 1.
isDefaultbooleantrue for the cheapest warehouse with stock (ties ⇒ lower warehouse number) — the one used with warehouse = 0, and the first one tried with 99.
Rules by warehouse
RuleWarehouse 1Warehouse 2Warehouse 3Warehouse 4
Wait for the first code25 minutes20 minutes25 minutes ¹Up to 25 minutes (shorter at some sources — the real deadline is the order's codeDeadlineAt)
No codeAuto-cancelled, 100% refundAuto-cancelled, 100% refundAuto-cancelled, 100% refund ¹Auto-cancelled, 100% refund
Cancel before a codeYesYesYes ¹Yes
Codes per inboxPer maxCodesUnlimitedUnlimited ¹Per maxCodes (usually null = no limit; 1 for some offers)
More codesNo extra charge within the 24-hour order period if the service sends more codes; automatic (no extra call). The inbox usually stays open about 25 minutes after the latest code.Free for fee.freeHours hours (currently Gmail 6 hours, iCloud 12 hours); then each extension costs fee.paidPct% of the price via next-code, up to fee.maxHours (Gmail 24 hours, iCloud 10 days)No extra charge for 24 hours; then rent the same inbox again (rerent) at 50% of the price; from the 2nd rerent on (at least 20 hours after the previous one) only 25%No extra charge within the 24-hour order period, like warehouse 1 — new codes appear when you read the order; next-code re-reads it right away.
¹ Services sold only from the own inventory, such as Cointiply (provider = "inventory", rules.cancellable = false), follow rules: up to rules.maxCodes emails within rules.windowMinutes minutes, no cancellation, and no refund if time runs out without an email.
Warehouse 3 on Gmail (domain = gmail.com, rules.windowOnly = true): only emails from the rented service itself, sent after you rent. The first code must arrive within rules.windowMinutes minutes (until codeDeadlineAt); no code ⇒ auto-cancel with a 100% refund; cancellable before the first code. After the first code the system stops waiting, but the order stays active until rentExpiresAt: to get another code call POST /v1/orders/{id}/next-code — free until nextCodeFee.freeUntil (each call listens for rules.windowMinutes minutes, listening = true until the new code arrives); after that, until nextCodeFee.hardUntil, each call costs nextCodeFee.feePriceVnd (send confirmFee = true; refunded if no new code arrives in that round), like warehouse 2. After hardUntil ⇒ 409 hard_expired; email no longer usable ⇒ 409 activation_gone (never charged). Once the order has left the active list, canRerent = true ⇒ POST /v1/orders/{id}/rerent rents the same email again for rerentPriceVnd. The Any service (ot) order gets up to the first rules.maxLetters emails sent after you rent (they show up by themselves, no next-code); 0 emails ⇒ 100% refund.
nextCodeFee — fee for more codes (warehouse 2 and 3 orders)
Included in GET /v1/orders/{id} and every order response; null for warehouse 1 and 4 orders (more codes are free). Warehouse 2: call POST /v1/orders/{id}/next-code when you need another code — if feePriceVnd is above 0 you must send confirmFee = true. Warehouse 3 (regular services): once the free window is over, feePriceVnd is the price to rent the same inbox again (rerent).
FieldTypeDescription
feePriceVndnumberAmount charged if you call next-code now; 0 = still inside the free window.
freeUntilnumber | nullEnd of the current free window (unix seconds).
hardUntilnumber | nullHard limit (unix seconds) — no more codes after this time.
paidPctnumber% of the rental price charged for each extra window.
freeHoursnumberFree hours of one code window (warehouse 2: Gmail 6, iCloud 12; warehouse 3: 24).
Example: list the warehouses, then rent from one
# warehouse: 0 | 1–4 | 99 (optional — omit it to keep warehouse 1 as before; 0 = cheapest warehouse with stock; 99 = automatic, moves on when a warehouse runs out; see offers[] in 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}'
Sample warehouse-2 order (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
  }
}

Bulk rental (batches)

Batches are bought on the web (the Bulk rental page) — the API lets you list batches and read codes. The email domain decides the warehouse: Gmail = Warehouse 1, iCloud = Warehouse 3 (private inboxes).
  • A batch is kept for 24 hours from purchase — read codes for free during that time, with no limit on the number of codes.
  • Inboxes that receive no code are not refunded; only a shortfall in quantity is refunded (automatically).
  • Warehouse 1 (Gmail): every inbox has a proxyUrl — a GET returns {"status":1,"code":"482913","all_codes":[...]} with no API key (the link is the secret — keep it private). The code endpoint below works too.
  • Warehouse 3 (iCloud): proxyUrl = null — read codes with the endpoint below or open readUrl (web page). Each inbox is tied to your account for that service; after expiry you can still rent it again on the web.
  • Emails with no extractable code (welcome emails, newsletters…) come back verbatim in code with isRaw: true (HTML or text, up to 20,000 characters).
Fields of an inbox in a batch (mails[])
FieldTypeDescription
idnumberInbox ID — the {mailId} parameter of the code endpoint
emailstringEmail address
urlstringWarehouse 1: = proxyUrl · warehouse 3: = readUrl (kept for older scripts / export files)
proxyUrlstring | nullWarehouse 1: code link that needs no login · warehouse 3: null
readUrlstringWeb page to read the batch's codes
codeCountnumberNumber of codes received
lastCodestring | nullNewest code (raw email: first 300 characters — the full text is on the code endpoint)
lastIsRawbooleantrue = the newest code is a raw email
checkedAtnumber | nullLast time the system checked the provider for this inbox (unix seconds; null = never)
GET/v1/batches
Your batches, newest first (paginated with page / pageSize, up to 100). Each batch has warehouse (1 = Gmail, 3 = iCloud), status (active | expired | failed), expiresAt, codeCount and readUrl.
Parameters
NameTypeRequiredDescription
pagenumberNoPage (default 1)
pageSizenumberNoBatches per page (default 20, max 100)
Example
curl "https://onemail.wtf/v1/batches?page=1&pageSize=20" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
  }
}
Possible errors: UNAUTHORIZED
GET/v1/batches/{id}
One batch with its mails[] — take each inbox id to read its codes.
Gmail batches (warehouse 1): each inbox's proxyUrl works in your scripts exactly as before. iCloud batches (warehouse 3): proxyUrl = null, read codes with the endpoint below. Expired iCloud batches carry rerentPriceVnd — the price to rent one inbox again individually (done on the web). An inbox you have already rented again may carry its own price in mails[].rerentPriceVnd (cheaper from the 2nd rerent on, at least 20 hours after the previous one).
Parameters
NameTypeRequiredDescription
idstringYesBatch ID (shown on the Bulk rental page and in readUrl)
Example
curl "https://onemail.wtf/v1/batches/BATCH_ID" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: UNAUTHORIZED, NOT_FOUND
GET/v1/batches/{id}/mails/{mailId}/codes
Read the codes of one inbox in a batch: the system checks the provider if the inbox is due, then returns EVERY code received, oldest first — the newest code is last in codes[].
Poll every 5–10 seconds while waiting (calling more often just returns the stored data — polledAt does not change). Emails with no extractable code come back verbatim in code with isRaw: true. Expired batches still return their stored codes but are no longer checked.
Parameters
NameTypeRequiredDescription
idstringYesBatch ID
mailIdnumberYesInbox ID (mails[].id)
poll0 | 1No0 = only read stored codes, do not check the provider (default 1)
Example
# Call again every 5–10 seconds while waiting; the newest code is last in codes[]
curl "https://onemail.wtf/v1/batches/BATCH_ID/mails/MAIL_ID/codes" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
    }
  }
}
Possible errors: 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
Signing in to warehouse-1 accounts (no recovery email)
  • Warehouse 1 (gm_cookie) accounts come without a recovery email — you get the email, password, cookies and inbox link (inboxUrl / inboxJsonUrl), nothing more.
  • Recommended way to sign in: import the cookies (cookies, JSON) into a browser — with a cookie-import extension or your antidetect browser's cookie import — then open Gmail: the session is already signed in, usually with no password prompt and no verification.
  • Only need the codes or emails? Read them through inboxUrl (web page) or inboxJsonUrl (JSON) — no API key and no Google sign-in needed.
  • Signing in with the password on a new device or IP can make Google ask for verification (recovery email, phone or a code) — these accounts have nothing to pass it with, so use the cookies or the inbox link instead.
  • Reselling? Give your customers the cookies and the inbox link — the .txt download (GET /v1/mail-shop/orders/{id}/download) has email|password|cookies|inboxUrl on one line — and tell them to sign in with the cookies, not the password.
  • Warehouse 2 (gm_login) accounts come with a quick login link (loginUrl) instead — open it in a desktop browser to sign in.
  • Warehouse 3 (gm_2fa) accounts have 2FA on: sign in with email + password + the 6-digit code from the twofa key (add it to Google Authenticator / a TOTP app) or from twoFaUrl — this works on a phone too; on a computer you can also import the cookies / open loginUrl as for warehouse 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[])
FieldTypeDescription
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
StatusDescription
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.
Example
curl "https://onemail.wtf/v1/mail-shop/products" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
      ]
    }
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
warehousenumberNoMail-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
productstringNoInstead of warehouse: the `code` of a warehouse in GET /v1/mail-shop/products (e.g. gm_cookie, gm_login, gm_2fa)
quantitynumberNoNumber of accounts (default 1)
Example
curl "https://onemail.wtf/v1/mail-shop/quote?warehouse=99&quantity=10" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
warehousenumberNoMail-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
productstringNoInstead of warehouse: the `code` of a warehouse in GET /v1/mail-shop/products (e.g. gm_cookie, gm_login, gm_2fa)
quantitynumberNoNumber of accounts (default 1)
Idempotency-KeystringYesHeader: a new UUID for every new purchase — reuse it only to retry that same purchase
Example
# Idempotency-Key is required: a new UUID per purchase — reuse the same key only to retry after a timeout
# 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}'
Sample response
{
  "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"
      }
    ]
  }
}
Possible errors: 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).
Parameters
NameTypeRequiredDescription
pagenumberNoPage (default 1)
pageSizenumberNoOrders per page (default 20, max 100)
Example
curl "https://onemail.wtf/v1/mail-shop/orders?page=1&pageSize=20" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (data.id returned by the purchase)
Example
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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"
      }
    ]
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (data.id returned by the purchase)
Example
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/download" \
  -H "Authorization: Bearer og_xxx..." \
  -o mail-ORDER_ID.txt
Sample response
email|password|cookies|inboxUrl
[email protected]|Pw7Xq!k3d|[{"domain":".google.com","name":"SID","value":"g.a000…"}]|https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (data.id returned by the purchase)
lineNonumberYesAccount number within the order (items[].lineNo)
maxnumberNoNumber of latest emails: 10 (default), 20, 50, 100 or 200
Example
# 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"
Sample response
{
  "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
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (data.id returned by the purchase)
lineNonumberYesAccount number within the order (items[].lineNo)
Example
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/status" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "success": true,
  "data": {
    "email": "[email protected]",
    "live": true,
    "reason": null,
    "checkedAt": 1760000600
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID (data.id returned by the purchase)
lineNonumberYesAccount number within the order (items[].lineNo)
Example
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/2fa" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "success": true,
  "data": {
    "none": false,
    "code": "424819",
    "expiresIn": 24
  }
}
Possible errors: 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[])
FieldTypeDescription
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
outcomeDescription
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.
Example
curl "https://onemail.wtf/v1/proxy/catalog" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
        }
      }
    ]
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
productIdnumberNoWarehouse 1 — <c>products[].productId</c>
daysnumberNoWarehouse 1 — warranty days 1…<c>warranty.maxDays</c> (default 30)
autoReplacebooleanNoWarehouse 1 — <c>1</c> = with "auto-replace the IP when it dies" (+<c>autoReplace.priceVnd</c> per proxy)
planIdnumberNoWarehouse 2 — plan <c>products[].plans[].id</c> (warehouse 1: the per-day plan is accepted too)
quantitynumberNoNumber of proxies (default 1)
Example
curl "https://onemail.wtf/v1/proxy/quote?productId=5&days=30&autoReplace=1&quantity=5" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
productIdnumberNoWarehouse 1 — <c>products[].productId</c>
daysnumberNoWarehouse 1 — warranty days 1…<c>warranty.maxDays</c> (default 30)
autoReplacebooleanNoWarehouse 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
planIdnumberNoWarehouse 2 — plan <c>products[].plans[].id</c> from the catalog (send <c>productId</c> OR <c>planId</c>)
quantitynumberYesNumber of proxies (≤ <c>maxQuantity</c>)
Idempotency-KeystringYesA new UUID per purchase; reuse it when retrying
Example
# 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}'
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
pagenumberNoPage (from 1)
pageSizenumberNo1–200, default 20
khonumberNo1 | 2
kindstringNo<c>buy</c> | <c>renew</c>
typestringNoType: <c>resident_vn</c> · <c>vip_resident_vn</c> · <c>datacenter_vn</c> · <c>resident_us</c> · <c>datacenter_us</c>
Example
curl "https://onemail.wtf/v1/proxy/orders?page=1&pageSize=20" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
idstringYesOrder ID
Example
curl "https://onemail.wtf/v1/proxy/orders/ORDER_ID" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
viewstringNoFilter (see above)
khonumberNo1 | 2
typestringNoType: <c>resident_vn</c> · <c>vip_resident_vn</c> · <c>datacenter_vn</c> · <c>resident_us</c> · <c>datacenter_us</c>
qstringNoSearch host / user / exit IP / id
orderIdstringNoOnly the proxies of one order
page · pageSizenumberNoPagination (pageSize 1–200)
Example
curl "https://onemail.wtf/v1/proxy/items?view=active&pageSize=100" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
    }
  }
}
Possible errors: 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>).
Parameters
NameTypeRequiredDescription
idstringYesProxy ID
Example
curl "https://onemail.wtf/v1/proxy/items/PROXY_ID" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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": []
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
idsstring[]YesProxy IDs (≤ 200)
Example
curl -X POST "https://onemail.wtf/v1/proxy/items/check" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"]}'
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
idsstring[]YesProxy IDs (≤ 200)
Example
curl -X POST "https://onemail.wtf/v1/proxy/items/warranty" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"]}'
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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").
Parameters
NameTypeRequiredDescription
textstringYesThe list, one proxy per line
Example
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"}'
Sample response
{
  "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
    }
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idsstring[]YesProxy IDs (≤ 200) — e.g. eligibleIds from lookup
Example
curl -X POST "https://onemail.wtf/v1/proxy/items/replace" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["k3m9x2p7q1w8e5r4"]}'
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
idstringYesProxy ID (warehouse 2)
Example
curl -X POST "https://onemail.wtf/v1/proxy/items/PROXY_ID/change-ip" \
  -H "Authorization: Bearer og_xxx..." \
  -H "Content-Type: application/json" \
  -d '{}'
Sample response
{
  "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"
  }
}
Possible errors: 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).
Parameters
NameTypeRequiredDescription
idsstring[]YesProxy IDs (≤ 200, same warehouse)
daysnumberYesWarehouse 1: 1–90 · warehouse 2: 1–365
Example
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}'
Sample response
{
  "success": true,
  "data": {
    "kho": 1,
    "days": 7,
    "items": [
      {
        "id": "k3m9x2p7q1w8e5r4",
        "unitPriceVnd": 200,
        "newEnd": 1795161600
      }
    ],
    "totalVnd": 200,
    "balanceVnd": 250000,
    "enough": true
  }
}
Possible errors: 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.
Parameters
NameTypeRequiredDescription
idsstring[]YesProxy IDs (≤ 200, same warehouse)
daysnumberYes1–365
Example
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}'
Sample response
{
  "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
      }
    ]
  }
}
Possible errors: 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>.
Parameters
NameTypeRequiredDescription
idsstring[]NoProxy IDs (≤ 5,000)
view · kho · typestring · number · stringNoInstead of ids: filters as in GET /v1/proxy/items
formatstringNo<c>colon</c> | <c>at</c> | <c>url</c>
whichstringNoKept 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>
Example
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"}'
Sample response
http://u7hk2m9qzt4w:[email protected]:23817
http://rx7k2m9q:[email protected]:18450
Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLED

Order lifecycle

StatusDescription
Waiting for codeNewly created order, waiting for the first code. Poll GET /v1/orders/{id} every 3–5 seconds.
CompletedThe first code has arrived — the status changes immediately. More codes can still arrive if the service sends more than one (no extra charge within the order period; limit and window per warehouse); keep polling and each new code appears at the end of otp[].
CancelledRefunded 100%. Happens when you call /cancel (before any code arrives), or when no code has arrived by codeDeadlineAt (at most 25 minutes).
Important notes:
  • Poll GET /v1/orders/{id} every 3–5 seconds while the order is waiting_code so you pick up the code promptly.
  • As soon as the first code arrives, the status changes to completed immediately.
  • No code by codeDeadlineAt (at most 25 minutes; warehouse 2: 20 minutes; some warehouse-4 sources are shorter) ⇒ the system cancels the order and refunds 100% (status = cancelled).
  • The otp[] array is ordered oldest first, newest last. Read the latest code with otp[otp.length - 1] (Python: otp[-1]).
  • A completed order keeps receiving codes automatically: keep polling GET /v1/orders/{id} and each new code shows up at the end of otp[]. Extra codes cost nothing within the order period when the service sends more than one; the limit and time window are shown before you rent (maxCodes and fee in offers[]; at warehouse 1 the inbox usually stays open about 25 minutes after the latest code). To ask for another code explicitly (e.g. to log in after signing up): POST /v1/orders/{id}/next-code — works in every warehouse, and only warehouse 2 outside its free window charges a fee.
  • If the service allows only one code per inbox, otp[] stops at that code. Responses stay normal, with no error — you decide when to stop polling.
  • otp[].code is usually a short code (digits / letters) or a link. An email with no extractable code (welcome emails, newsletters, unusual code formats…) is delivered verbatim (HTML or text) in otp[].code — treat it as a full email when it is longer than 80 characters, contains a line break or is HTML, and look for the code or link in it yourself.
  • POST /v1/orders waits for the provider to allocate an inbox, so it usually takes ~0.3 seconds but can take up to 10 seconds at peak times (rare). Set a client timeout of ≈ 15 seconds rather than giving up after 5 seconds and retrying early — and when you do retry, reuse the same Idempotency-Key.
  • An order that has received a code cannot be cancelled or refunded — the cancel call returns ORDER_NOT_CANCELLABLE.
  • To rent an @icloud.com inbox, send "domain": "icloud.com" when creating the order (omit it for Gmail; existing bots need no changes). If the service does not support iCloud, or iCloud is temporarily disabled, you get DOMAIN_UNAVAILABLE — switch to Gmail and the rental goes through right away. The lifecycle, the cancellation and refund rules, and the way you read codes are exactly the same as for Gmail.
  • Own-inventory services (provider = "inventory", e.g. Cointiply — see GET /v1/services) are iCloud-only; each email arrives as a link in otp[].code, together with kind, label and the full email text in text. An order receives up to rules.maxCodes emails within rules.windowMinutes minutes (until windowEndsAt), cannot be cancelled (ORDER_NOT_CANCELLABLE), and if time runs out with no email it becomes cancelled without a refund. To keep receiving on the same inbox, call POST /v1/orders/{id}/rerent while canRerent is true (price: rerentPriceVnd). Every other service / order has provider = "standard" — since 2026-10-24 provider has only two values, "standard" | "inventory" (the actual warehouse is in warehouse); compare with "inventory" only.
  • Warehouse 2 orders (warehouse = 2): codes are free for fee.freeHours hours; once the free window closes, new codes stop arriving — call POST /v1/orders/{id}/next-code with confirmFee = true (paying nextCodeFee.feePriceVnd) to open another window, up to nextCodeFee.hardUntil. Warehouse 3 orders of regular services: free codes for 24 hours, cancellable before a code arrives, then use rerent. Warehouse 4 orders: new codes land in otp[] when you read the order, free until rentExpiresAt; with a single-code source, nextCodeBlockReason becomes "max_codes" after the first code.
  • Many orders at once? Poll up to 100 per call with POST /v1/orders/status — see Bulk status.

Rate limits

Limits apply per API key (an account can have its own limits; otherwise the site default applies):
  • 100 requests/second — short bursts over a few seconds
  • 3000 requests/minute — total traffic per minute
Going over a limit returns HTTP 429 with a Retry-After: <seconds> header and the body {"success":false,"error":{"code":"RATE_LIMITED",...}}. Wait the number of seconds given in the header before retrying. The error body carries the same number of seconds in error.retryAfterSec (with error.retryable = true).

Error codes

Every error has the same shape: {"success":false,"error":{"code":"...","message":"...","retryable":false,"retryAfterSec":null}}
Since 2026-10-17 every /v1 error also has error.retryable and error.retryAfterSec (added fields — existing clients need no changes; details is unchanged). retryable = true ⇒ the same call may succeed later: wait retryAfterSec seconds (a whole number ≥ 1) and send it again — out of stock / no inboxes / warehouse paused / provider error ⇒ 5 s; 429 RATE_LIMITED ⇒ the Retry-After header; 409 DUPLICATE_REQUEST while the first request with the same Idempotency-Key is still running ⇒ 2 s. retryable = false (retryAfterSec = null) ⇒ calling again will not help until you fix the cause (balance, waiting-order limit, parameters, API key…). partial.reason of POST /v1/orders follows the same rules. On a 409 out-of-stock answer (OUT_OF_STOCK, WAREHOUSE_UNAVAILABLE, ALL_WAREHOUSES_EXHAUSTED), wait the full retryAfterSec before trying again — retrying sooner usually just returns the same answer — and check stock / offers[].stock in GET /v1/services before renting again; follow the orders you already have with webhooks instead of tight polling.
Sample error responses
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
  }
}
Error codeHTTPretryable · retryAfterSecMeaning
UNAUTHORIZED401false · nullThe API key is invalid or missing.
ACCOUNT_LOCKED403false · nullThe account is locked — every request made with its key is rejected. Contact support.
FORBIDDEN403false · nullThe account was no longer active while the rental was being processed (it has just been locked).
NOT_FOUND404false · nullNo order / batch / inbox with this ID in your account (another account's orders also return 404).
VALIDATION_ERROR400false · nullThe request parameters are invalid (wrong type, missing required field, etc.).
INSUFFICIENT_BALANCE402false · nullThe account balance is too low to pay for the order.
SERVICE_DISABLED409false · nullThe service code does not exist or the service is temporarily disabled. Take the exact code from GET /v1/services.
OUT_OF_STOCK409true · 5The service has no inboxes available (for the selected inbox type) at the time of the request.
DOMAIN_UNAVAILABLE409false · nullThe service does not offer the selected inbox type — iCloud is not supported yet / temporarily disabled, or the service has no gmx.com inboxes. Send domain "gmail.com" (or omit the field) to rent Gmail.
WAREHOUSE_UNAVAILABLE409true · 5 / falseThe chosen warehouse does not sell this service/inbox type, is paused or has just run out. Pick another warehouse from offers[], or send warehouse = 99 to let the system pick one with stock. If that warehouse (or every warehouse selling this service) is not available for your account, retryable is false — calling again will not help, use another warehouse.
ALL_WAREHOUSES_EXHAUSTED409true · 5Only with warehouse = 99: every warehouse with stock was tried (cheapest first) and all were out of stock or failing — or every warehouse reports zero stock. Nothing was charged; try again later.
NO_MAILS_AVAILABLE503true · 5The provider has no inboxes left for this service (temporarily out).
QUANTITY_EXCEEDED400false · nullquantity exceeds the per-request maximum (currently 200).
WAITING_LIMIT_REACHED429false · nullToo many orders are waiting for a code at the same time (over your account's limit of concurrent waiting_code orders) — wait for some to finish, then rent again.
ORDER_NOT_CANCELLABLE409false · nullThe order cannot be cancelled — it may already have a code, or it is no longer in the waiting_code status. next-code also returns this code when the order has not received its first code yet.
RERENT_NOT_AVAILABLE409false · nullThe order cannot be rented again. Warehouse 3: it is not the inbox's latest order, the inbox is no longer assigned to your account, or the previous receiving window is still open. Warehouse 2: the order is not closed yet (it can still receive codes — use next-code), it is too old to rent again, the email has another active order, or the service is paused. Warehouses 1 and 4 have no rent-again.
RERENT_EMAIL_BANNED409false · nullWarehouse 2 rent-again: the provider reports the email was locked by the service (email banned) — it can't be rented again; you are not charged.
RERENT_MAIL_GONE409false · nullWarehouse 2 rent-again: the provider can no longer reopen this email — rent a new one; you are not charged.
NEXT_CODE_FEE_CONFIRM409false · nullThe warehouse-2 order's free window has ended — call next-code again with confirmFee: true to pay the fee (nextCodeFee.feePriceVnd). Nothing has been charged.
EMAIL_BANNED409false · nullThe email has been locked by the service (the provider reports email banned) — it can't receive more codes; rent a new one. Since 2026-10-02 (previously ORDER_EXPIRED, same HTTP 409).
ORDER_EXPIRED409false · nullThe order can't receive more codes — its time limit has passed (rentExpiresAt / nextCodeFee.hardUntil), the provider closed the inbox, the code limit (maxCodes) was reached, or the service has no "next code". The reason is in order.nextCodeBlockReason.
RATE_LIMITED429true · = Retry-AfterMore than 100 req/second or 3000 req/minute on your API key (accounts can have their own limits). The Retry-After header tells you how many seconds to wait. In warehouse 2, POST /v1/orders and /rerent also return this code when the account has cancelled many warehouse 2 orders without a code in the last 60 minutes while very few got a code — renting from warehouse 2 pauses until the cancellation rate drops ("warehouse": 99 stops there with this error — pick another warehouse meanwhile). Facebook / Instagram (fb, fbb, ig) are exempt.
DUPLICATE_REQUEST409true · 2 / falseThe Idempotency-Key was already used with a different payload or endpoint, or the first request with this key is still running (retry in a moment). Generate a new key to create another order.
PROVIDER_ERROR502true · 5Error from the inbox provider (temporary — retry after a few seconds).
MAINTENANCE503false · nullThe system is under maintenance — creating and cancelling orders is paused.
MAILSHOP_DISABLED503false · nullBuying short-lived Gmail is paused, or this product is turned off — try again later.
MAILSHOP_PRODUCT_NOT_FOUND404false · nullNo product with this code — take the exact code from GET /v1/mail-shop/products.
MAILSHOP_OUT_OF_STOCK409false · nullNot enough stock for this quantity at the current price — error.details.stock = how many accounts you can buy now.
MAILSHOP_QTY_LIMIT400false · nullquantity is over the per-order maximum (currently 500) — error.details.max.
MAILSHOP_SUPPLIER_ERROR502false · nullThe source refused the purchase at once: a failed order was recorded and the money refunded (error.details.orderId). Try again later with a new Idempotency-Key.
PROXY_DISABLED503false · nullThe proxy section or this proxy warehouse is temporarily closed — try again later.
PROXY_PLAN_NOT_FOUND404false · nullThe plan does not exist or is not for sale right now — read GET /v1/proxy/catalog again.
PROXY_OUT_OF_STOCK409true · 5Not enough proxies for this quantity — error.details.stock = how many you can buy now (if the order was already charged, error.details.orderId has been refunded).
PROXY_QTY_LIMIT400false · nullQuantity above the per-order maximum — error.details.max.
PROXY_SUPPLIER_ERROR502true · 5The proxies could not be delivered: the order failed and the undelivered part was refunded (error.details.orderId). Try again with a new Idempotency-Key.
PROXY_ITEM_NOT_FOUND404false · nullThis proxy is not in your account.
PROXY_NOT_ELIGIBLE409false · nullThis action is not available for this proxy (wrong warehouse, replaced, revoked or expired) — error.details.reason.
PROXY_IP_ALIVE409false · nullIP change refused: the current IP is still alive (only a dead IP can be changed).
PROXY_WARRANTY_EXPIRED409false · nullThe proxy warranty has ended.
PROXY_UNAVAILABLE503true · 5The proxy service is temporarily unavailable — nothing was charged (or it was refunded); retry in a few seconds.
INTERNAL500false · nullUnexpected server error — try again later; contact support if it keeps happening.

Webhooks (push notifications)

Register one URL per account and we POST a signed JSON event to it as soon as an order receives a new code (order.code) or is cancelled / refunded (order.cancelled). Webhooks are optional and cover every order of your account (web and API). Delivery is best-effort — keep a slow poll as a fallback (see below).
Set up in 3 steps
  1. PUT /v1/webhook with your URL (and optionally events) — store data.secret (64 hex characters): you need it to verify every delivery. Calling PUT again keeps the same secret.
  2. POST /v1/webhook/test — we send a ping event right away and return what your server answered (ok, httpStatus, error).
  3. Your endpoint answers any 2xx within 5 seconds — reply first, then process the event. Anything else (3xx, 4xx, 5xx, timeout, connection error) counts as a failure and is retried.
The URL must start with http:// or https:// (with a valid certificate) and be reachable from the internet: localhost, private, link-local, multicast and reserved addresses (10.x, 172.16–31.x, 192.168.x, 169.254.x, fc00::/7, fe80::/10…) and Почта's own servers are rejected with VALIDATION_ERROR. The host name is resolved again before every delivery. Redirects are not followed — register the final URL.
Request format
Every delivery is an HTTP POST to your URL with a JSON body (UTF-8) and these headers:
HeaderValue
Content-Typeapplication/json
User-AgentПочта-Webhook/1
X-Почта-EventEvent name: order.code, order.cancelled or ping
X-Почта-DeliveryUnique event ID (UUID) — equal to deliveryId in the body and unchanged on every retry
X-Почта-TimestampUnix time (seconds) when this attempt was signed — equal to sentAt in the body
X-Почта-Signaturesha256= + lowercase hex HMAC-SHA256 of timestamp + "." + raw body, keyed with your secret
Verify the signature
Compute HMAC-SHA256 with your secret as the key over X-Почта-Timestamp + . + the raw request body, as lowercase hex, and compare it with the value after sha256= in constant time. The key is the 64-character secret string itself (its UTF-8 bytes — do not hex-decode it). Use the raw bytes: parsing and re-serializing the JSON changes them. Reject timestamps more than 5 minutes away from your clock (replay protection).
Receiver examples (Python and Node use only the standard library; the curl command sends a correctly signed test delivery to your own receiver)
# Local test: send your receiver a delivery signed exactly like ours
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"
Events
EventSent when
order.codeAn order received a new code — one event per code, including every next code on the same inbox. code is the new code; otp lists every code of the order so far, oldest first (as in GET /v1/orders/{id}; only the new code when the body would exceed 64 KB).
order.cancelledAn order was cancelled or refunded — once per order: no code before the deadline (timeout), cancelled by you (user) or by an administrator (admin), or refunded because the warehouse failed (provider). refundVnd = VND returned to your balance (0 when the service rules do not refund).
pingOnly from POST /v1/webhook/test.
Event fields
FieldTypeDescription
eventstringEvent name (also in the X-Почта-Event header)
deliveryIdstringUnique event ID (UUID, = X-Почта-Delivery) — store it to skip duplicates
sentAtnumberUnix time of this attempt (= X-Почта-Timestamp)
orderIdstringOrder ID — the same as in GET /v1/orders/{id}
servicestringService code
warehouse1 | 2 | 3 | 4 | nullWarehouse 1–4 that supplied the inbox; null if the order never got one
domainstringInbox domain: gmail.com, icloud.com or gmx.com
emailstring | nullThe rented inbox address
codestringorder.code only: the new code — can also be a link or a full email, like otp[].code
receivedAtnumberorder.code only: unix time the code arrived
statusstringOrder status at that moment: completed for order.code, cancelled for order.cancelled (an admin refund of an order that already had codes keeps completed)
otparrayorder.code only: every code so far, [{code, receivedAt}], oldest first
reasonstringorder.cancelled only: timeout | user | admin | provider
refundVndnumberorder.cancelled only: VND refunded to your balance (0 = no refund)
nextCodeBlockReasonstringorder.cancelled only, and only when the inbox cannot receive any more codes: email_banned | activation_gone | hard_expired | max_codes (as in GET /v1/orders/{id}). An order that ended early because its inbox was locked / is gone keeps reason timeout and carries this field; a plain timeout has no such field
Example body — 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
    }
  ]
}
Example body — 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"
}
Example body — ping
{
  "event": "ping",
  "deliveryId": "3c9a1e7f-2b4d-4c6e-8f0a-5d7b9c1e3a2f",
  "sentAt": 1760700000
}
Retries, pausing and history
  • A failed delivery is retried after 10 s, 1 min, 5 min, 30 min and 2 h (5 retries); if the last retry also fails, the event is dropped (failed).
  • 50 failed attempts in a row (across all events) pause the webhook: GET /v1/webhook shows pausedAt, nothing is sent and new events are not queued.
  • To resume: call PUT /v1/webhook again (the same URL is fine) or get a successful POST /v1/webhook/test — events waiting in the queue are then sent.
  • GET /v1/webhook/deliveries lists the latest 100 deliveries with their status, attempts and last error; history is kept for 7 days.
Duplicates and ordering
The same event can arrive more than once (for example when your 2xx reply was lost) and events can arrive out of order (several are sent in parallel). Store processed deliveryIds and skip repeats; for an order, rely on its newest data (otp, status) rather than on arrival order.
Keep polling as a fallback
Webhooks can be delayed (retries) or missed (webhook paused, your server down). Keep a slow poll — for example GET /v1/orders/{id} every 30–60 s for orders still waiting_code — and treat the order object from the API as the source of truth.
PUT/v1/webhook
Register or update the webhook of your account. The first call creates it and returns a new secret; later calls keep the secret, switch the webhook back on and resume it if it was paused. Without events: both events for a new webhook, unchanged for an existing one. The URL must be a public address — otherwise 400 VALIDATION_ERROR (error.details.problem says why).
Parameters
NameTypeRequiredDescription
urlstringYesYour endpoint (http:// or https://, public address, at most 2048 characters)
eventsstring[]NoWhich events to send: ["order.code", "order.cancelled"] (default both)
Example
# Store data.secret — you need it to verify every delivery
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"]}'
Sample response
{
  "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
  }
}
Possible errors: UNAUTHORIZED, VALIDATION_ERROR
GET/v1/webhook
The webhook of your account, including its secret, pausedAt and consecutiveFailures. data is null when no webhook is registered.
Example
curl "https://onemail.wtf/v1/webhook" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
  }
}
Possible errors: UNAUTHORIZED
DELETE/v1/webhook
Removes the webhook; events still waiting in the queue are dropped. Always 200 — data.deleted is false when there was nothing to remove.
Example
curl -X DELETE "https://onemail.wtf/v1/webhook" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "success": true,
  "data": {
    "deleted": true
  }
}
Possible errors: UNAUTHORIZED
POST/v1/webhook/test
Sends a ping event to your URL right now and reports what happened: ok (your server answered 2xx), httpStatus, durationMs, error. A successful test resumes a paused webhook. At most 10 tests per minute; 503 MAINTENANCE while webhooks are switched off system-wide.
Example
curl -X POST "https://onemail.wtf/v1/webhook/test" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "success": true,
  "data": {
    "ok": true,
    "httpStatus": 200,
    "durationMs": 143,
    "error": null,
    "deliveryId": "3c9a1e7f-2b4d-4c6e-8f0a-5d7b9c1e3a2f"
  }
}
Response 200 when your server does not answer 2xx
{
  "success": true,
  "data": {
    "ok": false,
    "httpStatus": 500,
    "durationMs": 88,
    "error": "HTTP 500",
    "deliveryId": "7d2b9f4e-1c6a-4e3b-8d5f-0a9c2e7b1f4d"
  }
}
Possible errors: UNAUTHORIZED, NOT_FOUND, RATE_LIMITED, MAINTENANCE
GET/v1/webhook/deliveries
Latest deliveries, newest first (kept 7 days): status = queued (next attempt at nextAt) | delivered | failed | paused, with attempts, lastHttpStatus and lastError. Event bodies are not returned.
Parameters
NameTypeRequiredDescription
limitnumberNoNumber of deliveries, 1–100 (default 100)
Example
curl "https://onemail.wtf/v1/webhook/deliveries?limit=20" \
  -H "Authorization: Bearer og_xxx..."
Sample response
{
  "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
    }
  ]
}
Possible errors: UNAUTHORIZED