OneMail
RU

API.

REST · JSON — buy emails and receive codes from your own code.

Getting started

All requests go to one base URL and return JSON. Authenticate with the API token from your account in the Authorization header.

Base URL
https://api.onemail-service.com
Header
Authorization: Bearer <token>

Limit — 120 requests per minute per token. Prices and stock match the website. Keep your token secret: it can spend your balance.

GET/balance

Balance

Current account balance.

Request · cURL
curl "https://api.onemail-service.com/balance" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "balance": 20.79,
  "currency": "USD"
}
GET/services

Services

Services, their emails and prices.

Request · cURL
curl "https://api.onemail-service.com/services" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "services": [
    {
      "id": 1,
      "site": "any",
      "domains": ["gmail", "hotmail", "outlook", "mail", "email", "gmx", "rambler"],
      "available": true,
      "price": {
        "gmail": 0.06,
        "hotmail": 0.04,
        "outlook": 0.04,
        "mail": 0.04,
        "email": 0.04,
        "gmx": 0.04,
        "rambler": 0.04
      }
    },
    {
      "id": 2,
      "site": "list",
      "domains": ["gmail"],
      "available": true,
      "price": {
        "gmail": null
      }
    },
    {
      "id": 3,
      "site": "any",
      "domains": ["gmail", "icloud", "outlook", "hotmail"],
      "available": true,
      "price": {
        "gmail": null,
        "icloud": null,
        "outlook": null,
        "hotmail": null
      }
    }
  ]
}
GET/stock

Stock

How many emails are available for a site — for each email in the service.

serviceintegerrequiredService number: 1, 2 or 3
sitestringrequiredSite domain, e.g. marktplaats.nl
Request · cURL
curl "https://api.onemail-service.com/stock?service=3&site=vinted.de" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "site": "vinted.de",
  "service": 3,
  "stock": {
    "gmail": 1256,
    "icloud": 10618,
    "outlook": 66081,
    "hotmail": 39115
  },
  "prices": {
    "gmail": 0.11,
    "icloud": 0.04,
    "outlook": 0.02,
    "hotmail": 0.02
  }
}
GET/catalog

Site catalog

Sites for the “site from list” service (2): what to pass as site when buying, stock and price. Price depends on the site.

serviceintegerrequiredService number: 2
Request · cURL
curl "https://api.onemail-service.com/catalog?service=2" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "service": 2,
  "domain": "gmail",
  "sites": [
    {
      "site": "instagram.com",
      "name": "Instagram",
      "stock": 120,
      "price": 0.03
    },
    {
      "site": "telegram.org",
      "name": "Telegram",
      "stock": 0,
      "price": 0.06
    }
  ]
}
POST/orders

Buy email

Buys an address. Charged immediately; refunded if no code arrives within 20 minutes.

serviceintegerrequiredService number: 1, 2 or 3
sitestringrequiredSite domain; for Service 2 — site from the catalog
domainstringoptionalThe service’s email: gmail, icloud, outlook, hotmail… Defaults to gmail
Request · cURL
curl -X POST "https://api.onemail-service.com/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":1,"site":"marktplaats.nl","domain":"gmail"}'
Response · 200 OK
{
  "id": "ord_8f2kq1",
  "email": "theo.vance44@gmail.com",
  "status": "waiting",
  "price": 0.06,
  "expires_in": 1200
}
GET/orders

My orders

Active orders (waiting for an email or received recently) or history.

scopestringoptionalactive or history. Defaults to active
limitintegeroptionalHow many to return, up to 500. Defaults to 100
offsetintegeroptionalHow many to skip — for paging
Request · cURL
curl "https://api.onemail-service.com/orders?scope=active" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "orders": [
    {
      "id": "ord_8f2kq1",
      "service": 1,
      "site": "marktplaats.nl",
      "domain": "gmail",
      "email": "theo.vance44@gmail.com",
      "status": "waiting",
      "price": 0.06,
      "expires_in": 1105
    }
  ]
}
GET/orders/{id}

Status and code

Order status: waiting, received, cancelled, refunded or expired. Once the email arrives — the code or a link.

idstringrequiredorder id from the purchase response
Request · cURL
curl "https://api.onemail-service.com/orders/ord_8f2kq1" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "id": "ord_8f2kq1",
  "status": "received",
  "type": "code",
  "code": "611402",
  "has_message": true
}
GET/orders/{id}/message

Full email

The full email — Services 1 and 3. The code and link from the email are here too.

idstringrequiredorder id
Request · cURL
curl "https://api.onemail-service.com/orders/ord_8f2kq1/message" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "from": "Marktplaats <noreply@marktplaats.nl>",
  "subject": "Confirm your email address",
  "received_at": "2026-11-06T19:38:12Z",
  "code": null,
  "link": "https://www.marktplaats.nl/confirm?t=…",
  "html": "<html>…</html>"
}
POST/orders/{id}/cancel

Cancel

Cancels an order before the email arrives. The money returns to your balance.

idstringrequiredorder id
Request · cURL
curl -X POST "https://api.onemail-service.com/orders/ord_8f2kq1/cancel" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "id": "ord_8f2kq1",
  "status": "cancelled",
  "refunded": 0.06
}
POST/orders/{id}/repeat

Repeat code

One more email to the same address — Services 1 and 3, after the first email. $0.025, non-refundable: if no email arrives within 20 minutes the status becomes expired. Cannot be cancelled. If the address is blocked — 409 email_unavailable.

idstringrequiredorder id
Request · cURL
curl -X POST "https://api.onemail-service.com/orders/ord_8f2kq1/repeat" \
  -H "Authorization: Bearer $TOKEN"
Response · 200 OK
{
  "id": "ord_3m9xq2",
  "email": "theo.vance44@gmail.com",
  "status": "waiting",
  "price": 0.025,
  "refundable": false,
  "repeat_of": "ord_8f2kq1",
  "expires_in": 1200
}

Errors

400invalid_requestInvalid request parameters
401invalid_tokenMissing or invalid token
402insufficient_balanceNot enough balance
403forbiddenOnly available in your account on the website
404not_foundOrder or site not found
409out_of_stockNo emails in stock for this site
409cancel_too_earlyYou can cancel 2–3 minutes after buying
409email_unavailableThe mailbox is blocked — no repeat code
429rate_limitedToo many requests — slow down
503temporarily_unavailableService temporarily unavailable — try again later