Gmail OTP API: Rent an Inbox, Read the Code

Q: Can I rent more than one inbox in a single call?

Yes. POST /v1/orders accepts a quantity field (default 1, up to 200 per request); the response array then contains one entry per inbox.

Updated October 13, 2026 · 6 min read

Signing up a bot, a test suite, or a piece of internal tooling for a third-party service almost always starts the same way: give it an email address, then read the verification code that address receives. The OTPGmail API rents that address — a real @gmail.com or @icloud.com inbox — for exactly as long as you need it, and hands the code back to your code as soon as it arrives. No mailbox to log into, no account to maintain afterward. This page is the overview; two worked examples and a testing-focused guide go deeper into the code.

Need an account you can sign in to rather than just a code? See buy short-lived Gmail accounts (also available through the mail-shop endpoints of this API, /v1/mail-shop).

How the API is put together

Every call is made over HTTPS to your account's base URL — otpgmail.net — and is authenticated with your own API key, from the Account page, sent as Authorization: Bearer <api_key> (or ?api_key= when a header is inconvenient). Every response is wrapped the same way: { "success": true, "data": ... } on success, or { "success": false, "error": { "code", "message" } } with a matching HTTP status on failure — so a client only has to branch on success once.

There are three calls you will use for almost everything:

GET /v1/services — the catalog: service codes, Gmail price and stock, and an icloud block (or null if that service has no iCloud option).
POST /v1/orders — rents an inbox for one service.
GET /v1/orders/{orderId} — the order's current status and any codes received so far.

Renting an inbox

POST /v1/orders
Authorization: Bearer <api_key>
Idempotency-Key: <a new UUID per order>

{ "service": "git", "domain": "gmail.com" }

service is a short code from GET /v1/services (git for GitHub, dr for ChatGPT, and so on). domain is optional and defaults to gmail.com; send "icloud.com" for the iCloud inbox type (usually the cheaper one) where it is offered. You are charged only once an inbox is actually issued — a failed attempt never touches your balance. The response is an array of orders (one call can rent more than one inbox with a quantity field), each with orderId, email, status, otp: [], codeDeadlineAt and rentExpiresAt.

Creating an order usually takes well under a second, but can take longer at peak load, so give the call a client timeout of around 15 seconds rather than retrying after five.

Reading the code

Poll GET /v1/orders/{orderId} every 3–5 seconds. While nothing has arrived, status is waiting_code; the moment the first code lands, it flips to completed and otp gains an entry — oldest first, so the newest code is the last element. From that point, further codes (a login, a device confirmation) are appended to the end of otp while the order can still receive them. 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. Many services send only one code per inbox. Where an order allows it, POST /v1/orders/{orderId}/next-code opens a new wait for another code and POST /v1/orders/{orderId}/rerent rents the same inbox again (when canRerent is true); any charge shows in the order's nextCodeFee and rerentPriceVnd fields before you call them. The code limit and time window for each service are listed in GET /v1/services and in the API docs.

If the order is no longer useful — you gave up, or signed up a different way — POST /v1/orders/{orderId}/cancel refunds it in full, as long as no code has arrived yet. Left alone, an order with no code cancels and refunds itself automatically when its waiting time ends (25 minutes at most).

Idempotency and retries

Network calls fail in the middle sometimes, and a rental should never be created twice by accident. Send an Idempotency-Key header — a fresh UUID — with every POST /v1/orders call. If the request times out and you retry with the same key, the API returns the order it already created instead of renting a second inbox; a new order needs a new key. It costs one line of code and removes an entire category of double-charged bugs.

Gmail or iCloud

Both inbox types work the same way — same endpoints, same default refund rule. The differences are practical: iCloud inboxes are usually cheaper than Gmail, depending on the service, and cover most services (a few are Gmail-only — Apple ID, for example, since an @icloud.com address already belongs to an Apple ID of its own), but iCloud stock can run dry for a while. A common pattern is to request icloud.com first and fall back to gmail.com on DOMAIN_UNAVAILABLE or NO_MAILS_AVAILABLE. Check the icloud field on GET /v1/services before assuming a service supports it.

Errors and rate limits

The error codes you will hit most: VALIDATION_ERROR (bad service code or parameter), INSUFFICIENT_BALANCE (top up and retry), NO_MAILS_AVAILABLE (the provider is temporarily out for that service — nothing was charged), and DOMAIN_UNAVAILABLE (that service has no iCloud option, or iCloud is briefly disabled — switch to gmail.com). Calls are rate limited per API key — by default 20 requests per second, 900 per minute — and going over returns HTTP 429 with a Retry-After header telling you how long to wait.

None of this needs memorizing up front: the API docs list every field and error code, and the worked examples below show a complete request-to-code loop.

Where to go next

Gmail OTP API in Python — a minimal script using requests.
Gmail OTP API in Node.js — the same flow with fetch.
Renting Gmail inboxes for testing sign-up flows — how QA teams fit this into a suite, including a GitHub sign-up as a running example.
Prefer a browser to a terminal? Gmail for OTP covers the same rentals through the web form, no code required.

Get your key on the rent page, check live prices on the service list, starting from $0.010 (250 VND), and keep the API docs open while you build. Whatever you automate, keep it inside the target service's own terms — OTPGmail is not responsible for accounts used to mislead people, commit fraud, or otherwise break a service's rules.

Frequently asked questions

Do I need a paid plan to use the API?

No separate plan. Every account gets an API key on the Account page, and you pay per inbox from your regular balance, the same balance used for rentals on the web.

Can I rent more than one inbox in a single call?

Yes. POST /v1/orders accepts a quantity field (default 1, up to 200 per request); the response array then contains one entry per inbox.

What happens if I poll faster than every 3–5 seconds?

Nothing arrives any sooner — the sending service, not your polling rate, decides that — and you burn through your rate limit faster for no benefit.

Is there a client library?

Not an official package, but runnable examples for Python, Node.js, PHP, C# and curl live in a public repository linked from the API docs; the Python and Node.js guides walk through the same code.

Does the API support the bulk rental feature?

Bulk rental (1 to 200 Gmail or iCloud inboxes per batch, at the same unit price as a single rental) is bought on the web; the API can list your batches and read their codes, but batch purchases themselves are a web-only flow for now.