REST API REFERENCE 99.99% SLA

OTPMailbox Automation & Verification API

Seamlessly integrate automated disposable email mailboxes and instant OTP code extraction directly into your automation suites, CI/CD pipelines, and Python bots.

1. Platform Architecture & Base URL

All API requests must be issued over standard HTTPS. The OTPMailbox API delivers JSON responses and is fully backward-compatible with 5mail and standard verification protocols.

Production Base URL HTTPS only

https://otpmailbox.com

2. Authentication

To authenticate requests, generate an API token from your Developer Console and include it as a query parameter (token=YOUR_API_KEY) or Bearer header in your HTTP requests.

Query Parameter Format Standard GET

https://otpmailbox.com/api/code/email?token=YOUR_API_TOKEN&service=TM_DISCORD

15-Minute Defect Protection & Automated Escrow

When an order is placed, funds are placed in escrow. If the target platform fails to deliver an OTP verification email within the 15-minute lease window, our asynchronous auditing engine terminates the order and automatically refunds 100% of the cost to your wallet balance. You are only charged for verified codes.

3. REST API Endpoints

GET /api/public/products

No Auth Required

Returns the complete list of supported services, active product codes, starting prices, and live stock availability.

Example Response (JSON)

{
  "ok": true,
  "products": [
    {
      "product_code": "TM_DISCORD",
      "display_name_en": "Discord (Clean Domain)",
      "selling_price": 0.003,
      "live_stock": 9999,
      "is_active": true
    },
    {
      "product_code": "TM_OPENAI",
      "display_name_en": "ChatGPT / OpenAI (Clean Domain)",
      "selling_price": 0.004,
      "live_stock": 9999,
      "is_active": true
    }
  ]
}

GET /api/user/balance

Requires Token

Retrieve the real-time available wallet balance for your developer account.

Example Response

{
  "code": 0,
  "data": {
    "balance": 15.425
  },
  "message": "success"
}

GET /api/code/email

Requires Token

Provisions a fresh disposable email mailbox configured to receive verification codes for the requested platform.

Parameter	Type	Required	Description
token	string	Yes	Your developer API token
service	string	Yes	Product code (e.g. `TM_DISCORD`, `TM_TELEGRAM`, `TM_OPENAI`)

Example Response

{
  "code": 0,
  "data": {
    "uid": "ord_8f192b0c",
    "email": "[email protected]",
    "expires_at": 1729437200
  },
  "message": "success"
}

GET /api/code/fetch

Requires Token

Polls for the incoming OTP verification code using the order uid returned during mailbox allocation.

Example Response (When Code Received)

{
  "code": 0,
  "data": {
    "status": "completed",
    "code": "849201",
    "subject": "Your verification code is 849201",
    "received_at": "2026-10-20T11:42:10Z"
  },
  "message": "success"
}

4. Python Integration Example

Here is a complete, production-ready Python script to allocate a mailbox, poll for the code, and handle auto-refunds:

quickstart.py Python 3.8+

import time
import requests

API_TOKEN = "YOUR_API_TOKEN"
BASE_URL = "https://otpmailbox.com"

def get_discord_verification_code():
    # 1. Allocate Mailbox
    order_res = requests.get(f"{BASE_URL}/api/code/email", params={
        "token": API_TOKEN,
        "service": "TM_DISCORD"
    }).json()

    if order_res.get("code") != 0:
        raise Exception(f"Failed to allocate mailbox: {order_res.get('message')}")

    order_uid = order_res["data"]["uid"]
    allocated_email = order_res["data"]["email"]
    print(f"Allocated Email: {allocated_email} (UID: {order_uid})")

    # 2. Poll for verification code (up to 300 seconds)
    print("Waiting for incoming OTP code...")
    for _ in range(60):
        time.sleep(5)
        code_res = requests.get(f"{BASE_URL}/api/code/fetch", params={
            "token": API_TOKEN,
            "uid": order_uid
        }).json()

        code_data = code_res.get("data", {})
        if code_data.get("code"):
            print(f"Success! OTP Code: {code_data['code']}")
            return code_data["code"]

    print("Timeout expired. If no code was delivered, 100% of funds are refunded automatically.")
    return None

if __name__ == "__main__":
    get_discord_verification_code()

5. cURL CLI Examples

Terminal / Bash

# 1. Order a Discord disposable mailbox
curl -s "https://otpmailbox.com/api/code/email?token=YOUR_TOKEN&service=TM_DISCORD"

# 2. Check for incoming code by Order UID
curl -s "https://otpmailbox.com/api/code/fetch?token=YOUR_TOKEN&uid=ord_8f192b0c"

Start Automating Verification in Minutes

Top up your balance instantly with multi-currency crypto, generate your API key, and scale your workflows.

Access Developer Cockpit