Disposi API

A free, unauthenticated REST API for reading disposable inboxes and managing domains. Every endpoint is rate-limited per IP; there is no API key and no outbound-send endpoint, this API can only receive and read mail, never send it.

Base URL

https://disposi.biz.ua

Conventions

Errors always return a JSON body shaped like { "detail": "..." }.
Pagination uses ?page=1&limit=20 query params where noted.
Rate-limited responses return 429 with a Retry-After header (seconds).
Any parameter shaped like an email address is validated as strict user@domain before use.

GET/api/email/:domain/:user/

List messages for user@domain, newest first. Lazily creates the address if it doesn't exist yet (as long as the domain is online), you don't need to generate an address before reading it.

Query params: page (default 1), limit (default 20, max 100)

curl "https://disposi.biz.ua/api/email/disposi.biz.ua/hello/?limit=20"

import requests
r = requests.get("https://disposi.biz.ua/api/email/disposi.biz.ua/hello/", params={"limit": 20})
print(r.json())

const res = await fetch("https://disposi.biz.ua/api/email/disposi.biz.ua/hello/?limit=20");
const data = await res.json();

GET/api/email/:domain/:user/:emailId

Full detail for one message: subject, sender, date, plain-text body, sanitized HTML body, and has_attachments.

curl "https://disposi.biz.ua/api/email/disposi.biz.ua/hello/{emailId}"

DELETE/api/email/:domain/:user/:emailId

Delete one message. Returns { "status": "deleted" }.

curl -X DELETE "https://disposi.biz.ua/api/email/disposi.biz.ua/hello/{emailId}"

POST/api/add-domain/:domain

Point a domain's MX at Disposi and register it, or refresh its live online status if it's already registered. Never claims ownership; anyone can add a domain anonymously. Returns { status: "added"|"updated", domain, is_online }.

curl -X POST "https://disposi.biz.ua/api/add-domain/yourdomain.com"

GET/api/all-domains/

List every domain currently online (MX verified), owned or not.

Query params: page (default 1), limit (default 20, max 100)

curl "https://disposi.biz.ua/api/all-domains/"

GET/api/random-domains/

A random sample of online domains, useful for picking a domain before generating a random address.

Query params: page (default 1), limit (default 10, max 50)

curl "https://disposi.biz.ua/api/random-domains/?limit=5"

GET/api/check-mx/:domain

Live DNS check, no database write. Returns { "result": "online" | "offline" }.

curl "https://disposi.biz.ua/api/check-mx/yourdomain.com"

Error handling

400 for malformed input (e.g. an invalid user@domainshape or domain), 404 when the domain, address, or message doesn't exist (or a domain isn't online), 429 when you've been rate-limited, 500 on an unexpected server error. Every non-2xx response body is { "detail": "human-readable message" }.