API Reference

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer dm_live_your_api_key_here

Quick start

curl -X GET https://api.mailmark.dev/v1/mailboxes \
  -H "Authorization: Bearer dm_live_your_key"

List Mailboxes

Returns all mailboxes that belong to the domain scoped to your API key. Each mailbox includes its local address, full address, and optional display name.

curl -X GET https://api.mailmark.dev/v1/mailboxes \
  -H "Authorization: Bearer dm_live_..."

Create Mailbox

Creates a new mailbox on the domain associated with your API key. Only the local part of the address is needed (e.g. 'hello'). The domain suffix is appended automatically.

curl -X POST https://api.mailmark.dev/v1/mailboxes \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"address":"hello","displayName":"Hello Team"}'

Delete Mailbox

Permanently deletes a mailbox and all its emails. Also removes it from any sender groups it belongs to. Pass the local part ('hello') or the full address ('hello@domain.com').

curl -X DELETE https://api.mailmark.dev/v1/mailboxes/hello \
  -H "Authorization: Bearer dm_live_..."

List Sender Groups

Returns all sender groups for the API key's domain. A sender group defines which mailboxes act as senders and which recipient emails are targeted.

curl -X GET https://api.mailmark.dev/v1/sender-groups \
  -H "Authorization: Bearer dm_live_..."

Create Sender Group

Creates a sender group. Specify which sender mailboxes to include and an optional list of recipient emails. Pass 'all' for mailboxes to include every mailbox on the domain.

curl -X POST https://api.mailmark.dev/v1/sender-groups \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My Group","mailboxes":"all","emails":[]}'

Update Sender Group

Updates a sender group. All fields are optional. Only the fields you provide will be changed. Use addEmails / removeEmails for incremental recipient list changes, or emails to replace the entire list at once.

curl -X PATCH https://api.mailmark.dev/v1/sender-groups/GROUP_ID \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Delete Sender Group

Permanently deletes a sender group. The mailboxes themselves are not affected.

curl -X DELETE https://api.mailmark.dev/v1/sender-groups/GROUP_ID \
  -H "Authorization: Bearer dm_live_..."

Send Email

Sends an email from a mailbox on the API key's domain. Supports transactional sends (one email to all recipients), campaign sends (individual email per recipient with a shared batchId), and scheduled sends (delivered at a future time).

curl -X POST https://api.mailmark.dev/v1/send \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "hello@yourdomain.com",
  "to": [
    "user@example.com"
  ],
  "subject": "Hello!"
}'

List Sequences

Returns all sequences created by the authenticated user. Each sequence includes its status, step count, and enrollment statistics (total, active, completed, replied, bounced, cancelled).

curl -X GET https://api.mailmark.dev/v1/sequences \
  -H "Authorization: Bearer dm_live_..."

Create Sequence

Creates a new automated email sequence for campaign-style sends (one email per recipient). A sequence is a series of steps: send_email steps deliver an email, delay steps wait a specified duration before proceeding. The first step must be send_email. Supports merge field placeholders like {{firstName}} in subject and html.

curl -X POST https://api.mailmark.dev/v1/sequences \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Welcome Series",
  "from": "hello@yourdomain.com",
  "steps": [
    {
      "type": "send_email",
      "subject": "Welcome {{firstName}}",
      "html": "<p>Hello!</p>"
    },
    {
      "type": "delay",
      "delayMs": 86400000
    },
    {
      "type": "send_email",
      "subject": "Follow up",
      "html": "<p>Checking in</p>"
    }
  ]
}'

Enroll Contacts

Enroll one or more contacts into a sequence. Each contact will start receiving sequence emails from step 1. Contacts already actively enrolled are skipped. Maximum 100 contacts per request.

curl -X POST https://api.mailmark.dev/v1/sequences/:sequenceId/enroll \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "email": "jane@example.com",
      "mergeFields": {
        "firstName": "Jane"
      }
    }
  ]
}'

Pause / Resume Sequence

Pause or resume a sequence. Pausing prevents new step executions (scheduled steps will check sequence status before sending). Resume re-enables processing.

curl -X PATCH https://api.mailmark.dev/v1/sequences/:sequenceId \
  -H "Authorization: Bearer dm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

Cancel Sequence

Cancel a sequence permanently. Sets sequence status to 'completed' and cancels all active enrollments. Scheduled follow-up emails will not be sent.

curl -X DELETE https://api.mailmark.dev/v1/sequences/:sequenceId \
  -H "Authorization: Bearer dm_live_..."

Domain Health

Returns the latest health check for the API key's domain (domain-scoped key) or all domains (org-wide key). Includes SPF, DKIM, DMARC, MX, blacklist status, and an overall score.

curl -X GET https://api.mailmark.dev/v1/domain-health \
  -H "Authorization: Bearer dm_live_..."

Warmup Status

Returns warmup status for all enrolled mailboxes on the API key's domain. Includes health score, inbox rate, daily limits, and activity counts.

curl -X GET https://api.mailmark.dev/v1/warmup \
  -H "Authorization: Bearer dm_live_..."

Bounce Stats

Returns bounce and delivery statistics for the domain over a configurable lookback window. Includes total sent, delivered, bounced, failed, opened, clicked, and replied counts.

curl -X GET https://api.mailmark.dev/v1/bounces \
  -H "Authorization: Bearer dm_live_..."

Suppression List

Returns the suppression (unsubscribe) list for the domain. Supports pagination via the 'after' cursor parameter.

curl -X GET https://api.mailmark.dev/v1/suppressions \
  -H "Authorization: Bearer dm_live_..."

Campaign Stats

Returns aggregate stats for sequences and/or batch sends. Includes open, click, reply, and bounce rates for each campaign.

curl -X GET https://api.mailmark.dev/v1/campaign-stats \
  -H "Authorization: Bearer dm_live_..."