Documentation / API Reference

Domains API

2 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
domain 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 '{"domain": "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"}
}

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

Domain statistics

Get sending statistics for a domain.

GET /v1/domains/{domain_id}/stats

Query parameters

Parameter Type Description
from string Start date (ISO 8601)
to string End date (ISO 8601)
group_by string hour, day, week, month

Example request

curl "https://api.mailingapi.com/v1/domains/dom_abc123/stats?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "domain": "notifications.yourdomain.com",
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "totals": {
    "sent": 15000,
    "delivered": 14850,
    "bounced": 100,
    "complained": 5,
    "opened": 3500,
    "clicked": 875
  },
  "rates": {
    "delivery": 99.0,
    "bounce": 0.67,
    "complaint": 0.03,
    "open": 23.6,
    "click": 5.9
  }
}

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