API documentation

Overview

https://otpgmail.net

Endpoints

curl "https://otpgmail.net/v1/balance" \
  -H "Authorization: Bearer og_xxx..."

{
  "success": true,
  "data": {
    "balance": 25000
  }
}

curl "https://otpgmail.net/v1/services" \
  -H "Authorization: Bearer og_xxx..."

{
  "success": true,
  "data": [
    {
      "code": "ig",
      "name": "Instagram",
      "price": 1060,
      "stock": 342,
      "icloud": {
        "price": 950,
        "stock": 120
      }
    },
    {
      "code": "tg",
      "name": "Telegram",
      "price": 530,
      "stock": 1200,
      "icloud": {
        "price": 480,
        "stock": 860
      }
    },
    {
      "code": "fb",
      "name": "Facebook",
      "price": 1590,
      "stock": 88,
      "icloud": null
    }
  ]
}

# 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)
curl -X POST "https://otpgmail.net/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
    }
  ]
}

curl "https://otpgmail.net/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
  }
}

curl -X POST "https://otpgmail.net/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
  }
}

Order lifecycle

• 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.
• After 30 minutes without a code, the system cancels the order and refunds 100% (status = cancelled).
• The otp[] array is ordered oldest first, newest last. Read the latest code with otp[otp.length - 1] (Python: otp[-1]).
• A completed order keeps receiving codes for free for 24 hours after it was created, and it does so automatically — no extra call is needed. Right after each code, the system is already listening for the next one. Just keep polling GET /v1/orders/{id}; new codes show up at the end of otp[].
• 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.
• POST /v1/orders waits for the provider to allocate an inbox, so it usually takes ~0.3 seconds but can take up to 10 seconds at peak times (rare). Set a client timeout of ≈ 15 seconds rather than giving up after 5 seconds and retrying early — and when you do retry, reuse the same Idempotency-Key.
• An order that has received a code cannot be cancelled or refunded — the cancel call returns ORDER_NOT_CANCELLABLE.
• To rent an @icloud.com inbox, send "domain": "icloud.com" when creating the order (omit it for Gmail; existing bots need no changes). If the service does not support iCloud, or iCloud is temporarily disabled, you get DOMAIN_UNAVAILABLE — switch to Gmail and the rental goes through right away. The lifecycle, the cancellation and refund rules, and the way you read codes are exactly the same as for Gmail.

Rate limits

• 10 requests/second — short bursts over a few seconds
• 300 requests/minute — total traffic per minute

Error codes