MailSMMO
Sign in

// REST API

REST API documentation

Tool endpoints use GET and return JSON shaped like { "status": "success", "data": … }. Authenticate with the ?api_key= parameter from the API Docs page after signing in.

Endpoints

Base URL: https://mailsmmo.com

GET/api/v1/services

Services — price & stock

Without ?service= it returns the whole list. With ?service= it returns the price and stock of one service. No API key needed.

No auth

  • service (optional) — Leave empty for the whole list; a code returns one service (bare codes like facebook are accepted)

Success

{ "status": "success", "data": { "services": [
    { "code": "otp_gmail_facebook", "name": "Facebook", "price": 5000, "stock": 42 }
  ] } }

GET/api/v1/me

Account info

ID, email and balance of the API key making the call.

API key required

Success

{ "status": "success", "data": { "id": "b7e5...-uuid", "email": "demo@mailsmmo.com", "balance": 1000000, "created_at": "2026-01-15T08:30:00Z" } }

GET/api/v1/orders

Create order

One endpoint for both: a Gmail OTP code (otp_gmail_*) issues one OTP mailbox; a stock product code (hotmail_*…) buys by quantity. The balance is charged at the listed price.

API key required

  • service — OTP service code (otp_gmail_*) or stock product code (e.g. hotmail_imap_12m_36m)
  • quantity (optional) — Only for one-off sold emails — quantity (default 1)
  • unique_key (optional) — Self-generated UUID — resending will not create or charge twice

Success

{ "status": "success", "data": {
    "id": "b7e5a1c2-3d4e-4f60-8a91-2c3d4e5f6a7b", "email": "zurhansuzu@gmail.com",
    "service": "otp_gmail_facebook", "amount": 5000
  } }

GET/api/v1/orders/otp

Get OTP by order

Reads the OTP of one order. No API key needed — the order code (order_id) is the capability key.

No auth

  • order_id — Order code (returned when the order is created)
  • unique_key (optional) — A fresh self-generated UUID for each call
  • from (optional) — Unix seconds — otp/received_at are omitted unless a newer code exists

Success

{ "status": "success", "data": {
    "otp": "481253", "amount": 5000, "received_at": 1732000000,
    "from": "security@facebookmail.com", "otp_history": [
      { "value": "481253", "received_at": 1732000000 }
    ] } }

GET/api/v1/otp/orders

OTP order list

Rented Gmail OTP orders, paginated, with the latest OTP of each order.

API key required

  • page (optional) — Page (default 1)
  • page_size (optional) — Rows per page (default 20, max 200)

Success

{ "status": "success", "data": { "orders": [
    { "id": "b7e5a1c2-3d4e-4f60-8a91-2c3d4e5f6a7b", "email": "...", "service": "otp_gmail_facebook",
      "latest_otp": "481253", "latest_link": null }
  ], "page": 1, "page_size": 20, "total": 137 } }

GET/api/v1/mail

Read all messages

All messages of one mailbox, with the extracted OTP/link.

API key required

  • order_id — Order code

Success

{ "status": "success", "data": { "count": 1, "messages": [
    { "id": 88, "from": "...", "subject": "...", "otp": "481253", "received_at": "..." }
  ] } }

common error codes

{ "status": "error", "message": "out_of_stock", "retryable": true }
  • unauthorized — API key is invalid or missing (HTTP 401)
  • invalid_request — Invalid request parameters (HTTP 400)
  • not_found — Service, order or endpoint not found (HTTP 404)
  • insufficient_balance — Insufficient balance (HTTP 402)
  • out_of_stock — Out of stock (HTTP 409) — Gmail OTP: retryable, retry in a few seconds; outright-sale email: wait for restock
  • service_unavailable — Server could not finish the order right now — retry with the same unique_key (HTTP 503, retryable)
  • in_progress — Order is being finalized or may already exist at the provider — retry with the same unique_key (HTTP 409, retryable)
  • forbidden — No permission for the resource (HTTP 403)
  • idempotency_mismatch — unique_key was used for a different request — use a new unique_key (HTTP 422)
  • order_cancelled — Order was released before it was charged, nothing charged — retry (HTTP 409, retryable)
  • too_many_requests — Too many requests — wait and retry (HTTP 429, retryable)
  • auth_unavailable — API key couldn't be checked right now, the key is fine — retry (HTTP 503, retryable)
  • shutting_down — Server is restarting — retry in a few seconds (HTTP 503, retryable)
  • payload_too_large — Request body too large (HTTP 413)
  • internal_server_error — Server error, please try again later (HTTP 500)

Docs for AI and tools

The full documentation in Markdown lives at https://mailsmmo.com/llms.txt — paste it into Cursor, Claude or ChatGPT to generate integration code.

Safe retries with unique_key

Send a unique_key (a self-generated UUID) with every order. If the network drops, retry with the same unique_key: you get the same order back, with no new order and no second charge.

Error format

On error the response contains only status, message (a snake_case error code) and retryable, which tells you whether to try again.

Get started with MailSMMO

Sign up for free, top up your wallet and rent your first mail in minutes.

Create account →