Domains

List domains

GET/api/v1/email/domains

GET /email/domains
curl -X GET 'https://www.unitpost.com/api/v1/email/domains' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "domain",
      "id": "id_123",
      "name": "Example",
      "status": "pending",
      "records": [
        {
          "type": "string",
          "name": "Example",
          "value": "string",
          "priority": 0
        }
      ],
      "dkim_selector": "string",
      "open_tracking": false,
      "click_tracking": false,
      "tls": "opportunistic",
      "tracking_subdomain": "string",
      "tracking_verified_at": "2026-01-01T00:00:00.000Z",
      "capabilities": {
        "sending": "enabled",
        "receiving": "enabled"
      },
      "receiving": {
        "status": "disabled",
        "record": {
          "type": "string",
          "name": "Example",
          "value": "string",
          "priority": 0
        },
        "checks": {
          "mx_found": false,
          "mx_lowest_priority": false,
          "other_mx_found": false
        },
        "checked_at": "2026-01-01T00:00:00.000Z"
      },
      "verified_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your sending domains, cursor-paginated, with each domain's verification status. Add a new one with Add a domain, or fetch a single domain (including its DNS records) with Retrieve a domain. Requires the domains:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Add a domain

POST/api/v1/email/domains

POST /email/domains
curl -X POST 'https://www.unitpost.com/api/v1/email/domains' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "yourdomain.com"
  }'
Response · 201
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add a domain you'll send email from. The response includes the DNS records (SPF, DKIM, and so on) to publish with your DNS provider. Once they're published, trigger a check with Verify a domain — sending from the domain is blocked until it verifies. Requires the domains:write capability.

Request body1 field
FieldTypeDescription
namerequiredstring—
Response · 201 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
201401409422

Retrieve a domain

GET/api/v1/email/domains/{id}

GET /email/domains/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/domains/dom_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single sending domain by id, including its current verification status and the DNS records you need to publish. Re-run the DNS check with Verify a domain, or change its tracking/TLS settings with Update a domain. Requires the domains:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a domain

PATCH/api/v1/email/domains/{id}

PATCH /email/domains/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/domains/dom_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "click_tracking": true,
    "open_tracking": true
  }'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a domain's sending options: open/click tracking defaults, TLS enforcement, and the tracking subdomain. These act as the domain-level defaults that individual emails and campaigns can override (see Update a campaign). A tracking_subdomain can be set at any time, so you can publish its CNAME along with the domain's other records. It is only checked once the domain is verified, and tracked links switch to it once its CNAME is published and it answers over HTTPS; until then they use the default tracking host. After a change, links keep using the previous subdomain until the new one answers over HTTPS (keep the previous CNAME in place). Changing it is limited to a few times an hour per domain, and to a few new subdomains a day per workspace. **Receiving.** capabilities.receiving: "enabled" receives mail sent to any address at the domain: each message is stored and fires the email.received webhook. The domain must be verified (or degraded), else 409 and nothing in the request is applied. Then publish receiving.record (an MX record at the domain's own name) and call Verify a domain: receiving.status turns verified once the record wins and mail is accepted. An MX record takes ALL mail for the name, so if receiving.checks.other_mx_found is true the name already gets mail elsewhere: receive on a subdomain instead (add it as its own domain). "disabled" stops receiving and is always allowed. Turning it on is limited to a few times an hour per domain; sending "enabled" again while it's on doesn't count. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
open_trackingboolean | null—
click_trackingboolean | null—
tlsenumopportunistic | enforced—
tracking_subdomainstring | null—
capabilitiesobjectTurn receiving on or off: `{ "receiving": "enabled" }` or `{ "receiving": "disabled" }`.
Response · 200 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422429

Delete a domain

DELETE/api/v1/email/domains/{id}

DELETE /email/domains/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/email/domains/dom_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove a sending domain from your workspace. Sends that reference an address on this domain will be rejected afterwards, so update your from addresses first. Re-add it any time with Add a domain (you'll need to verify it again). Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404

List sender addresses

GET/api/v1/email/senders

GET /email/senders
curl -X GET 'https://www.unitpost.com/api/v1/email/senders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sender",
      "id": "id_123",
      "domain_id": "domain_123",
      "address": "string",
      "display_name": "string",
      "from": "you@yourdomain.com",
      "source": "manual",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your saved From addresses, as the domain page lists them and the dashboard's From pickers offer them: each a mailbox on one of your domains, with its display name and from, the value to send with. Filter with domain_id. A sender can send once its domain can (see Retrieve a domain). Requires the domains:read capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
domain_idstring · queryOnly the senders on this domain.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
200401403422

Add a sender address

POST/api/v1/email/senders

POST /email/senders
curl -X POST 'https://www.unitpost.com/api/v1/email/senders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "hello@yourdomain.com",
    "display_name": "Acme"
  }'
Response · 201
{
  "object": "sender",
  "id": "id_123",
  "domain_id": "domain_123",
  "address": "string",
  "display_name": "string",
  "from": "you@yourdomain.com",
  "source": "manual",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Save a From address on one of your domains, as the domain page's "Add address" does. The domain may still be verifying. A mailbox already saved on that domain is a 409, so a retry never saves it twice. Requires the domains:write capability.

Request body2 fields
FieldTypeDescription
addressrequiredstringThe mailbox to save, on one of your domains (e.g. `hello@mail.acme.com`). Its domain may still be verifying.
display_namestring | nullShown as the sender's name (`Acme Support <hello@…>`).
Response · 201 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

Retrieve a sender address

GET/api/v1/email/senders/{id}

GET /email/senders/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/senders/sndr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sender",
  "id": "id_123",
  "domain_id": "domain_123",
  "address": "string",
  "display_name": "string",
  "from": "you@yourdomain.com",
  "source": "manual",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

One saved From address. Requires the domains:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Update a sender address

PATCH/api/v1/email/senders/{id}

PATCH /email/senders/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/senders/sndr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "display_name": "Acme Support"
  }'
Response · 200
{
  "object": "sender",
  "id": "id_123",
  "domain_id": "domain_123",
  "address": "string",
  "display_name": "string",
  "from": "you@yourdomain.com",
  "source": "manual",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Change a sender's display name, the only field that changes: a different mailbox is a new sender. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
display_namerequiredstring | nullThe new display name; `null` or `""` clears it.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
200400401403404422

Delete a sender address

DELETE/api/v1/email/senders/{id}

DELETE /email/senders/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/email/senders/sndr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove a saved From address from the pickers. Templates and campaigns that send from it keep their From. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404

Diagnose a domain's DNS

GET/api/v1/email/domains/{id}/diagnose

GET /email/domains/{id}/diagnose
curl -X GET 'https://www.unitpost.com/api/v1/email/domains/dom_123/diagnose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "domain_diagnosis",
  "domain_id": "domain_123",
  "domain": "string",
  "status": "queued",
  "checked_at": "2026-01-01T00:00:00.000Z",
  "last_checked_at": "2026-01-01T00:00:00.000Z",
  "would_verify": false,
  "zone": "string",
  "nameservers": [
    {
      "host": "string",
      "ips": [
        "string"
      ]
    }
  ],
  "provider": {
    "configured": false,
    "identity_exists": false,
    "dkim_status": "string",
    "mail_from_status": "string",
    "error": "string"
  },
  "records": [
    {}
  ],
  "findings": [
    {
      "code": "string",
      "severity": "blocking",
      "title": "string",
      "detail": "string",
      "fix": "string"
    }
  ]
}

Explain why a domain is not verified, or what could break it. Every authoritative nameserver is asked about every expected record, the email provider's view of the identity is read, and findings list what is wrong, most serious first, each with the concrete fix. Read-only: it never changes the domain; Verify a domain does. Shares verify's per-workspace DNS rate limit. Requires the domains:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredenumdomain_diagnosis—
domain_idrequiredstring—
domainrequiredstring—
statusrequiredstringThe domain's stored status, next to the live diagnosis.
checked_atrequiredstring—
last_checked_atstringThe last verify check, which this call does not change.
would_verifyrequiredbooleanWhether a verify run now would mark the domain verified.
zonestringThe zone whose nameservers were asked; null when none was found.
nameserversobject[]—
providerobjectThe email provider's view of the sending identity.
recordsrequiredobject[]Every expected record, with each nameserver's answer and a `verdict` (`ok`, `partial`, `wrong`, `missing`, `unknown`).
findingsrequiredobject[]What is wrong, most serious first, each with the concrete `fix`.
200401403404429502

Verify a domain

POST/api/v1/email/domains/{id}/verify

POST /email/domains/{id}/verify
curl -X POST 'https://www.unitpost.com/api/v1/email/domains/dom_123/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "checks": [
    "string"
  ]
}

Run an on-demand DNS check and advance the domain's verification status. The response includes per-record checks so you can see exactly which DNS records are still missing or wrong. checks.mx and checks.spf are true once the record is correct on your nameservers; checks.dkim also needs the email provider to confirm the key. The domain is verified when all three are true. Get the records to publish from Retrieve a domain. Verification also re-runs periodically in the background. If another workspace also added this domain, yours verifies only once the domain's sending identity is yours: your DKIM record is live and theirs is gone on two checks at least 10 minutes apart, or their domain is deleted. While they have it verified, this returns 409 once all your records are live, and nothing is written. With receiving on (capabilities.receiving), it also checks the receiving MX record and reports it in receiving. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields17 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
checksobject[]—
200401404409502

Search docs and guides

Search the docs and product guides.