REST API

Returns JSON array of all messages with basic metadata.

curl http://127.0.0.1:1080/messages

Response

[
  {
    "id": 1,
    "from": ["sender@example.com"],
    "to": ["recipient@example.com"],
    "subject": "Test Email",
    "created_at": "2024-01-10T10:30:00Z"
  }
]

Returns detailed metadata for a specific message including headers, sender, recipients, and body info.

curl http://127.0.0.1:1080/messages/1.json

Returns the HTML version of the message rendered in the browser.

curl http://127.0.0.1:1080/messages/1.html

Returns the plain text version of the message.

curl http://127.0.0.1:1080/messages/1.plain

Returns the complete raw email source in MIME format.

curl http://127.0.0.1:1080/messages/1.source

Downloads the message as an EML file (RFC 822), suitable for importing into email clients.

curl -O http://127.0.0.1:1080/messages/1.eml

Returns the SMTP transcript including all commands, responses, and TLS details for debugging connection issues.

curl http://127.0.0.1:1080/messages/1/transcript.json

Includes

• • Session ID and client/server connection details
• • TLS protocol version and cipher suite
• • Complete SMTP command/response transcript
• • Connection timing information

Returns SMTP transcript rendered as an HTML page for viewing in a browser.

curl http://127.0.0.1:1080/messages/1.transcript

Downloads a specific message part or attachment by its Content-ID.

# First, get the message metadata to find attachment CIDs
curl http://127.0.0.1:1080/messages/1.json | jq '.parts'

# Then download the attachment
curl -O http://127.0.0.1:1080/messages/1/parts/image-001

Search messages across subject, sender, recipient, and body content with optional filtering.

Query Parameters

curl "http://127.0.0.1:1080/messages/search?q=verification&has_attachments=false"

curl "http://127.0.0.1:1080/messages/search?q=noreply@example.com&from=2024-01-01&to=2024-01-31"

Extracts verification tokens, magic links, OTP codes, or reset tokens from message content.

Query Parameters

# Extract OTP code
curl "http://127.0.0.1:1080/messages/1/extract?type=otp"

# Extract magic link
curl "http://127.0.0.1:1080/messages/1/extract?type=link"

# Extract reset token
curl "http://127.0.0.1:1080/messages/1/extract?type=token"

Returns all links found in the message with metadata about their purpose (verification, unsubscribe, etc).

curl http://127.0.0.1:1080/messages/1/links.json

Returns comprehensive structured data parsed from the message including verification URLs, OTP codes, reset tokens, and all links.

curl http://127.0.0.1:1080/messages/1/parsed.json

Analyzes HTML email for accessibility issues and returns a score (0-100) with recommendations.

Score Breakdown

• • images_with_alt - Percentage of images with alt text
• • semantic_html - Use of semantic HTML tags
• • score - Overall accessibility score (0-100)

curl http://127.0.0.1:1080/messages/1/accessibility.json

Returns server configuration and status information.

Response Includes

• • MailCatcher version
• • HTTP and SMTP server ports
• • Hostname and IP addresses
• • Connection counts and statistics

curl http://127.0.0.1:1080/server-info

Upgrades the HTTP connection to WebSocket for receiving real-time notifications about new messages, deletions, and clears.

Message Types

• • add - New message arrived
• • remove - Message was deleted
• • clear - All messages cleared

const ws = new WebSocket('ws://127.0.0.1:1080/messages');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'add') {
    console.log('New message:', data.message);
  } else if (data.type === 'remove') {
    console.log('Message deleted:', data.id);
  }
};