REST API Reference

Base URL: https://api.spawnmail.sh (cloud) or http://localhost:8000 (self-hosted).

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

Authentication

curl -H "x-api-key: fm_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": 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 up to 120 seconds until an email arrives. Returns the first new email or 408 Request Timeout.

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 a message field:

{
  "message": "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