API Documentation
Free Email API Documentation. Integrate disposable email into your application in minutes. No authentication required for public endpoints.
Quick Start - Get Started in 30 Seconds
Choose an email address
Use any address @catchmail.io or your own domain.
Send emails to that address
From your app, test suite, or manually.
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
API Endpoints
All endpoints return JSON responses.
List Mailbox Messages
Retrieve all messages for a specific email address. Returns message metadata including sender, subject, date, and size.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Full email address (e.g., test@catchmail.io) |
page | integer | No | Page number (default: 1) |
page_size | integer | No | Messages per page (default: 50) |
cURL Example
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 Message Details
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 | Yes | Message ID (path parameter) |
mailbox | string | Yes | Full email address |
cURL Example
curl "https://api.catchmail.io/api/v1/message/abc123?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 Message
Permanently delete a message. Returns 204 No Content on success.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Message ID (path parameter) |
mailbox | string | Yes | Full email address |
cURL Example
curl -X DELETE "https://api.catchmail.io/api/v1/message/abc123?mailbox=test@catchmail.io"Custom Domain Setup
Use your own domain for private, unlimited email addresses. They are perfectly private and great for testing.
DNS Configuration
1. Add MX Record
| Type | MX |
| Host | @ |
| Value | smtp.catchmail.io |
| Priority | 10 |
| TTL | 3600 |
2. Wait for Propagation: DNS changes can take up to 24-48 hours, but usually happen within minutes.
3. Start Using Your Domain: Any email sent to *@yourdomain.com will be catchable via the API!
Example with Custom Domain
# List messages for your custom domain
curl "https://api.catchmail.io/api/v1/mailbox?address=any@yourdomain.com"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 |