Domains

Add, list, verify and remove sending domains, and read the DNS records each one needs before it can send.

Add a domain

POST /v1/domains

Returns the DNS records to publish.

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

{
  "id": "d0e78a7b-5a7a-45ed-8b25-cb4d541bda29",
  "name": "mail.yourdomain.com",
  "status": "pending",
  "records": [
    { "type": "TXT", "name": "sp.yourdomain.com", "value": "v=spf1 include:spf.sendpository.com -all", "purpose": "spf", "required": true, "verified": false },
    { "type": "TXT", "name": "sxyzabcd._domainkey.yourdomain.com", "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkq...", "purpose": "dkim", "required": true, "verified": false },
    { "type": "MX", "name": "sp.yourdomain.com", "value": "mail.sendpository.com", "priority": 10, "purpose": "return_path", "required": true, "verified": false },
    { "type": "TXT", "name": "_dmarc.yourdomain.com", "value": "v=DMARC1; p=none; rua=mailto:dmarc@sendpository.com", "purpose": "dmarc", "required": false, "verified": false }
  ],
  "created_at": "2026-08-30T09:00:00.000Z"
}

Publish all four, then call verify. See Domains for what each record does.

required tells you which ones gate verification: SPF, DKIM and the Return-Path MX. DMARC is recommended and does not block sending.

The name is the full record name. Most DNS panels append your domain to whatever you type, so enter the label alone - sp, _dmarc, sxyzabcd._domainkey - and let the panel add the rest.

Domains added before September 2026

Older domains were issued a different layout: an SPF record on the apex and a CNAME return-path on bounces., with neither the MX nor DMARC required. Those records still verify and nothing needs to change. The response tells you which layout a domain is on - read type and required rather than assuming.

List domains

GET /v1/domains

{
  "data": [
    {
      "id": "d0e78a7b-...",
      "name": "mail.yourdomain.com",
      "status": "verified",
      "records": [ /* ... */ ],
      "created_at": "2026-08-30T09:00:00.000Z"
    }
  ]
}

Retrieve a domain

GET /v1/domains/{id}

Includes per-record verification state.

{
  "id": "d0e78a7b-...",
  "name": "mail.yourdomain.com",
  "status": "verified",
  "records": [ /* each with its own "verified": true|false */ ],
  "verified_at": "2026-08-30T09:06:12.400Z",
  "last_checked_at": "2026-08-30T09:06:12.400Z",
  "created_at": "2026-08-30T09:00:00.000Z"
}

Verify a domain

POST /v1/domains/{id}/verify

Runs a live DNS lookup now.

curl -X POST https://api.sendpository.com/v1/domains/{id}/verify \
  -H "Authorization: Bearer $SENDPOSITORY_API_KEY"

{
  "id": "d0e78a7b-...",
  "name": "mail.yourdomain.com",
  "status": "pending",
  "records": [ /* "verified" per record */ ]
}

status is verified only when SPF and DKIM both resolve. Return-Path and DMARC affect bounce handling and reporting, not authentication.

Safe to poll

Nothing is cached - each call is a fresh lookup. Poll every 30 seconds or so while you wait for DNS to propagate.

Delete a domain

DELETE /v1/domains/{id}

Requires a full_access key.

{ "id": "d0e78a7b-...", "deleted": true }

Sending from that domain stops immediately. Messages already sent stay in your history.