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.wtfAuthentication
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.
Examplecurl
Python
Node.js
curl "https://onemail.wtf/v1/balance" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"balance": 25000
}
}Possible errors: UNAUTHORIZEDGET/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.
Examplecurl
Python
Node.js
curl "https://onemail.wtf/v1/services" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": [
{
"code": "dr",
"name": "OpenAI (ChatGPT)",
"price": 350,
"stock": 616525,
"icloud": {
"price": 630,
"stock": 12464
},
"offers": [
{
"warehouse": 2,
"domain": "gmail.com",
"price": 350,
"stock": 616525,
"maxCodes": null,
"rules": null,
"fee": {
"freeHours": 6,
"paidPct": 50,
"maxHours": 24
},
"isDefault": true
},
{
"warehouse": 1,
"domain": "gmail.com",
"price": 630,
"stock": 12464,
"maxCodes": 3,
"rules": null,
"fee": null,
"isDefault": false
},
{
"warehouse": 1,
"domain": "icloud.com",
"price": 630,
"stock": 12464,
"maxCodes": 5,
"rules": null,
"fee": null,
"isDefault": true
}
],
"note": null
},
{
"code": "fb",
"name": "Facebook",
"price": 1590,
"stock": 88,
"icloud": null,
"offers": [
{
"warehouse": 1,
"domain": "gmail.com",
"price": 1590,
"stock": 88,
"maxCodes": 10,
"rules": null,
"fee": null,
"isDefault": false
},
{
"warehouse": 4,
"domain": "gmail.com",
"price": 1580,
"stock": 2310,
"maxCodes": null,
"rules": null,
"fee": null,
"isDefault": true
}
],
"note": null
}
]
}Possible errors: UNAUTHORIZEDPOST/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 —
datacan be shorter than quantity, and you are charged only for the orders indata. ThestockinGET /v1/servicesdoes not promise how many one call will get. - The response then also carries a top-level
partialfield next todata(absent when everything was delivered, so bots that only readdatakeep working):requested,delivered,missingandreason={code, message, retryable, retryAfterSec}, wherecodeis 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, waitreason.retryAfterSecseconds (3–5 s), then request themissinginboxes again with a NEWIdempotency-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_STOCKor 503NO_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": 99to 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.retryableanderror.retryAfterSec(for example 409OUT_OF_STOCK⇒true, 5; 402INSUFFICIENT_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| Name | Type | Required | Description |
|---|---|---|---|
service | string | Yes | Service code (from GET /v1/services, e.g. "ig", "tg", "fb") |
quantity | number | No | MAXIMUM 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 |
domain | string | No | Inbox 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. |
warehouse | number | No | Warehouse 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. |
curl
Python
Node.js
# 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"}'{
"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)
Possible errors: {
"success": true,
"data": [
{
"orderId": "abc123xyz",
"service": "ig",
"domain": "gmail.com",
"email": "[email protected]",
"status": "waiting_code",
"price": 1060,
"otp": [],
"codeDeadlineAt": 1753270000,
"rentExpiresAt": 1753356400,
"createdAt": 1753268200,
"warehouse": 1,
"nextCodeFee": null,
"listening": false,
"listenUntil": null,
"nextCodeBlocked": false,
"nextCodeBlockReason": null
},
{
"orderId": "jkl012mno",
"service": "ig",
"domain": "gmail.com",
"email": "[email protected]",
"status": "waiting_code",
"price": 1060,
"otp": [],
"codeDeadlineAt": 1753270001,
"rentExpiresAt": 1753356401,
"createdAt": 1753268201,
"warehouse": 1,
"nextCodeFee": null,
"listening": false,
"listenUntil": null,
"nextCodeBlocked": false,
"nextCodeBlockReason": null
}
],
"partial": {
"requested": 5,
"delivered": 2,
"missing": 3,
"reason": {
"code": "NO_MAILS_AVAILABLE",
"message": "No inboxes available for this service right now, please try again later",
"retryable": true,
"retryAfterSec": 5
}
}
}UNAUTHORIZED, VALIDATION_ERROR, SERVICE_DISABLED, INSUFFICIENT_BALANCE, OUT_OF_STOCK, DOMAIN_UNAVAILABLE, WAREHOUSE_UNAVAILABLE, ALL_WAREHOUSES_EXHAUSTED, NO_MAILS_AVAILABLE, QUANTITY_EXCEEDED, WAITING_LIMIT_REACHED, RATE_LIMITED, DUPLICATE_REQUEST, PROVIDER_ERROR, MAINTENANCEGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (the orderId returned when the order was created) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/orders/ORDER_ID" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"orderId": "abc123xyz",
"service": "ig",
"domain": "gmail.com",
"email": "[email protected]",
"status": "completed",
"price": 1060,
"otp": [
{
"code": "123456",
"receivedAt": 1753268500
},
{
"code": "789012",
"receivedAt": 1753269000
}
],
"codeDeadlineAt": 1753270000,
"rentExpiresAt": 1753356400,
"createdAt": 1753268200,
"warehouse": 1,
"nextCodeFee": null,
"listening": true,
"listenUntil": 1753270500,
"nextCodeBlocked": false,
"nextCodeBlockReason": null
}
}Possible errors: UNAUTHORIZED, NOT_FOUNDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | ID of the order to cancel |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/orders/ORDER_ID/cancel" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json"{
"success": true,
"data": {
"orderId": "abc123xyz",
"service": "ig",
"domain": "gmail.com",
"email": "[email protected]",
"status": "cancelled",
"price": 1060,
"otp": [],
"codeDeadlineAt": 1753270000,
"rentExpiresAt": 1753356400,
"createdAt": 1753268200,
"warehouse": 1,
"nextCodeFee": null,
"listening": false,
"listenUntil": null,
"nextCodeBlocked": false,
"nextCodeBlockReason": null
}
}Possible errors: UNAUTHORIZED, NOT_FOUND, ORDER_NOT_CANCELLABLE, PROVIDER_ERRORPOST/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
ParameterscanRerent = 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.| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | ID of the inbox's previous order (the one with canRerent = true) |
curl
Python
Node.js
# 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)"{
"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, MAINTENANCEPOST/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 withnextCodeBlockReason. - 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 sendconfirmFee= true (missing ⇒ 409NEXT_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 — usePOST /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 untilrentExpiresAt(listening= true; calling again while waiting ⇒ 200, nothing changes); expired ⇒ 409hard_expired, inbox closed ⇒ 409activation_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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (orderId) — any warehouse |
confirmFee | boolean | No | true = you agree to pay nextCodeFee.feePriceVnd to open another code window. Not needed while feePriceVnd = 0. |
refresh | boolean | No | true = 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. |
curl
Python
Node.js
# 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}'{
"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, MAINTENANCEBulk 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(follownextCursor), then resume polling withPOST /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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | Order IDs (orderId) — 1 to 100 per call |
curl
Python
Node.js
# 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"]}'{
"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_LIMITEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | Only this status: waiting_code | completed | cancelled | queued (omitted ⇒ all of them) |
since | number | No | Only orders created at or after this unix time (seconds) |
limit | number | No | Orders per page: 1–200 (default 50) |
cursor | string | No | nextCursor of the previous page, passed unchanged |
curl
Python
Node.js
# 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..."{
"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_LIMITEDWarehouses
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)
offers[] fieldsSend
"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 inoffers[]) 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 thewarehouseandpriceof 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.
curl
Python
Node.js
# 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}'¹ 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 (
nextCodeFee — fee for more codes (warehouse 2 and 3 orders)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.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).curl
Python
Node.js
# 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}'{
"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— aGETreturns{"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 openreadUrl(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
codewithisRaw: true(HTML or text, up to 20,000 characters).
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| Name | Type | Required | Description |
|---|---|---|---|
page | number | No | Page (default 1) |
pageSize | number | No | Batches per page (default 20, max 100) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/batches?page=1&pageSize=20" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"items": [
{
"id": "k3v9m2x7q1w8e5r4",
"serviceCode": "lf",
"serviceName": "Tiktok",
"domain": "icloud.com",
"warehouse": 3,
"status": "active",
"countRequested": 3,
"countReceived": 3,
"countDuplicate": 0,
"countCharged": 3,
"unitPriceVnd": 600,
"quotedVnd": 1800,
"chargedVnd": 1800,
"refundVnd": 0,
"holdHours": 24,
"expiresAt": 1753354200,
"createdAt": 1753267800,
"readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
"codeCount": 1,
"rerentPriceVnd": null
}
],
"total": 1,
"page": 1,
"pageSize": 20
}
}Possible errors: UNAUTHORIZEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Batch ID (shown on the Bulk rental page and in readUrl) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/batches/BATCH_ID" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"id": "k3v9m2x7q1w8e5r4",
"serviceCode": "lf",
"serviceName": "Tiktok",
"domain": "icloud.com",
"warehouse": 3,
"status": "active",
"countRequested": 3,
"countReceived": 3,
"countDuplicate": 0,
"countCharged": 3,
"unitPriceVnd": 600,
"quotedVnd": 1800,
"chargedVnd": 1800,
"refundVnd": 0,
"holdHours": 24,
"expiresAt": 1753354200,
"createdAt": 1753267800,
"readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
"codeCount": 1,
"rerentPriceVnd": null,
"mails": [
{
"id": 812,
"email": "[email protected]",
"url": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
"proxyUrl": null,
"readUrl": "https://onemail.wtf/app/batch/k3v9m2x7q1w8e5r4",
"fresh": true,
"codeCount": 1,
"lastCode": "482913",
"lastCodeAt": 1753268500,
"lastIsRaw": false,
"checkedAt": 1753268507
}
]
}
}Possible errors: UNAUTHORIZED, NOT_FOUNDGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Batch ID |
mailId | number | Yes | Inbox ID (mails[].id) |
poll | 0 | 1 | No | 0 = only read stored codes, do not check the provider (default 1) |
curl
Python
Node.js
# 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..."{
"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_LIMITEDBuy 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- 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) orinboxJsonUrl(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) hasemail|password|cookies|inboxUrlon 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 thetwofakey (add it to Google Authenticator / a TOTP app) or fromtwoFaUrl— this works on a phone too; on a computer you can also import thecookies/ openloginUrlas for warehouse 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, callGET /v1/mail-shop/quote. - Buy:
POST /v1/mail-shop/orderswith{"warehouse": 1 | 2 | 3 | 99, "quantity": N}+ headerIdempotency-Key(a new UUID per purchase). The response is the order, usually alreadycompletedwithitems[]. - Get the accounts: read
items[](table below) or download the TXTGET /v1/mail-shop/orders/{id}/download.status=pending⇒ pollGET /v1/mail-shop/orders/{id}every 5 seconds untilcompleted/partial/failed.
curl
Python
Node.js
# 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..."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"
# 424819Check 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- Money:
chargedVnd= Σroute[].quantity×unitPriceVnd(a 99 order split across warehouses ⇒ two legs inroute). Shortfalls are refunded automatically (refundVnd). Delivered accounts are not refunded — the only warranty is the warehouse'sterms(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 ⇒ 429RATE_LIMITED. - Common errors:
MAILSHOP_OUT_OF_STOCK409 (details.stock= how many you can buy now) ·MAILSHOP_QTY_LIMIT400 (details.max) ·INSUFFICIENT_BALANCE402 ·MAILSHOP_DISABLED503 (warehouse / section paused) ·MAILSHOP_SUPPLIER_ERROR502 (the source refused at once — a failed order was recorded and refunded,details.orderId) ·VALIDATION_ERROR400 (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.
Examplecurl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/products" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"products": [
{
"warehouse": 1,
"code": "gm_cookie",
"name": "Short-lived live Gmail — with cookies + inbox link",
"description": "Short-lived personal Gmail account. You get the email · password · login cookies · an inbox link (add ?json to read the emails as JSON) · a quick login link.",
"terms": "• Warranty covers ONLY the first successful sign-in, within 2 hours of purchase.\n• These Gmail accounts typically last 6–24 hours: use them right after purchase.",
"delivers": [
"email",
"password",
"cookies",
"inboxUrl",
"inboxJsonUrl",
"loginUrl"
],
"priceVnd": 3300,
"listPriceVnd": 3300,
"stock": 1840,
"available": true,
"maxQty": 500
},
{
"warehouse": 2,
"code": "gm_login",
"name": "Short-lived live Gmail — with a quick login link",
"description": "Short-lived personal Gmail account that has been used on a few services. You get the email · password · a quick login link.",
"terms": "• Warranty covers ONLY the first successful sign-in, within 2 hours of purchase.\n• Sign in with the link in a DESKTOP BROWSER.",
"delivers": [
"email",
"password",
"loginUrl"
],
"priceVnd": 6000,
"listPriceVnd": 6000,
"stock": 141,
"available": true,
"maxQty": 100
},
{
"warehouse": 3,
"code": "gm_2fa",
"name": "Short-lived live Gmail — with 2FA key + cookies",
"description": "Short-lived personal Gmail account with 2FA ENABLED — you can sign in on a phone too. You get the email · password · recovery email (if any) · the 2FA key + a 2FA code link · login cookies · an inbox link · an account live-check link.",
"terms": "• Warranty covers ONLY the first successful sign-in, within 2 hours of purchase.\n• These Gmail accounts typically last 6–24 hours: use them right after purchase.",
"delivers": [
"email",
"password",
"recovery",
"twofa",
"twoFaUrl",
"cookies",
"loginUrl",
"inboxUrl",
"inboxJsonUrl",
"liveUrl"
],
"priceVnd": 3300,
"listPriceVnd": 3300,
"stock": 920,
"available": true,
"maxQty": 500
}
],
"auto": {
"warehouse": 99,
"priceVnd": 3300,
"available": true,
"order": [
1,
2
]
}
}
}Possible errors: UNAUTHORIZEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
warehouse | number | No | Mail-shop warehouse = a `warehouse` number from products[] of GET /v1/mail-shop/products (each lists its fields in `delivers`; warehouses can be added — do not assume only 1 / 2 / 3), or 99 = automatic, cheapest first among the warehouses in auto.order. Send warehouse OR product |
product | string | No | Instead of warehouse: the `code` of a warehouse in GET /v1/mail-shop/products (e.g. gm_cookie, gm_login, gm_2fa) |
quantity | number | No | Number of accounts (default 1) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/quote?warehouse=99&quantity=10" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"warehouse": 99,
"quantity": 10,
"unitPriceVnd": 3300,
"totalVnd": 38400,
"available": true,
"stock": null,
"maxQty": 500,
"route": [
{
"warehouse": 1,
"quantity": 8,
"unitPriceVnd": 3300
},
{
"warehouse": 2,
"quantity": 2,
"unitPriceVnd": 6000
}
]
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, MAILSHOP_PRODUCT_NOT_FOUNDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
warehouse | number | No | Mail-shop warehouse = a `warehouse` number from products[] of GET /v1/mail-shop/products (each lists its fields in `delivers`; warehouses can be added — do not assume only 1 / 2 / 3), or 99 = automatic, cheapest first among the warehouses in auto.order. Send warehouse OR product |
product | string | No | Instead of warehouse: the `code` of a warehouse in GET /v1/mail-shop/products (e.g. gm_cookie, gm_login, gm_2fa) |
quantity | number | No | Number of accounts (default 1) |
Idempotency-Key | string | Yes | Header: a new UUID for every new purchase — reuse it only to retry that same purchase |
curl
Python
Node.js
# 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}'{
"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, MAINTENANCEGET/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| Name | Type | Required | Description |
|---|---|---|---|
page | number | No | Page (default 1) |
pageSize | number | No | Orders per page (default 20, max 100) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/orders?page=1&pageSize=20" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"items": [
{
"id": "p3x9k2m7q1w8e5r4",
"requestedWarehouse": 99,
"warehouse": 1,
"productCode": "gm_cookie",
"quantity": 2,
"deliveredCount": 2,
"unitPriceVnd": 3300,
"chargedVnd": 9300,
"refundVnd": 0,
"status": "completed",
"channel": "api",
"route": [
{
"warehouse": 1,
"quantity": 1,
"unitPriceVnd": 3300
},
{
"warehouse": 2,
"quantity": 1,
"unitPriceVnd": 6000
}
],
"message": null,
"createdAt": 1760000400,
"completedAt": 1760000409
}
],
"total": 1,
"page": 1,
"pageSize": 20
}
}Possible errors: UNAUTHORIZEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (data.id returned by the purchase) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"id": "p3x9k2m7q1w8e5r4",
"requestedWarehouse": 99,
"warehouse": 1,
"productCode": "gm_cookie",
"quantity": 2,
"deliveredCount": 2,
"unitPriceVnd": 3300,
"chargedVnd": 9300,
"refundVnd": 0,
"status": "completed",
"channel": "api",
"route": [
{
"warehouse": 1,
"quantity": 1,
"unitPriceVnd": 3300
},
{
"warehouse": 2,
"quantity": 1,
"unitPriceVnd": 6000
}
],
"message": null,
"createdAt": 1760000400,
"completedAt": 1760000409,
"items": [
{
"lineNo": 1,
"warehouse": 1,
"email": "[email protected]",
"password": "Pw7Xq!k3d",
"rawLine": "[email protected]|Pw7Xq!k3d||[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000…\"}]",
"cookies": "[{\"domain\":\".google.com\",\"name\":\"SID\",\"value\":\"g.a000…\"}]",
"inboxUrl": "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d",
"inboxJsonUrl": "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d?json",
"loginUrl": "https://onemail.wtf/login/Q7xK2mP9vL4tR8wN3cB6yH1d",
"liveUrl": "https://onemail.wtf/live/Q7xK2mP9vL4tR8wN3cB6yH1d",
"twoFaUrl": "https://onemail.wtf/2fa/Q7xK2mP9vL4tR8wN3cB6yH1d",
"inboxLinkExpiresAt": 1762592400
},
{
"lineNo": 2,
"warehouse": 2,
"email": "[email protected]",
"password": "Qp9!rT2",
"rawLine": "[email protected]!rT2----no----https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Fk3Wq8Ln5Tz1Vb7Mc4Rx6y",
"loginUrl": "https://onemail.wtf/api/mail-shop/login/p3x9k2m7q1w8e5r4.2.Fk3Wq8Ln5Tz1Vb7Mc4Rx6y",
"otpUrl": "https://onemail.wtf/api/mail-shop/otp/p3x9k2m7q1w8e5r4.2.Zx8Kq2Lm4Np6Rt0Vw3Yb5c",
"otpService": "vinted"
}
]
}
}Possible errors: UNAUTHORIZED, NOT_FOUNDGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (data.id returned by the purchase) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/download" \
-H "Authorization: Bearer og_xxx..." \
-o mail-ORDER_ID.txtemail|password|cookies|inboxUrl
[email protected]|Pw7Xq!k3d|[{"domain":".google.com","name":"SID","value":"g.a000…"}]|https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1dPossible errors: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERRORGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (data.id returned by the purchase) |
lineNo | number | Yes | Account number within the order (items[].lineNo) |
max | number | No | Number of latest emails: 10 (default), 20, 50, 100 or 200 |
curl
Python
Node.js
# Warehouse 1 accounts only; max = 10 | 20 | 50 | 100 | 200
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/inbox?max=20" \
-H "Authorization: Bearer og_xxx..." \
--max-time 70
# Same emails without an API key: GET the account's inboxJsonUrl
curl "https://onemail.wtf/mail/Q7xK2mP9vL4tR8wN3cB6yH1d?json&max=20"{
"success": true,
"data": {
"email": "[email protected]",
"letters": [
{
"key": "h:9f2c4e1a7b3d5c80",
"from": "Instagram [email protected]",
"subject": "350038 is your Instagram code",
"receivedAt": 1760000520,
"code": "350038",
"content": "<html><body><p>Enter this confirmation code in the app: 350038</p></body></html>"
}
],
"max": 10,
"total": 8,
"fetchedAt": 1760000530,
"cached": false
}
}Possible errors: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PROVIDER_ERRORPOST/v1/mail-shop/orders/{id}/items/{lineNo}/inbox-link
Manage the inbox link (inboxUrl + inboxJsonUrl + loginUrl + liveUrl + twoFaUrl — one shared code) of a warehouse-1 / warehouse-3 account: action "regenerate" = NEW link (the old one stops working immediately; also re-enables a link you turned off), "off" = turn it off (inboxUrl / inboxJsonUrl / loginUrl / liveUrl / twoFaUrl become null). Returns the account (an element of items[]).
At most 60 changes per 10 minutes for your account.
Parameters| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (data.id returned by the purchase) |
lineNo | number | Yes | Account number within the order (items[].lineNo) |
action | string | Yes | "regenerate" = new link (the old one stops working immediately) · "off" = turn the link off |
curl
Python
Node.js
# New link (the old one stops working immediately); send {"action":"off"} to turn it off
curl -X POST "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/inbox-link" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"action":"regenerate"}'{
"success": true,
"data": {
"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/Hn4Vw8Zr2Lk6Tq9Pm3Xs7Bd1",
"inboxJsonUrl": "https://onemail.wtf/mail/Hn4Vw8Zr2Lk6Tq9Pm3Xs7Bd1?json",
"loginUrl": "https://onemail.wtf/login/Hn4Vw8Zr2Lk6Tq9Pm3Xs7Bd1",
"liveUrl": "https://onemail.wtf/live/Hn4Vw8Zr2Lk6Tq9Pm3Xs7Bd1",
"twoFaUrl": "https://onemail.wtf/2fa/Hn4Vw8Zr2Lk6Tq9Pm3Xs7Bd1",
"inboxLinkExpiresAt": 1762592400
}
}Possible errors: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (data.id returned by the purchase) |
lineNo | number | Yes | Account number within the order (items[].lineNo) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/status" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"email": "[email protected]",
"live": true,
"reason": null,
"checkedAt": 1760000600
}
}Possible errors: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PROVIDER_ERRORGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID (data.id returned by the purchase) |
lineNo | number | Yes | Account number within the order (items[].lineNo) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/mail-shop/orders/ORDER_ID/items/1/2fa" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"none": false,
"code": "424819",
"expiresIn": 24
}
}Possible errors: UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PROVIDER_ERRORProxies
Buy HTTP proxies over the API — same catalog, prices, balance and rules as the website (same server, same orders). Proxies come as
What you can buy (warehouses)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.GET /v1/proxy/catalog⇒ pick a product withwarranty.available: true(basePriceVnd+perDayVndper day is YOUR price;stock= how many you can buy now).POST /v1/proxy/orders{productId, days, quantity}(+autoReplace: trueif you want the system to replace a dead IP by itself) + anIdempotency-Keyheader (REQUIRED) ⇒ the order +items[](one proxy each, the string isproxy).- Manage:
GET /v1/proxy/items(filter withview,type), check live, warranty / replace, renew, export .txt.
curl
Python
Node.js
# 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}'- Idempotency-Key is REQUIRED for
POST /v1/proxy/ordersandPOST /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 isprocessing(still being delivered) ⇒ pollGET /v1/proxy/orders/{id}every 3–5 s.partial= fewer delivered, the rest refunded (refundVnd); total failure ⇒ 502PROXY_SUPPLIER_ERROR+error.details.orderId(refunded). - Out of stock ⇒ 409
PROXY_OUT_OF_STOCK(error.details.stock) and nothing is charged;retryable: true⇒ waitretryAfterSecand try again (with a NEW key). - Warehouse 1 — warranty:
warrantyonly CHECKS (alive / dead / in or out of warranty / waiting);replaceSWAPS (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.priceVndper 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 showsreplacewithdata.auto: true. Free replacements used up ⇒autoReplaceStatus.state=stopped. Not chosen ⇒ as before: callwarranty/replaceyourself. Option temporarily off ⇒autoReplace.available: false, buying with it ⇒ 409PROXY_NOT_ELIGIBLE(details.reason: "auto_replace_unavailable", nothing charged). - Renew:
renew-quoteshows the price first,renewcharges 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.
Examplecurl
Python
Node.js
curl "https://onemail.wtf/v1/proxy/catalog" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"enabled": true,
"kho1Enabled": true,
"kho2Enabled": true,
"maxQuantity": 100,
"formats": [
"colon",
"at",
"url"
],
"products": [
{
"key": "k1-5",
"kho": 1,
"productId": 5,
"type": "datacenter_vn",
"grade": "good",
"nameKey": "datacenter_vn.good",
"name": "",
"description": "",
"protocol": "http",
"stock": 1476,
"daysMeaning": "warranty",
"plans": [
{
"id": 17,
"kho": 1,
"days": 30,
"priceVnd": 1400,
"listPriceVnd": 1400,
"customPrice": false,
"available": true
}
],
"warranty": {
"planId": 17,
"minDays": 1,
"maxDays": 90,
"defaultDays": 30,
"quickDays": [
7,
15,
30,
60,
90
],
"basePriceVnd": 450,
"perDayVnd": 30,
"listBasePriceVnd": 450,
"listPerDayVnd": 30,
"customPrice": false,
"roundTo": 100,
"available": true
},
"intermediate": null,
"autoReplace": {
"available": true,
"priceVnd": 50
}
},
{
"key": "k1-4",
"kho": 1,
"productId": 4,
"type": "datacenter_us",
"grade": "good",
"nameKey": "datacenter_us.good",
"name": "",
"description": "",
"protocol": "http",
"stock": 810,
"daysMeaning": "warranty",
"plans": [
{
"id": 13,
"kho": 1,
"days": 30,
"priceVnd": 1200,
"listPriceVnd": 1200,
"customPrice": false,
"available": true
}
],
"warranty": {
"planId": 13,
"minDays": 1,
"maxDays": 90,
"defaultDays": 30,
"quickDays": [
7,
15,
30,
60,
90
],
"basePriceVnd": 600,
"perDayVnd": 20,
"listBasePriceVnd": 600,
"listPerDayVnd": 20,
"customPrice": false,
"roundTo": 100,
"available": true
},
"intermediate": null,
"autoReplace": {
"available": true,
"priceVnd": 50
}
}
]
}
}Possible errors: UNAUTHORIZED, PROXY_DISABLEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
productId | number | No | Warehouse 1 — <c>products[].productId</c> |
days | number | No | Warehouse 1 — warranty days 1…<c>warranty.maxDays</c> (default 30) |
autoReplace | boolean | No | Warehouse 1 — <c>1</c> = with "auto-replace the IP when it dies" (+<c>autoReplace.priceVnd</c> per proxy) |
planId | number | No | Warehouse 2 — plan <c>products[].plans[].id</c> (warehouse 1: the per-day plan is accepted too) |
quantity | number | No | Number of proxies (default 1) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/proxy/quote?productId=5&days=30&autoReplace=1&quantity=5" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"planId": 17,
"productId": 5,
"kho": 1,
"type": "datacenter_vn",
"days": 30,
"intermediate": false,
"intermediatePriceVnd": 0,
"autoReplace": true,
"autoReplacePriceVnd": 50,
"quantity": 5,
"unitPriceVnd": 1450,
"totalVnd": 7250,
"stock": 1476,
"maxQuantity": 100,
"balanceVnd": 250000,
"enough": true
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_PLAN_NOT_FOUND, PROXY_QTY_LIMIT, PROXY_NOT_ELIGIBLE, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
productId | number | No | Warehouse 1 — <c>products[].productId</c> |
days | number | No | Warehouse 1 — warranty days 1…<c>warranty.maxDays</c> (default 30) |
autoReplace | boolean | No | Warehouse 1 — <c>true</c> = "Intermediate proxy — auto-replace the IP when it dies" (+<c>autoReplace.priceVnd</c> per proxy, default <c>false</c>): the system replaces a dead IP by itself; not chosen ⇒ call <c>replace</c> yourself when a proxy dies |
planId | number | No | Warehouse 2 — plan <c>products[].plans[].id</c> from the catalog (send <c>productId</c> OR <c>planId</c>) |
quantity | number | Yes | Number of proxies (≤ <c>maxQuantity</c>) |
Idempotency-Key | string | Yes | A new UUID per purchase; reuse it when retrying |
curl
Python
Node.js
# warehouse 1: productId from GET /v1/proxy/catalog (products[].productId) + warranty days (1–maxDays, default 30)
# "autoReplace": true (optional, + products[].autoReplace.priceVnd per proxy) = the system replaces a dead IP by itself
# warehouse 2: {"planId": products[].plans[].id} · one NEW Idempotency-Key per purchase, reuse it to retry
curl -X POST "https://onemail.wtf/v1/proxy/orders" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
--max-time 60 \
-d '{"productId":5,"days":30,"quantity":5,"autoReplace":true}'{
"success": true,
"data": {
"id": "a1b2c3d4e5f6g7h8",
"kho": 1,
"kind": "buy",
"planId": 17,
"type": "datacenter_vn",
"nameKey": "datacenter_vn.good",
"quantity": 1,
"days": 30,
"unitPriceVnd": 1450,
"totalVnd": 1450,
"refundVnd": 0,
"status": "completed",
"deliveredCount": 1,
"source": "api",
"intermediate": false,
"intermediateFailed": 0,
"autoReplace": true,
"autoReplacePriceVnd": 50,
"errorCode": null,
"errorMessage": null,
"createdAt": 1793952000,
"completedAt": 1793952003,
"items": [
{
"id": "k3m9x2p7q1w8e5r4",
"orderId": "a1b2c3d4e5f6g7h8",
"kho": 1,
"type": "resident_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 23817,
"username": "u7hk2m9qzt4w",
"password": "Lp2Qa8xT4w9cNb3e",
"proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"status": "active",
"health": "live",
"exitIp": "198.51.100.21",
"latencyMs": 182,
"lastCheckAt": 1793952060,
"lastOkAt": 1793952060,
"expiresAt": 1794556800,
"warrantyUntil": 1794556800,
"replacementsLeft": 3,
"replaceCount": 0,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": true,
"autoReplaceStatus": {
"state": "on",
"count": 1,
"lastAt": 1794020400
},
"actions": {
"check": true,
"warranty": true,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952003
}
]
}
}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, MAINTENANCEGET/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| Name | Type | Required | Description |
|---|---|---|---|
page | number | No | Page (from 1) |
pageSize | number | No | 1–200, default 20 |
kho | number | No | 1 | 2 |
kind | string | No | <c>buy</c> | <c>renew</c> |
type | string | No | Type: <c>resident_vn</c> · <c>vip_resident_vn</c> · <c>datacenter_vn</c> · <c>resident_us</c> · <c>datacenter_us</c> |
curl
Python
Node.js
curl "https://onemail.wtf/v1/proxy/orders?page=1&pageSize=20" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"items": [
{
"id": "a1b2c3d4e5f6g7h8",
"kho": 1,
"kind": "buy",
"planId": 17,
"type": "datacenter_vn",
"nameKey": "datacenter_vn.good",
"quantity": 1,
"days": 30,
"unitPriceVnd": 1450,
"totalVnd": 1450,
"refundVnd": 0,
"status": "completed",
"deliveredCount": 1,
"source": "api",
"intermediate": false,
"intermediateFailed": 0,
"autoReplace": true,
"autoReplacePriceVnd": 50,
"errorCode": null,
"errorMessage": null,
"createdAt": 1793952000,
"completedAt": 1793952003
},
{
"id": "z9x8c7v6b5n4m3l2",
"kho": 1,
"kind": "buy",
"planId": 17,
"type": "datacenter_vn",
"nameKey": "datacenter_vn.good",
"quantity": 10,
"days": 30,
"unitPriceVnd": 1400,
"totalVnd": 14000,
"refundVnd": 4200,
"status": "partial",
"deliveredCount": 7,
"source": "api",
"intermediate": false,
"intermediateFailed": 0,
"autoReplace": false,
"autoReplacePriceVnd": 0,
"errorCode": "PROXY_OUT_OF_STOCK",
"errorMessage": "Delivered 7/10 proxies — 4,200 VND refunded for the rest",
"createdAt": 1793952000,
"completedAt": 1793952004
}
],
"total": 2,
"page": 1,
"pageSize": 20
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLEDGET/v1/proxy/orders/{id}
One order + <c>items[]</c> (a renewal: the proxies renewed). Poll it while <c>status</c> = <c>processing</c>.
Parameters| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Order ID |
curl
Python
Node.js
curl "https://onemail.wtf/v1/proxy/orders/ORDER_ID" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"id": "a1b2c3d4e5f6g7h8",
"kho": 1,
"kind": "buy",
"planId": 17,
"type": "datacenter_vn",
"nameKey": "datacenter_vn.good",
"quantity": 1,
"days": 30,
"unitPriceVnd": 1450,
"totalVnd": 1450,
"refundVnd": 0,
"status": "completed",
"deliveredCount": 1,
"source": "api",
"intermediate": false,
"intermediateFailed": 0,
"autoReplace": true,
"autoReplacePriceVnd": 50,
"errorCode": null,
"errorMessage": null,
"createdAt": 1793952000,
"completedAt": 1793952003,
"items": [
{
"id": "k3m9x2p7q1w8e5r4",
"orderId": "a1b2c3d4e5f6g7h8",
"kho": 1,
"type": "resident_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 23817,
"username": "u7hk2m9qzt4w",
"password": "Lp2Qa8xT4w9cNb3e",
"proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"status": "active",
"health": "live",
"exitIp": "198.51.100.21",
"latencyMs": 182,
"lastCheckAt": 1793952060,
"lastOkAt": 1793952060,
"expiresAt": 1794556800,
"warrantyUntil": 1794556800,
"replacementsLeft": 3,
"replaceCount": 0,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": true,
"autoReplaceStatus": {
"state": "on",
"count": 1,
"lastAt": 1794020400
},
"actions": {
"check": true,
"warranty": true,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952003
}
]
}
}Possible errors: UNAUTHORIZED, NOT_FOUND, PROXY_DISABLEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
view | string | No | Filter (see above) |
kho | number | No | 1 | 2 |
type | string | No | Type: <c>resident_vn</c> · <c>vip_resident_vn</c> · <c>datacenter_vn</c> · <c>resident_us</c> · <c>datacenter_us</c> |
q | string | No | Search host / user / exit IP / id |
orderId | string | No | Only the proxies of one order |
page · pageSize | number | No | Pagination (pageSize 1–200) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/proxy/items?view=active&pageSize=100" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"items": [
{
"id": "p7w2n8x4c1v9b3m6",
"orderId": "q9w8e7r6t5y4u3i2",
"kho": 2,
"type": "private_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 18450,
"username": "rx7k2m9q",
"password": "Tz4w8Lp2Qa",
"proxy": "203.0.113.50:18450:rx7k2m9q:Tz4w8Lp2Qa",
"status": "active",
"health": "dead",
"exitIp": "198.51.100.77",
"latencyMs": null,
"lastCheckAt": 1793952060,
"lastOkAt": 1793948400,
"expiresAt": 1794556800,
"warrantyUntil": null,
"replacementsLeft": null,
"replaceCount": 1,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": false,
"autoReplaceStatus": null,
"actions": {
"check": true,
"warranty": false,
"replace": false,
"changeIp": true,
"renew": true
},
"createdAt": 1793952000
},
{
"id": "k3m9x2p7q1w8e5r4",
"orderId": "a1b2c3d4e5f6g7h8",
"kho": 1,
"type": "resident_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 23817,
"username": "u7hk2m9qzt4w",
"password": "Lp2Qa8xT4w9cNb3e",
"proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"status": "active",
"health": "live",
"exitIp": "198.51.100.21",
"latencyMs": 182,
"lastCheckAt": 1793952060,
"lastOkAt": 1793952060,
"expiresAt": 1794556800,
"warrantyUntil": 1794556800,
"replacementsLeft": 3,
"replaceCount": 0,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": true,
"autoReplaceStatus": {
"state": "on",
"count": 1,
"lastAt": 1794020400
},
"actions": {
"check": true,
"warranty": true,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952003
}
],
"total": 2,
"page": 1,
"pageSize": 20,
"counts": {
"active": 2,
"expiring": 0,
"dead": 1,
"expired": 0,
"all": 2
}
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLEDGET/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Proxy ID |
curl
Python
Node.js
curl "https://onemail.wtf/v1/proxy/items/PROXY_ID" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"item": {
"id": "k3m9x2p7q1w8e5r4",
"orderId": "a1b2c3d4e5f6g7h8",
"kho": 1,
"type": "resident_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 23817,
"username": "u7hk2m9qzt4w",
"password": "Lp2Qa8xT4w9cNb3e",
"proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"status": "active",
"health": "live",
"exitIp": "198.51.100.21",
"latencyMs": 182,
"lastCheckAt": 1793952060,
"lastOkAt": 1793952060,
"expiresAt": 1794556800,
"warrantyUntil": 1794556800,
"replacementsLeft": 3,
"replaceCount": 0,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": true,
"autoReplaceStatus": {
"state": "on",
"count": 1,
"lastAt": 1794020400
},
"actions": {
"check": true,
"warranty": true,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952003
},
"events": [
{
"id": 871,
"type": "check",
"ok": true,
"actor": "api",
"at": 1793952060,
"data": {
"health": "live",
"exitIp": "203.0.113.21"
}
},
{
"id": 870,
"type": "deliver",
"ok": true,
"actor": "system",
"at": 1793952003,
"data": {
"days": 7
}
}
],
"usage": []
}
}Possible errors: UNAUTHORIZED, PROXY_ITEM_NOT_FOUND, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | Proxy IDs (≤ 200) |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/check" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"ids":["k3m9x2p7q1w8e5r4"]}'{
"success": true,
"data": {
"results": [
{
"id": "k3m9x2p7q1w8e5r4",
"found": true,
"health": "live",
"exitIp": "203.0.113.21",
"latencyMs": 182,
"checkedAt": 1794038400,
"error": null
},
{
"id": "nope",
"found": false,
"health": "unknown",
"exitIp": null,
"latencyMs": null,
"checkedAt": null,
"error": null
}
]
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | Proxy IDs (≤ 200) |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/warranty" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"ids":["k3m9x2p7q1w8e5r4"]}'{
"success": true,
"data": {
"results": [
{
"id": "k3m9x2p7q1w8e5r4",
"kho": 1,
"health": "dead",
"outcome": "eligible",
"warrantyUntil": 1794556800,
"replacementsLeft": 3,
"checkedAt": 1794038400
},
{
"id": "m1n2b3v4c5x6z7l8",
"kho": 1,
"health": "dead",
"outcome": "expired",
"warrantyUntil": 1793952000,
"replacementsLeft": 2,
"checkedAt": 1794038400
}
]
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
text | string | Yes | The list, one proxy per line |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/lookup" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"text":"203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e\nhttp://x:[email protected]:8080"}'{
"success": true,
"data": {
"lines": [
{
"lineNo": 1,
"input": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"error": null,
"itemId": "k3m9x2p7q1w8e5r4",
"result": {
"id": "k3m9x2p7q1w8e5r4",
"kho": 1,
"health": "dead",
"outcome": "eligible",
"warrantyUntil": 1794556800,
"replacementsLeft": 3,
"checkedAt": 1794038400
}
},
{
"lineNo": 2,
"input": "http://x:[email protected]:8080",
"error": "not_mine",
"itemId": null,
"result": null
}
],
"eligibleIds": [
"k3m9x2p7q1w8e5r4"
],
"summary": {
"total": 2,
"mine": 1,
"notMine": 1,
"invalid": 0,
"alive": 0,
"eligible": 1,
"expired": 0
}
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | Proxy IDs (≤ 200) — e.g. eligibleIds from lookup |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/replace" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"ids":["k3m9x2p7q1w8e5r4"]}'{
"success": true,
"data": {
"results": [
{
"id": "k3m9x2p7q1w8e5r4",
"outcome": "replaced",
"newItem": {
"id": "k3m9x2p7q1w8e5r4",
"orderId": "a1b2c3d4e5f6g7h8",
"kho": 1,
"type": "resident_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 23817,
"username": "u7hk2m9qzt4w",
"password": "Lp2Qa8xT4w9cNb3e",
"proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"status": "active",
"health": "unknown",
"exitIp": null,
"latencyMs": null,
"lastCheckAt": null,
"lastOkAt": null,
"expiresAt": 1794556800,
"warrantyUntil": 1794556800,
"replacementsLeft": 2,
"replaceCount": 1,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": true,
"autoReplaceStatus": {
"state": "on",
"count": 1,
"lastAt": 1794020400
},
"actions": {
"check": true,
"warranty": true,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952003
}
},
{
"id": "m1n2b3v4c5x6z7l8",
"outcome": "expired",
"newItem": null
}
]
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Proxy ID (warehouse 2) |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/PROXY_ID/change-ip" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{}'{
"success": true,
"data": {
"item": {
"id": "p7w2n8x4c1v9b3m6",
"orderId": "q9w8e7r6t5y4u3i2",
"kho": 2,
"type": "private_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 18450,
"username": "rx7k2m9q",
"password": "Tz4w8Lp2Qa",
"proxy": "203.0.113.50:18450:rx7k2m9q:Tz4w8Lp2Qa",
"status": "active",
"health": "live",
"exitIp": "198.51.100.91",
"latencyMs": 140,
"lastCheckAt": 1793952060,
"lastOkAt": 1793948400,
"expiresAt": 1794556800,
"warrantyUntil": null,
"replacementsLeft": null,
"replaceCount": 2,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": false,
"autoReplaceStatus": null,
"actions": {
"check": true,
"warranty": false,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952000
},
"fromIp": "198.51.100.77",
"toIp": "198.51.100.91"
}
}Possible errors: UNAUTHORIZED, PROXY_ITEM_NOT_FOUND, PROXY_IP_ALIVE, PROXY_NOT_ELIGIBLE, PROXY_OUT_OF_STOCK, PROXY_UNAVAILABLE, RATE_LIMITED, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | Proxy IDs (≤ 200, same warehouse) |
days | number | Yes | Warehouse 1: 1–90 · warehouse 2: 1–365 |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/renew-quote" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"ids":["k3m9x2p7q1w8e5r4"],"days":7}'{
"success": true,
"data": {
"kho": 1,
"days": 7,
"items": [
{
"id": "k3m9x2p7q1w8e5r4",
"unitPriceVnd": 200,
"newEnd": 1795161600
}
],
"totalVnd": 200,
"balanceVnd": 250000,
"enough": true
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_ITEM_NOT_FOUND, PROXY_NOT_ELIGIBLE, PROXY_DISABLEDPOST/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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | Proxy IDs (≤ 200, same warehouse) |
days | number | Yes | 1–365 |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/renew" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["k3m9x2p7q1w8e5r4"],"days":7}'{
"success": true,
"data": {
"id": "r1e2n3e4w5o6r7d8",
"kho": 1,
"kind": "renew",
"planId": 17,
"type": "datacenter_vn",
"nameKey": "datacenter_vn.good",
"quantity": 1,
"days": 7,
"unitPriceVnd": 200,
"totalVnd": 200,
"refundVnd": 0,
"status": "completed",
"deliveredCount": 1,
"source": "api",
"intermediate": false,
"intermediateFailed": 0,
"autoReplace": true,
"autoReplacePriceVnd": 50,
"errorCode": null,
"errorMessage": null,
"createdAt": 1793952000,
"completedAt": 1793952003,
"items": [
{
"id": "k3m9x2p7q1w8e5r4",
"orderId": "a1b2c3d4e5f6g7h8",
"kho": 1,
"type": "resident_vn",
"protocol": "http",
"host": "203.0.113.50",
"port": 23817,
"username": "u7hk2m9qzt4w",
"password": "Lp2Qa8xT4w9cNb3e",
"proxy": "203.0.113.50:23817:u7hk2m9qzt4w:Lp2Qa8xT4w9cNb3e",
"status": "active",
"health": "live",
"exitIp": "198.51.100.21",
"latencyMs": 182,
"lastCheckAt": 1793952060,
"lastOkAt": 1793952060,
"expiresAt": 1794556800,
"warrantyUntil": 1795161600,
"replacementsLeft": 3,
"replaceCount": 0,
"replacedBy": null,
"replaces": null,
"intermediate": null,
"autoReplace": true,
"autoReplaceStatus": {
"state": "on",
"count": 1,
"lastAt": 1794020400
},
"actions": {
"check": true,
"warranty": true,
"replace": false,
"changeIp": false,
"renew": true
},
"createdAt": 1793952003
}
]
}
}Possible errors: UNAUTHORIZED, VALIDATION_ERROR, INSUFFICIENT_BALANCE, PROXY_ITEM_NOT_FOUND, PROXY_NOT_ELIGIBLE, PROXY_SUPPLIER_ERROR, PROXY_DISABLED, RATE_LIMITED, DUPLICATE_REQUEST, MAINTENANCEPOST/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| Name | Type | Required | Description |
|---|---|---|---|
ids | string[] | No | Proxy IDs (≤ 5,000) |
view · kho · type | string · number · string | No | Instead of ids: filters as in GET /v1/proxy/items |
format | string | No | <c>colon</c> | <c>at</c> | <c>url</c> |
which | string | No | Kept for compatibility: <c>proxy</c> (default). New proxies have no intermediate (the option was removed) ⇒ <c>intermediate</c> returns nothing, <c>both</c> = same as <c>proxy</c> |
curl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/proxy/items/export" \
-H "Authorization: Bearer og_xxx..." \
-H "Content-Type: application/json" \
-d '{"view":"active","format":"url"}'http://u7hk2m9qzt4w:[email protected]:23817
http://rx7k2m9q:[email protected]:18450
Possible errors: UNAUTHORIZED, VALIDATION_ERROR, PROXY_DISABLEDOrder lifecycle
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 withotp[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 ofotp[]. 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 (maxCodesandfeeinoffers[]; 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[].codeis 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) inotp[].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/orderswaits 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 sameIdempotency-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 getDOMAIN_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 — seeGET /v1/services) are iCloud-only; each email arrives as a link inotp[].code, together withkind,labeland the full email text intext. An order receives up torules.maxCodesemails withinrules.windowMinutesminutes (untilwindowEndsAt), 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, callPOST /v1/orders/{id}/rerentwhilecanRerentis true (price:rerentPriceVnd). Every other service / order hasprovider="standard"— since 2026-10-24providerhas only two values,"standard"|"inventory"(the actual warehouse is inwarehouse); compare with"inventory"only. - Warehouse 2 orders (
warehouse= 2): codes are free forfee.freeHourshours; once the free window closes, new codes stop arriving — callPOST /v1/orders/{id}/next-codewithconfirmFee= true (payingnextCodeFee.feePriceVnd) to open another window, up tonextCodeFee.hardUntil. Warehouse 3 orders of regular services: free codes for 24 hours, cancellable before a code arrives, then usererent. Warehouse 4 orders: new codes land inotp[]when you read the order, free untilrentExpiresAt; with a single-code source,nextCodeBlockReasonbecomes"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
Sample error responseserror.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.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
}
}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 (
Set up in 3 stepsorder.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).PUT /v1/webhookwith your URL (and optionallyevents) — storedata.secret(64 hex characters): you need it to verify every delivery. Calling PUT again keeps the same secret.POST /v1/webhook/test— we send apingevent right away and return what your server answered (ok,httpStatus,error).- 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
Request formathttp:// 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.Every delivery is an HTTP POST to your URL with a JSON body (UTF-8) and these headers:
Compute HMAC-SHA256 with your secret as the key over
Receiver examples (Python and Node use only the standard library; the curl command sends a correctly signed test delivery to your own receiver)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).curl
Python
Node.js
# 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"{
"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/webhookshowspausedAt, nothing is sent and new events are not queued. - To resume: call
PUT /v1/webhookagain (the same URL is fine) or get a successfulPOST /v1/webhook/test— events waiting in the queue are then sent. GET /v1/webhook/deliverieslists the latest 100 deliveries with their status, attempts and last error; history is kept for 7 days.
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
Keep polling as a fallbackdeliveryIds and skip repeats; for an order, rely on its newest data (otp, status) rather than on arrival order.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| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Your endpoint (http:// or https://, public address, at most 2048 characters) |
events | string[] | No | Which events to send: ["order.code", "order.cancelled"] (default both) |
curl
Python
Node.js
# 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"]}'{
"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_ERRORGET/v1/webhook
The webhook of your account, including its secret, pausedAt and consecutiveFailures. data is null when no webhook is registered.
Examplecurl
Python
Node.js
curl "https://onemail.wtf/v1/webhook" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"url": "https://your-server.example/otpgmail-webhook",
"events": [
"order.code",
"order.cancelled"
],
"enabled": true,
"secret": "9f2c6d1e8b7a4f3c5e0d2b1a6c9e8f7d3b5a1c2e4f6a8b0d9c7e5f3a1b2c4d6e",
"pausedAt": 1760705400,
"consecutiveFailures": 50,
"createdAt": 1760699000,
"updatedAt": 1760705400
}
}Possible errors: UNAUTHORIZEDDELETE/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.
Examplecurl
Python
Node.js
curl -X DELETE "https://onemail.wtf/v1/webhook" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"deleted": true
}
}Possible errors: UNAUTHORIZEDPOST/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.
Examplecurl
Python
Node.js
curl -X POST "https://onemail.wtf/v1/webhook/test" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": {
"ok": true,
"httpStatus": 200,
"durationMs": 143,
"error": null,
"deliveryId": "3c9a1e7f-2b4d-4c6e-8f0a-5d7b9c1e3a2f"
}
}Response 200 when your server does not answer 2xx
Possible errors: {
"success": true,
"data": {
"ok": false,
"httpStatus": 500,
"durationMs": 88,
"error": "HTTP 500",
"deliveryId": "7d2b9f4e-1c6a-4e3b-8d5f-0a9c2e7b1f4d"
}
}UNAUTHORIZED, NOT_FOUND, RATE_LIMITED, MAINTENANCEGET/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| Name | Type | Required | Description |
|---|---|---|---|
limit | number | No | Number of deliveries, 1–100 (default 100) |
curl
Python
Node.js
curl "https://onemail.wtf/v1/webhook/deliveries?limit=20" \
-H "Authorization: Bearer og_xxx..."{
"success": true,
"data": [
{
"id": "0b7e4c2a-5d1f-4e8b-9a3c-2f6d8e1b4a7c",
"event": "order.cancelled",
"orderId": "p8v2n5c1x7z3m9k4",
"status": "queued",
"attempts": 1,
"lastHttpStatus": 503,
"lastError": "HTTP 503",
"nextAt": 1760701640,
"createdAt": 1760701630,
"deliveredAt": null
},
{
"id": "6f1d2c3b-8a9e-4f70-b1c2-d3e4f5a6b7c8",
"event": "order.code",
"orderId": "k3m9x2p7q1w8e5r4",
"status": "delivered",
"attempts": 1,
"lastHttpStatus": 200,
"lastError": null,
"nextAt": null,
"createdAt": 1760700124,
"deliveredAt": 1760700125
}
]
}Possible errors: UNAUTHORIZED