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 }

Scans the inbox for the given email address for ~80s; if a matching message arrives, returns its contents and captures the charge.

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 }

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. Use /cancel — same parameters, same behaviour.)

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

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

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 }