API reference

Domains

The domain you send from. Adding acme.dev sets up two subdomains: mail.acme.dev for transactional email and updates.acme.dev for marketing, so a marketing problem never hurts your password resets.

Add the returned DNS records at your DNS provider, or use the one-click setup link when the provider supports Domain Connect. Mailpark re-checks DNS on its own; call verify to check now.

The Domain object

type Domain = {
  id: string;                  // the root domain, e.g. "acme.dev"
  domain: string;
  status: "pending" | "partially_verified" | "verified" | "failed";
  subdomains: { transactional: string; marketing: string };
  records: {
    id: string;
    purpose: "DKIM" | "SPF" | "MX" | "DMARC" | "Tracking";
    lane: "transactional" | "marketing" | "both";
    type: "CNAME" | "TXT" | "MX";
    name: string; value: string; priority?: number;
    status: "pending" | "verified" | "failed";
    note: string | null;
  }[];
  click_tracking: { host: string; status: "not_set_up" | "issuing_certificate" | "active" | "standby" | "failed" };
  last_checked_at: string | null; next_check_at: string | null; created_at: string;
};

Add a domain

POST/v1/domains

Sets up mail.<domain> and updates.<domain> and returns the DNS records to add.

scope domains:write

Body

domainstringrequired
The root domain, e.g. acme.dev.

Errors

curl -X POST https://api.mailpark.io/v1/domains \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.dev"
  }'

Response · 200

{
  "id": "acme.dev",
  "domain": "acme.dev",
  "status": "pending",
  "subdomains": {
    "transactional": "mail.acme.dev",
    "marketing": "updates.acme.dev"
  },
  "records": [
    {
      "id": "dkim_1",
      "purpose": "DKIM",
      "lane": "both",
      "type": "CNAME",
      "name": "mp1._domainkey.acme.dev",
      "value": "mp1.dkim.mailpark.io",
      "status": "pending",
      "note": null
    },
    {
      "id": "spf_mail",
      "purpose": "SPF",
      "lane": "transactional",
      "type": "TXT",
      "name": "mail.acme.dev",
      "value": "v=spf1 include:amazonses.com ~all",
      "status": "pending",
      "note": null
    },
    {
      "id": "mx_mail",
      "purpose": "MX",
      "lane": "transactional",
      "type": "MX",
      "name": "mail.acme.dev",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10,
      "status": "pending",
      "note": null
    },
    {
      "id": "dmarc",
      "purpose": "DMARC",
      "lane": "both",
      "type": "TXT",
      "name": "_dmarc.acme.dev",
      "value": "v=DMARC1; p=none;",
      "status": "pending",
      "note": "Skip if you already have a DMARC record."
    }
  ],
  "click_tracking": {
    "host": "links.updates.acme.dev",
    "status": "not_set_up"
  },
  "last_checked_at": null,
  "next_check_at": "2026-10-22T10:07:11Z",
  "created_at": "2026-10-22T10:02:11Z"
}

▶ Try it in the playground

List domains

GET/v1/domains

All domains and their verification status.

curl https://api.mailpark.io/v1/domains \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "acme.dev",
      "domain": "acme.dev",
      "status": "pending",
      "subdomains": {
        "transactional": "mail.acme.dev",
        "marketing": "updates.acme.dev"
      },
      "records": [
        {
          "id": "dkim_1",
          "purpose": "DKIM",
          "lane": "both",
          "type": "CNAME",
          "name": "mp1._domainkey.acme.dev",
          "value": "mp1.dkim.mailpark.io",
          "status": "pending",
          "note": null
        },
        {
          "id": "spf_mail",
          "purpose": "SPF",
          "lane": "transactional",
          "type": "TXT",
          "name": "mail.acme.dev",
          "value": "v=spf1 include:amazonses.com ~all",
          "status": "pending",
          "note": null
        },
        {
          "id": "mx_mail",
          "purpose": "MX",
          "lane": "transactional",
          "type": "MX",
          "name": "mail.acme.dev",
          "value": "feedback-smtp.us-east-1.amazonses.com",
          "priority": 10,
          "status": "pending",
          "note": null
        },
        {
          "id": "dmarc",
          "purpose": "DMARC",
          "lane": "both",
          "type": "TXT",
          "name": "_dmarc.acme.dev",
          "value": "v=DMARC1; p=none;",
          "status": "pending",
          "note": "Skip if you already have a DMARC record."
        }
      ],
      "click_tracking": {
        "host": "links.updates.acme.dev",
        "status": "not_set_up"
      },
      "last_checked_at": null,
      "next_check_at": "2026-10-22T10:07:11Z",
      "created_at": "2026-10-22T10:02:11Z"
    }
  ],
  "next_cursor": null
}

▶ Try it in the playground

Get a domain

GET/v1/domains/{id}

The domain with each DNS record's status and click tracking.

Path parameters

idstringrequired
The root domain, e.g. acme.dev.

curl https://api.mailpark.io/v1/domains/acme.dev \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "id": "acme.dev",
  "domain": "acme.dev",
  "status": "pending",
  "subdomains": {
    "transactional": "mail.acme.dev",
    "marketing": "updates.acme.dev"
  },
  "records": [
    {
      "id": "dkim_1",
      "purpose": "DKIM",
      "lane": "both",
      "type": "CNAME",
      "name": "mp1._domainkey.acme.dev",
      "value": "mp1.dkim.mailpark.io",
      "status": "pending",
      "note": null
    },
    {
      "id": "spf_mail",
      "purpose": "SPF",
      "lane": "transactional",
      "type": "TXT",
      "name": "mail.acme.dev",
      "value": "v=spf1 include:amazonses.com ~all",
      "status": "pending",
      "note": null
    },
    {
      "id": "mx_mail",
      "purpose": "MX",
      "lane": "transactional",
      "type": "MX",
      "name": "mail.acme.dev",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10,
      "status": "pending",
      "note": null
    },
    {
      "id": "dmarc",
      "purpose": "DMARC",
      "lane": "both",
      "type": "TXT",
      "name": "_dmarc.acme.dev",
      "value": "v=DMARC1; p=none;",
      "status": "pending",
      "note": "Skip if you already have a DMARC record."
    }
  ],
  "click_tracking": {
    "host": "links.updates.acme.dev",
    "status": "not_set_up"
  },
  "last_checked_at": null,
  "next_check_at": "2026-10-22T10:07:11Z",
  "created_at": "2026-10-22T10:02:11Z"
}

▶ Try it in the playground

Check DNS now

POST/v1/domains/{id}/verify

Re-checks every record straight away instead of waiting for the next automatic check.

Path parameters

idstringrequired
The root domain.

curl -X POST https://api.mailpark.io/v1/domains/acme.dev/verify \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response · 200

{
  "id": "acme.dev",
  "domain": "acme.dev",
  "status": "partially_verified",
  "subdomains": {
    "transactional": "mail.acme.dev",
    "marketing": "updates.acme.dev"
  },
  "records": [
    {
      "id": "dkim_1",
      "purpose": "DKIM",
      "lane": "both",
      "type": "CNAME",
      "name": "mp1._domainkey.acme.dev",
      "value": "mp1.dkim.mailpark.io",
      "status": "pending",
      "note": null
    },
    {
      "id": "spf_mail",
      "purpose": "SPF",
      "lane": "transactional",
      "type": "TXT",
      "name": "mail.acme.dev",
      "value": "v=spf1 include:amazonses.com ~all",
      "status": "pending",
      "note": null
    },
    {
      "id": "mx_mail",
      "purpose": "MX",
      "lane": "transactional",
      "type": "MX",
      "name": "mail.acme.dev",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10,
      "status": "pending",
      "note": null
    },
    {
      "id": "dmarc",
      "purpose": "DMARC",
      "lane": "both",
      "type": "TXT",
      "name": "_dmarc.acme.dev",
      "value": "v=DMARC1; p=none;",
      "status": "pending",
      "note": "Skip if you already have a DMARC record."
    }
  ],
  "click_tracking": {
    "host": "links.updates.acme.dev",
    "status": "not_set_up"
  },
  "last_checked_at": "2026-10-22T10:02:11Z",
  "next_check_at": "2026-10-22T10:07:11Z",
  "created_at": "2026-10-22T10:02:11Z"
}

▶ Try it in the playground

Get the one-click setup link

GET/v1/domains/{id}/connect

When the domain's DNS provider supports Domain Connect, a link where the founder signs in and approves every record at once. url is null when unsupported.

scope domains:write

Path parameters

idstringrequired
The root domain.

curl https://api.mailpark.io/v1/domains/acme.dev/connect \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "supported": true,
  "provider": "Cloudflare",
  "url": "https://dash.cloudflare.com/domainconnect/v2/domainTemplates/providers/mailpark.io/…",
  "groups": [
    "sending",
    "tracking"
  ],
  "message": "Open the link, sign in to Cloudflare and approve."
}

▶ Try it in the playground

Remove a domain

DELETE/v1/domains/{id}

Stops sending from it. Refused while it's the only verified domain on a live account.

scope domains:write

Path parameters

idstringrequired
The root domain.

Errors

409domain_in_use

curl -X DELETE https://api.mailpark.io/v1/domains/acme.dev \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "deleted": true,
  "id": "acme.dev",
  "next_steps": []
}

▶ Try it in the playground