REST API Reference

Base URL: https://api.spawnmail.sh

All endpoints require an API key via the x-api-key header unless noted.

Authentication

curl -H "x-api-key: sk_your_api_key" https://api.spawnmail.sh/me

Endpoints

Health Check

GET /health

No authentication required. Returns { "status": "ok" }.

Current User

GET /me

Returns the current user's info and inbox count.

Inboxes

Create Inbox

POST /inboxes
Content-Type: application/json

{ "ttl_seconds": 300, "password": "optional" }

Both fields are optional. Returns the created Inbox object.

Get Inbox

GET /inboxes/:id
X-Password: optional-password

Delete Inbox

DELETE /inboxes/:id
X-Password: optional-password

List Emails

GET /inboxes/:id/emails
X-Password: optional-password

Get Single Email

GET /inboxes/:id/emails/:emailId
X-Password: optional-password

Wait for Email (Long-Poll)

GET /inboxes/:id/wait
X-Password: optional-password

Blocks until an email arrives or timeout elapses. Returns the first new email or 408 Request Timeout.

Parameter	Type	Default	Description
timeout	query param (seconds)	120	Max wait time (1–120s)

Response Types

Inbox

{
  "id": "abc123",
  "address": "abc123@spawnmail.sh",
  "createdAt": "2026-03-03T12:00:00Z",
  "expiresAt": "2026-03-03T12:05:00Z",
  "isActive": true
}

Email

{
  "id": "email-uuid",
  "inboxId": "abc123",
  "sender": "noreply@example.com",
  "subject": "Verify your email",
  "bodyText": "Your code is 123456",
  "bodyHtml": "<p>Your code is 123456</p>",
  "receivedAt": "2026-03-03T12:01:00Z"
}

Error Responses

All errors return JSON with an error field:

{
  "error": "Inbox not found"
}

Status	Meaning
400	Bad request (invalid parameters)
401	Missing or invalid API key
403	Wrong password for protected inbox
404	Inbox or email not found
408	Long-poll timeout (no email arrived)
429	Rate limit exceeded