REST API reference

Authentication

Create a key under Settings → API keys and send it as a bearer token. Keys start with mxc_, are shown once, and can be revoked at any time.

curl https://www.mxcatch.net/api/v1/domains \
  -H "Authorization: Bearer mxc_your_key_here"

Status	Meaning
401	Missing, malformed or revoked key.
402	The key's account is not on a plan with API access.
404	The domain or message does not exist, or is not shared with you.
422	Validation failed. The body lists the fields that failed.
429	More than 120 requests in a minute. Back off and retry.

Domains

Endpoint	Description
GET /api/v1/domains	All domains you own or were invited to.
GET /api/v1/domains/{name}	One domain, addressed by its name, e.g. /domains/acme.com.

{
  "data": {
    "name": "acme.com",
    "verified": true,
    "mx_healthy": true,
    "verified_at": "2026-10-02T08:11:45+00:00",
    "sending_enabled": false,
    "spam_action": "tag",
    "aliases_count": 4,
    "emails_count": 1290,
    "created_at": "2026-10-02T08:02:10+00:00"
  }
}

Aliases

Endpoint	Description
GET /api/v1/domains/{name}/aliases	Aliases with their actions.
POST /api/v1/domains/{name}/aliases	Create an alias. Body: {"local_part": "billing"} or {"catch_all": true}.
DELETE /api/v1/domains/{name}/aliases/{id}	Delete an alias. Returns 204.

Emails

Endpoint	Description
GET /api/v1/emails	Received messages, newest first, 25 per page.
GET /api/v1/emails/{id}	One message with headers, text and HTML bodies, spam verdict and signed attachment URLs (valid 60 minutes).
DELETE /api/v1/emails/{id}	Move a message to the trash. Returns 204.

Filters for GET /api/v1/emails, all optional:

Parameter	Example	Effect
domain	acme.com	Only this domain.
q	invoice	Search subject, preview and sender.
from	@stripe.com	Sender contains this text.
status	failed	One of received, delivered, failed, filtered, partial.
spam	0	1 for spam only, 0 to exclude it.
since / until	2026-11-01	Received at or after / before.
per_page	100	1–100.

{
  "data": [
    {
      "id": 48213,
      "domain": "acme.com",
      "from": { "address": "notify@stripe.com", "name": "Stripe" },
      "to": "billing@acme.com",
      "subject": "Invoice paid",
      "status": "delivered",
      "is_spam": false,
      "spam_score": 0.5,
      "attachments_count": 1,
      "received_at": "2026-11-10T09:14:02+00:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 12, "per_page": 25, "total": 290 },
  "links": { "next": "https://www.mxcatch.net/api/v1/emails?page=2", "prev": null }
}

Tips

• Prefer webhooks for reacting to new mail in real time; use the API for backfills, dashboards and cleanup.
• Message IDs are stable, so you can safely store them and fetch the full message later.
• Keep keys server-side. Anyone holding a key can read every message on your domains.