API reference

Authentication

Programmatic requests are authenticated with an API key. Create one from API keys in your dashboard. Send it in the X-API-KEY request header — this is the only accepted method.

X-API-KEY: ofm_live_xxx

Never put your API key in a URL (e.g. ?api-key=...) — query strings are written in plain text to server access logs, proxy logs, and browser history, and are the single most common way API keys leak. Query parameter authentication is not supported: a request that sends the key only as ?api-key=... is rejected with 400 Bad Request.

Base URL

Returns a random active disposable email address and reserves $0.002 (hold) from your balance.

curl -H "X-API-KEY: $KEY" "https://oneformail.com/get_mail?domain=mail&from=twitch.tv"

# 200
{ "mail": "abc@mail.com", "domain": "mail.com", "from": "twitch.tv",
  "balance": 9.998, "currency": "USD", "charged": 0.002,
  "request_id": 123, "multiple_mail": false }

Scans the inbox for the given email address. By default long-polls for ~80s; with waitotp=false checks once and returns immediately. In multiple_mail mode, each additional OTP costs an extra $0.002.

curl -H "X-API-KEY: $KEY" "https://oneformail.com/get_otp?mail=abc@mail.com"

# 200 (code found)
{ "mail": "abc@mail.com", "subject": "522322 - Your code",
  "sender": "Twitch <no-reply@twitch.tv>", "pending": false }

# 200 (no mail yet)
{ "mail": "abc@mail.com", "pending": true }

# multiple_mail mode — call again for the next OTP
curl -H "X-API-KEY: $KEY" "https://oneformail.com/get_otp?mail=abc@mail.com"
# each additional OTP is charged $0.002

Cancels the reservation and refunds the hold — but only if no mail has arrived yet, you have called /get_otp at least once for it, and you are within the refund window. (/release has been retired: it now always returns 410 Gone.)

curl -H "X-API-KEY: $KEY" "https://oneformail.com/cancel?request_id=123"

# 200
{ "mail": "abc@mail.com", "request_id": 123, "refunded": true,
  "balance": 10.000, "currency": "USD", "detail": "refunded successfully" }

Closes a multiple_mail session. Call this when you are done receiving OTPs on the address. Only works for addresses opened with multiple_mail=true.

curl -H "X-API-KEY: $KEY" "https://oneformail.com/finish_mail?mail=abc@mail.com"

# 200
{ "mail": "abc@mail.com", "status": "finished",
  "from": "twitch.tv", "balance": 9.994, "currency": "USD" }

Returns your current balance and the per-OTP unit price.

curl -H "X-API-KEY: $KEY" "https://oneformail.com/balance"

# 200
{ "balance": 9.998, "currency": "USD", "mail_cost": 0.002 }