API Reference

Programmatically create inboxes and read emails at scale. All endpoints return JSON.

Sign in to generate an API key
All API requests require a Bearer token.
Sign In
Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer ct_your_api_key_here
BASE URLhttps://catchthis.email/api/v1
Quick Start
# Create an inbox
curl -X POST https://catchthis.email/api/v1/inboxes/create \
  -H "Authorization: Bearer ct_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice"}'

# Bulk claim inboxes
curl -X POST https://catchthis.email/api/v1/inboxes/create/bulk \
  -H "Authorization: Bearer ct_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '["alice", "bob", "test-signup"]'

# List your inboxes
curl https://catchthis.email/api/v1/inboxes/list \
  -H "Authorization: Bearer ct_your_api_key_here"

# Read emails
curl https://catchthis.email/api/v1/inboxes/alice@ilovemyemail.net/emails \
  -H "Authorization: Bearer ct_your_api_key_here"
Endpoints
POST/inboxes/create

Create a single inbox. Random address if no username provided.

Body (optional)
usernamestringUsername part — auto-sanitized to lowercase
domainstringDefaults to ilovemyemail.net
curl -X POST https://catchthis.email/api/v1/inboxes/create \
  -H "Authorization: Bearer ct_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"username": "myapp-test"}'
Response 201
{
  "address": "myapp-test@ilovemyemail.net",
  "domain": "ilovemyemail.net",
  "private": true,
  "created_at": "2026-03-18T12:00:00.000Z"
}
POST/inboxes/create/bulk

Claim up to 10,000 inboxes in one request. Usernames without @ get @${d} appended automatically.

Body (JSON array)
curl -X POST https://catchthis.email/api/v1/inboxes/create/bulk \
  -H "Authorization: Bearer ct_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '["alice", "bob", "signup-test@ilovemyemail.net"]'
Response 201
{
  "count": 3,
  "addresses": [
    { "address": "alice@ilovemyemail.net", "domain": "ilovemyemail.net", "private": true },
    { "address": "bob@ilovemyemail.net", "domain": "ilovemyemail.net", "private": true },
    { "address": "signup-test@ilovemyemail.net", "domain": "ilovemyemail.net", "private": true }
  ]
}
GET/inboxes/list

List your inboxes with email counts. Cursor-based pagination for scale.

Query Parameters
limitintResults per page (1–200, default 50)
cursorintCursor from previous response for next page
curl "https://catchthis.email/api/v1/inboxes/list?limit=100" \
  -H "Authorization: Bearer ct_your_api_key_here"
Response 200
{
  "data": [
    {
      "id": 42,
      "address": "alice@ilovemyemail.net",
      "domain": "ilovemyemail.net",
      "email_count": 3,
      "private": true,
      "created_at": "2026-03-18T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": true,
    "next_cursor": 41
  }
}

To get the next page, pass ?cursor=41 from pagination.next_cursor.

GET/inboxes/:address/emails

Fetch emails for an inbox. Supports cursor pagination and format control.

Query Parameters
limitintResults per page (1–200, default 50)
cursorintCursor for next page
formatstringfull (default) includes text + html. metadata returns only id, from, to, subject, received_at.
# Full content (text + html)
curl "https://catchthis.email/api/v1/inboxes/alice@ilovemyemail.net/emails?limit=10" \
  -H "Authorization: Bearer ct_your_api_key_here"

# Metadata only (faster, no content fetching)
curl "https://catchthis.email/api/v1/inboxes/alice@ilovemyemail.net/emails?format=metadata" \
  -H "Authorization: Bearer ct_your_api_key_here"
Response 200 (full)
{
  "address": "alice@ilovemyemail.net",
  "data": [
    {
      "id": 99,
      "from": "noreply@github.com",
      "to": "alice@ilovemyemail.net",
      "subject": "Verify your email",
      "text": "Click the link below...",
      "html": "<html>...</html>",
      "headers": { "message-id": "<abc@mail.github.com>" },
      "received_at": "2026-03-18T12:05:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "has_more": false,
    "next_cursor": null
  }
}
GET/inboxes/:address/emails/:id

Get a single email with full content including raw MIME source.

curl https://catchthis.email/api/v1/inboxes/alice@ilovemyemail.net/emails/99 \
  -H "Authorization: Bearer ct_your_api_key_here"
Response 200
{
  "id": 99,
  "from": "noreply@github.com",
  "to": "alice@ilovemyemail.net",
  "subject": "Verify your email",
  "text": "Click the link below...",
  "html": "<html>...</html>",
  "raw": "MIME-Version: 1.0\r\nFrom: ...",
  "headers": { "message-id": "<abc@mail.github.com>" },
  "received_at": "2026-03-18T12:05:00.000Z"
}
Error Codes
401Missing or invalid API key
403Address is private and not owned by you
404Email not found
400Invalid request body or parameters
Pagination

All list endpoints use cursor-based pagination. Pass the next_cursor value from the response as the cursor query parameter to fetch the next page.

# Page 1
GET /api/v1/inboxes/list?limit=100
# → pagination.next_cursor = 42

# Page 2
GET /api/v1/inboxes/list?limit=100&cursor=42
# → pagination.next_cursor = null (last page)
Performance Tips

Use ?format=metadata on list endpoints when you only need subjects and timestamps — it's significantly faster than fetching full email content.