VOIDMAIL / API V1

An inbox for your next idea.

Create disposable addresses, read messages, and clean up from your own application.

Authenticate

Ask the site operator for an API key. Send it in the Authorization header over HTTPS. Never put it in a URL or public browser code.

Authorization: Bearer YOUR_API_KEY

Endpoints

Method	Path	Scope
GET	`/api/v1/domains`	`domains:read`
POST	`/api/v1/inboxes`	`inboxes:write`
GET	`/api/v1/inboxes`	`inboxes:read`
DELETE	`/api/v1/inboxes/{uuid}`	`inboxes:write`
GET	`/api/v1/inboxes/{uuid}/messages`	`messages:read`
GET	`/api/v1/inboxes/{uuid}/messages/{id}`	`messages:read`
GET	`/api/v1/inboxes/{uuid}/messages/{id}/attachments/{attachment}`	`messages:read`
DELETE	`/api/v1/inboxes/{uuid}/messages/{id}`	`messages:delete`

Create an inbox

curl -X POST 'https://demo.voidmail.email/api/v1/inboxes' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

Optional fields: domain_id (from the domains endpoint), alias (4–24 letters, digits, dashes or underscores; only when custom aliases are enabled).

{"data":{"id":"inbox-uuid","address":"example@domain.test","expires_at":"2026-10-19T12:00:00Z"}}

Read messages

curl 'https://demo.voidmail.email/api/v1/inboxes/{uuid}/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Lists are paginated with ?page=2 and return data plus meta.page and meta.last_page. Message details include body_text, sanitized body_html, and attachment download URLs. Use the same Authorization header for downloads.

Limits and errors

Each key has a request limit and an active inbox cap. Keys can only access inboxes they created. Expired inboxes return 404. Deletion returns 204. Use Retry-After on 429 responses; do not retry in a tight loop.

401 — Missing, expired or revoked key
403 — Required permission is missing
404 — Not found, not owned or expired
422 — Invalid input or inbox limit reached
429 — Rate limit reached

Keep keys on your server. Revoke them immediately if exposed.