API Reference

Pro Plan

The REST API gives you programmatic access to manage webhooks, query mails, and view statistics. All endpoints require an API key.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer rfk_your_api_key_here

Create API keys in Dashboard > Settings > API Keys. Keys start with rfk_.

Rate Limits

100 requests per minute per API key. Rate limit headers are returned on every response:

X-RateLimit-Remaining — requests left in window
X-RateLimit-Reset — Unix timestamp when window resets

Endpoints

GET

/api/v1/mails

List stored emails with pagination and search

Query params: limit (1-100), offset, search, status

curl -H "Authorization: Bearer rfk_..." \
  "https://your-domain.com/api/v1/mails?limit=10&search=invoice"

{
  "success": true,
  "data": {
    "mails": [{
      "id": "mail_abc123",
      "fromAddress": "sender@example.com",
      "toAddress": "you@example.com",
      "subject": "Invoice #123",
      "receivedAt": "2025-01-15T10:30:00Z"
    }],
    "total": 42, "limit": 10, "offset": 0
  }
}

GET

/api/v1/mails/:id

Get a single mail with full body content

curl -H "Authorization: Bearer rfk_..." \
  "https://your-domain.com/api/v1/mails/mail_abc123"

GET

/api/v1/webhooks

List all configured webhooks

curl -H "Authorization: Bearer rfk_..." \
  "https://your-domain.com/api/v1/webhooks"

POST

/api/v1/webhooks

Create a new webhook endpoint

curl -X POST -H "Authorization: Bearer rfk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Inbox",
    "sharedSecret": "my-secret-at-least-12",
    "forwardEmails": ["me@example.com"]
  }' \
  "https://your-domain.com/api/v1/webhooks"

DELETE

/api/v1/webhooks/:id

Delete a webhook

curl -X DELETE -H "Authorization: Bearer rfk_..." \
  "https://your-domain.com/api/v1/webhooks/webhook_abc123"

GET

/api/v1/stats

Get aggregated usage statistics

{
  "success": true,
  "data": {
    "webhookCount": 3,
    "mailCount": 1250,
    "deliveryCount": 3600,
    "currentPeriod": { "mailCount": 450 }
  }
}

Error Codes

Status	Meaning
400	Bad request / invalid parameters
401	Invalid or missing API key
403	Free plan (API requires Pro)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

{
  "success": false,
  "error": "Description of what went wrong"
}