How long are messages stored?

Messages are automatically deleted after 7 days. This ensures your privacy and keeps the service running efficiently for everyone.

Is the API really free?

Yes! Our public API is completely free to use with no authentication required. Fair usage limits apply to ensure service reliability for everyone.

Can I use my own domain?

Absolutely! Just point your domain's MX record to smtp.catchmail.io and you're ready to go. Your domain will be completely private - only you can access emails sent to it.

Do you read my emails?

Never. We have zero interest in your data. Messages are stored temporarily and automatically deleted. We don't track, analyze, or share anything.

What are the rate limits?

The API has a fair usage limit of 1 request per second per IP address. This ensures reliable service for everyone while remaining completely free to use.

Can I delete messages manually?

Yes! You can delete individual messages at any time through the web interface or via the DELETE API endpoint.

API Documentation - Free Email API for Developers

Quick Start

Get Started in 30 Seconds

1
Choose an email address
Use any address @catchmail.io or your own domain
2
Send emails to that address
From your app, test suite, or manually
3
Fetch messages via API
Use our REST API to read, list, or delete messages

curl "https://api.catchmail.io/api/v1/mailbox?address=test@catchmail.io"

Base URL

https://api.catchmail.io

Rate Limits

Anonymous Access

1 request per second per IP

With API Key

Higher limits available (contact us)

API Endpoints

All endpoints return JSON responses

GET

List Mailbox Messages

/api/v1/mailbox

Retrieve all messages for a specific email address. Returns message metadata including sender, subject, date, and size.

Parameters

Name	Type	Required	Description
address	string		Full email address (e.g., test@catchmail.io)
page	integer	-	Page number (default: 1)
page_size	integer	-	Messages per page (default: 50)

curl "https://api.catchmail.io/api/v1/mailbox?address=test@catchmail.io"

Response

{
  "address": "test@catchmail.io",
  "page": 1,
  "page_size": 50,
  "count": 2,
  "messages": [
    {
      "id": "abc123",
      "mailbox": "test@catchmail.io",
      "from": "sender@example.com",
      "subject": "Welcome!",
      "date": "2024-01-15T10:30:00Z",
      "size": 1234
    }
  ]
}

GET

Get Message Details

/api/v1/message/{id}

Retrieve the full content of a specific message, including headers, body (HTML and plain text), and attachment metadata.

Parameters

Name	Type	Required	Description
id	string		Message ID (path parameter)
mailbox	string		Full email address

curl "https://api.catchmail.io/api/v1/message/{message_id}?mailbox=test@catchmail.io"

Response

{
  "id": "abc123",
  "mailbox": "test@catchmail.io",
  "from": "sender@example.com",
  "to": ["test@catchmail.io"],
  "subject": "Welcome!",
  "date": "2024-01-15T10:30:00Z",
  "size": 1234,
  "headers": { ... },
  "body": {
    "text": "Plain text content",
    "html": "<html>HTML content</html>"
  },
  "attachments": [
    {
      "id": "att1",
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "size": 5678,
      "download_url": "/api/v1/attachment/att1?mailbox=test@catchmail.io"
    }
  ]
}

DELETE

Delete Message

/api/v1/message/{id}

Permanently delete a message. Returns 204 No Content on success.

Parameters

Name	Type	Required	Description
id	string		Message ID (path parameter)
mailbox	string		Full email address

curl -X DELETE "https://api.catchmail.io/api/v1/message/{message_id}?mailbox=test@catchmail.io"

Custom Domain Setup

Use your own domain for private, unlimited email addresses

DNS Configuration

Add MX Record

Go to your DNS provider and add the following MX record:

Type:     MX
Host:     @ (or your subdomain)
Value:    smtp.catchmail.io
Priority: 10
TTL:      3600

Wait for Propagation

DNS changes can take up to 24-48 hours to propagate, but usually happen within minutes.

Start Using Your Domain

That's it! Any email sent to *@yourdomain.com will be catchable via the API.

Using Your Custom Domain with the API

# After setting up MX record for yourdomain.com -> smtp.catchmail.io

# List messages for your custom domain
curl "https://api.catchmail.io/api/v1/mailbox?address=any@yourdomain.com"

# Any address works: support@, test@, user123@, etc.

Privacy Guarantee

Custom domains are completely private. They are never listed publicly, and only requests with the exact email address can access the messages. Perfect for CI/CD pipelines, automated testing, and private workflows.

Error Handling

All errors are returned with a consistent JSON structure:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before trying again."
  }
}

HTTP Status Codes

Code	Description
200	Success
204	Success (no content) - for DELETE operations
400	Bad request - invalid parameters
404	Not found - message or mailbox doesn't exist
429	Rate limit exceeded - slow down requests
500	Server error - try again later

Free Email API Documentation

Quick Start

Get Started in 30 Seconds

Base URL

Rate Limits

API Endpoints

List Mailbox Messages

Parameters

Response

Get Message Details

Parameters

Response

Delete Message

Parameters

Custom Domain Setup

DNS Configuration

Add MX Record

Wait for Propagation

Start Using Your Domain

Using Your Custom Domain with the API

Privacy Guarantee

Error Handling

HTTP Status Codes

Ready to Get Started?