Documentation / API Reference

Domains API

3 min read

The Domains API lets you add, verify, and manage your sending domains.

Add domain

Register a new sending domain.

POST /v1/domains

Request body

Field Type Required Description
name string Yes Domain name (e.g., mail.yourdomain.com)

Example request

curl -X POST https://api.mailingapi.com/v1/domains \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "notifications.yourdomain.com"}'

Response

{
  "id": "dom_abc123",
  "domain": "notifications.yourdomain.com",
  "status": "pending",
  "created_at": "2024-01-15T10:00:00Z",
  "dns_records": [
    {
      "type": "TXT",
      "host": "notifications.yourdomain.com",
      "value": "v=spf1 include:spf.mailingapi.com ~all",
      "purpose": "spf",
      "status": "pending"
    },
    {
      "type": "CNAME",
      "host": "mlapi._domainkey.notifications.yourdomain.com",
      "value": "mlapi._domainkey.mailingapi.com",
      "purpose": "dkim",
      "status": "pending"
    },
    {
      "type": "TXT",
      "host": "_dmarc.notifications.yourdomain.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com",
      "purpose": "dmarc",
      "status": "pending"
    },
    {
      "type": "TXT",
      "host": "_mailingapi.notifications.yourdomain.com",
      "value": "mailingapi-verify=abc123xyz",
      "purpose": "ownership",
      "status": "pending"
    }
  ]
}

List domains

Retrieve all domains for your account.

GET /v1/domains

Example request

curl https://api.mailingapi.com/v1/domains \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "notifications.yourdomain.com",
      "status": "verified",
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "dom_def456",
      "domain": "alerts.yourdomain.com",
      "status": "pending",
      "created_at": "2024-01-16T10:00:00Z"
    }
  ]
}

Get domain

Retrieve details of a specific domain.

GET /v1/domains/{domain_id}

Example request

curl https://api.mailingapi.com/v1/domains/dom_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "id": "dom_abc123",
  "domain": "notifications.yourdomain.com",
  "status": "verified",
  "created_at": "2024-01-15T10:00:00Z",
  "verified_at": "2024-01-15T10:30:00Z",
  "authentication": {
    "spf": {"status": "valid"},
    "dkim": {"status": "valid"},
    "dmarc": {"status": "valid"},
    "ownership": {"status": "valid"}
  }
}

Domain statuses

Status Description
pending DNS records not yet verified
verifying Verification in progress
verified All records valid, ready to send
failed One or more records invalid

Get DNS records

Retrieve DNS records required for domain verification.

GET /v1/domains/{domain_id}/dns-records

Example request

curl https://api.mailingapi.com/v1/domains/dom_abc123/dns-records \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "records": [
    {
      "type": "TXT",
      "host": "notifications.yourdomain.com",
      "value": "v=spf1 include:spf.mailingapi.com ~all",
      "purpose": "spf",
      "status": "valid"
    },
    {
      "type": "CNAME",
      "host": "mlapi._domainkey.notifications.yourdomain.com",
      "value": "mlapi._domainkey.mailingapi.com",
      "purpose": "dkim",
      "status": "valid"
    },
    {
      "type": "TXT",
      "host": "_dmarc.notifications.yourdomain.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com",
      "purpose": "dmarc",
      "status": "valid"
    },
    {
      "type": "TXT",
      "host": "_mailingapi.notifications.yourdomain.com",
      "value": "mailingapi-verify=abc123xyz",
      "purpose": "ownership",
      "status": "valid"
    }
  ]
}

Verify domain

Trigger verification of DNS records.

POST /v1/domains/{domain_id}/verify

Example request

curl -X POST https://api.mailingapi.com/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer $API_KEY"

Response (success)

{
  "id": "dom_abc123",
  "domain": "notifications.yourdomain.com",
  "status": "verified",
  "spf": {"status": "valid"},
  "dkim": {"status": "valid"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Response (partial failure)

{
  "id": "dom_abc123",
  "domain": "notifications.yourdomain.com",
  "status": "failed",
  "spf": {"status": "valid"},
  "dkim": {"status": "missing", "error": "CNAME record not found"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Update tracking settings

Set the domain-wide tracking defaults. These act as a master switch: with tracking_enabled: false, no message from this domain gets an open pixel or rewritten links, regardless of the per-message tracking field.

PATCH /v1/domains/{domain_id}

Request body

Field Type Description
tracking_enabled boolean Master tracking switch for the domain
click_tracking boolean Default click tracking (link rewriting)
open_tracking boolean Default open tracking (pixel)

The update is partial — omitted fields keep their current value. Only these three fields are updatable; anything else in the body (name, status, ownership_verified, …) is ignored. A non-boolean value returns 400.

Example request

curl -X PATCH https://api.mailingapi.com/v1/domains/dom_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tracking_enabled": false }'

Response

{
  "data": {
    "id": "dom_abc123",
    "name": "mail.yourdomain.com",
    "tracking": {
      "enabled": false,
      "click_tracking": true,
      "open_tracking": true
    }
  }
}

When to use this instead of per-message tracking: if your product sends only transactional mail — invitations, password resets, system notices — turn tracking off once here rather than remembering the field on every send. An omitted per-message field means “use the domain default”, so a forgotten flag then fails safe instead of silently shipping a pixel. See Messages → Tracking options.

Delete domain

Remove a domain from your account.

DELETE /v1/domains/{domain_id}

Example request

curl -X DELETE https://api.mailingapi.com/v1/domains/dom_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content

Warning: Deleting a domain will:

  • Revoke all associated API keys
  • Prevent sending from this domain
  • Delete historical statistics

Error codes

Code Description
domain_already_exists Domain already registered
invalid_domain Invalid domain format
domain_not_found Domain ID not found
verification_failed DNS verification failed
domain_in_use Cannot delete domain with active API keys