API Reference

Send emails, validate addresses, manage lists, and more via our REST API.

Authentication Send Email Batch Send Scheduled Send Idempotency Validate Email Domains Credentials Contact Lists Campaigns Templates Tags & Segments Suppressions Logs & Reports Tracking Webhooks Error Codes

Authentication

Include your API key in the Authorization header:

Authorization: Bearer mm_your_api_key_here

Alternative: use the X-API-Key header:

X-API-Key: mm_your_api_key_here

All API keys start with mm_. Find yours in Credentials.

Send Email

Send a single transactional email. Returns 202 on success.

curl -X POST https://app.mailmatic.cc/api/send \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from Mailmatic",
    "html": "<h1>Welcome!</h1><p>This is a test email.</p>"
  }'

Parameters

Field	Required	Description
from	Yes	Sender email address
to	Yes	Recipient (string or string array)
subject	Yes	Email subject line
html	Yes*	HTML body (*or text)
text	Yes*	Plain text body (*or html)
from_name	No	Display name for sender
cc	No	CC recipients (string or string array)
bcc	No	BCC recipients (string or string array)
reply_to	No	Reply-To address
headers	No	Custom email headers (object)
send_at	No	ISO 8601 datetime for scheduled send

Response

{
  "id": "c9de3859-ac2e-4379-a2e5-ff5dae2e07d0",
  "message_id": "<[email protected]>",
  "status": "sent",
  "message": "Email queued for delivery"
}

Batch Send

Send up to 100 emails in a single API call. Each email is processed independently.

curl -X POST https://app.mailmatic.cc/api/send/batch \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "to": "[email protected]",
        "subject": "Welcome",
        "html": "<p>Hi User 1</p>"
      },
      {
        "to": "[email protected]",
        "subject": "Welcome",
        "html": "<p>Hi User 2</p>"
      }
    ]
  }'

Response

{
  "results": [
    { "id": "uuid-1", "message_id": "<...@domain>", "status": "sent" },
    { "id": "uuid-2", "message_id": "<...@domain>", "status": "sent" }
  ]
}

Each email in the batch supports the same fields as the single send endpoint. The from field defaults to the credential's email if omitted.

Scheduled Sending

Schedule emails for future delivery by adding a send_at parameter to the send endpoint.

curl -X POST https://app.mailmatic.cc/api/send \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Scheduled message",
    "html": "<p>This was scheduled!</p>",
    "send_at": "2026-06-01T09:00:00Z"
  }'

Response

{
  "id": "uuid",
  "message_id": "<uuid@domain>",
  "status": "scheduled",
  "send_at": "2026-06-01T09:00:00Z"
}

Scheduled emails are stored in Redis and processed by the cron job at /api/cron/process-scheduled. Must be a future ISO 8601 datetime.

Idempotency Keys

Prevent duplicate sends by including an idempotency key. Cached for 24 hours.

curl -X POST https://app.mailmatic.cc/api/send \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Important notification",
    "html": "<p>Only sent once!</p>"
  }'

If the same Idempotency-Key is sent again within 24 hours, the original response is returned without re-sending. Also accepts X-Idempotency-Key header.

Validate Email

Check if an email address is valid (syntax + MX lookup).

curl -X POST https://app.mailmatic.cc/api/validate \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Domain Management

Add a domain

curl -X POST https://app.mailmatic.cc/api/domains \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Verify DNS records

curl -X POST https://app.mailmatic.cc/api/domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer mm_your_api_key_here"

Get DNS score

curl https://app.mailmatic.cc/api/domains/DOMAIN_ID/score \
  -H "Authorization: Bearer mm_your_api_key_here"

DNS checks cover SPF, DKIM, DMARC, and MX records. Score is 0–100.

SMTP Credentials

Create credentials

curl -X POST https://app.mailmatic.cc/api/credentials \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain_id": "UUID", "username": "noreply", "display_name": "My App"}'

Each credential generates a unique mm_ API key for sending. Credentials also include SMTP username/password for direct SMTP relay on port 587.

Contact Lists

Create a list

curl -X POST https://app.mailmatic.cc/api/lists \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Subscribers", "description": "Weekly newsletter list"}'

Add a contact

curl -X POST https://app.mailmatic.cc/api/lists/LIST_ID/contacts \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "first_name": "John", "last_name": "Doe"}'

Import from CSV

curl -X POST https://app.mailmatic.cc/api/lists/LIST_ID/import \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -F "[email protected]"

CSV must have header row: email, first_name, last_name

Campaigns

Create campaign

curl -X POST https://app.mailmatic.cc/api/campaigns \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Series",
    "subject": "Welcome to our platform",
    "from_email": "[email protected]",
    "from_name": "Your Brand",
    "list_id": "LIST_ID",
    "content_html": "<h1>Welcome {{first_name}}!</h1>",
    "content_text": "Welcome {{first_name}}!"
  }'

Send campaign

curl -X POST https://app.mailmatic.cc/api/campaigns/CAMPAIGN_ID/send \
  -H "Authorization: Bearer mm_your_api_key_here"

Clone campaign

curl -X POST https://app.mailmatic.cc/api/campaigns/CAMPAIGN_ID/clone \
  -H "Authorization: Bearer mm_your_api_key_here"

Live tracking (SSE)

curl -N https://app.mailmatic.cc/api/campaigns/CAMPAIGN_ID/stream \
  -H "Authorization: Bearer mm_your_api_key_here"

Template Variables

Use these variables in campaign HTML, subjects, and templates:

Variable	Description
{{first_name}}	Contact first name
{{last_name}}	Contact last name
{{email}}	Contact email address
{{full_name}}	Full name (first + last)
{{metadata.key}}	Custom metadata field
{{unsubscribe_url}}	Auto-generated unsubscribe link

Tags & Segments

Create tag

curl -X POST https://app.mailmatic.cc/api/tags \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP", "color": "#3B82F6"}'

Create segment

curl -X POST https://app.mailmatic.cc/api/segments \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Active Users", "rules": {"field": "email", "operator": "contains", "value": "@"}}'

Suppressions

List suppressed emails

curl https://app.mailmatic.cc/api/suppressions \
  -H "Authorization: Bearer mm_your_api_key_here"

Remove from suppression list

curl -X DELETE https://app.mailmatic.cc/api/suppressions/[email protected] \
  -H "Authorization: Bearer mm_your_api_key_here"

Logs & Reports

List email logs

curl "https://app.mailmatic.cc/api/logs?page=1&limit=50&search=example.com&status=sent" \
  -H "Authorization: Bearer mm_your_api_key_here"

Dashboard stats

curl https://app.mailmatic.cc/api/stats \
  -H "Authorization: Bearer mm_your_api_key_here"

Export as CSV

curl "https://app.mailmatic.cc/api/reports?export=csv" \
  -H "Authorization: Bearer mm_your_api_key_here" \
  -o report.csv

Tracking

Open and click tracking is automatic. These endpoints are called by the email client, not by you:

Endpoint	Purpose
/api/t/o/:token	Open tracking pixel (1x1 GIF)
/api/t/c/:token	Click tracking redirect
/api/unsub/:token	One-click unsubscribe

Webhooks

Mailmatic receives delivery and bounce events from Postfix:

POST https://app.mailmatic.cc/api/webhooks/postfix
X-Webhook-Secret: your_webhook_secret
Content-Type: application/json

{
  "event": "bounce",
  "recipient": "[email protected]",
  "message_id": "<uuid@domain>",
  "reason": "550 User not found"
}

Webhook authentication is via X-Webhook-Secret or Authorization: Bearer header. Razorpay payment webhooks use signature verification.

Error Codes

Code	Meaning
401	Invalid or missing API key / session
403	Forbidden — wrong domain or inactive credential
422	Validation error (syntax/MX/suppressed)
429	Rate limit exceeded (per-IP or per-credential)
500	Internal server error
502	SMTP relay error