Domains

Add and manage custom domains with separate sending and receiving readiness. Verify sender identity records and check MX routing independently.

Overview

By default, inboxes send from @agentsend.io. Adding your own domain lets you send from addresses like agent@yourdomain.com, improving deliverability and brand trust.

After adding a domain, AgentSend returns separate DNS records for sending and receiving. Once published, call the verify endpoint to refresh both statuses: sending checks SES sender verification and DKIM, while receiving checks whether the domain's MX points to AgentSend.

ℹ

All requests require an x-api-key header. Get your key from the dashboard.

The Domain Object

All domain endpoints return a Domain object (or an array of them).

Domain object

{
  "id":                 "dom_01hxyz...",          // UUID
  "domain":             "mail.yourdomain.com",
  "sendingStatus":      "pending",              // pending | pending_dkim | verified | failed
  "receivingStatus":    "pending",              // pending | verified | failed
  "verificationStatus": "pending",              // backward-compatible alias of sendingStatus
  "sendingDnsRecords": [
    {
      "type":  "TXT",
      "name":  "_amazonses.mail.yourdomain.com",
      "value": "verification-token"
    },
    {
      "type":  "CNAME",
      "name":  "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1.dkim.amazonses.com"
    }
  ],
  "receivingDnsRecords": [
    {
      "type":  "MX",
      "name":  "mail.yourdomain.com",
      "value": "mx.agentsend.io",
      "priority": 10
    }
  ],
  "dnsRecords": [
    {
      "type":  "TXT",
      "name":  "_amazonses.mail.yourdomain.com",
      "value": "verification-token"
    }
  ],
  "sendingVerifiedAt": null,
  "receivingVerifiedAt": null,
  "createdAt": "2024-11-01T09:00:00Z"
}

Field	Type	Description
`id`	string	Unique domain identifier (UUID).
`domain`	string	The domain or subdomain you added.
`sendingStatus`	string	Sender verification status. `pending`, `pending_dkim`, `verified`, or `failed`.
`receivingStatus`	string	Inbound routing status based on MX. `pending`, `verified`, or `failed`.
`verificationStatus`	string	Backward-compatible alias of `sendingStatus`.
`sendingDnsRecords`	array	DNS records required for sending verification and DKIM signing.
`receivingDnsRecords`	array	DNS records required if you want AgentSend to receive inbound mail for the domain.
`dnsRecords`	array	Combined list of sending and receiving records for convenience.
`sendingVerifiedAt`	string \| null	When sending verification last reached `verified`.
`receivingVerifiedAt`	string \| null	When MX verification last reached `verified`.
`createdAt`	string (ISO 8601)	Timestamp when the domain was added.

POST /domains

Add a custom domain. Returns the new Domain object including the DNS records you must publish before verifying.

Request body

Parameter	Type	Description
`domain` obrigatório	string	The domain or subdomain to add, e.g. `mail.yourdomain.com`.

curl

curl -X POST https://api.agentsend.io/domains \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.yourdomain.com"}'

Response `201 Created`

json

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "pending",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

💡

Publish all returned dnsRecords at your DNS registrar, then call POST /domains/{id}/verify to activate the domain.

GET /domains

List all domains on your account, including their current verification status.

Parameters

No query parameters.

curl

curl https://api.agentsend.io/domains \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `200 OK`

json

{
  "data": [
    {
      "id": "dom_01hxyz4k9s2n3p7q",
      "domain": "mail.yourdomain.com",
      "verificationStatus": "verified",
      "dnsRecords": [ /* ... */ ],
      "createdAt": "2024-11-01T09:00:00Z"
    },
    {
      "id": "dom_01hzab8m3t4r2w9c",
      "domain": "outbound.acme.io",
      "verificationStatus": "pending",
      "dnsRecords": [ /* ... */ ],
      "createdAt": "2024-11-15T14:23:00Z"
    }
  ]
}

GET /domains/{id}

Retrieve a single domain by ID, including its full DNS records and current verification status.

Path parameters

Parameter	Type	Description
`id` obrigatório	string (uuid)	The ID of the domain to retrieve.

curl

curl https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `200 OK`

json

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "verified",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

DELETE /domains/{id}

Permanently delete a domain from your account. Inboxes using this domain will fall back to @agentsend.io addresses. This action is irreversible.

Path parameters

Parameter	Type	Description
`id` obrigatório	string (uuid)	The ID of the domain to delete.

curl

curl -X DELETE https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `204 No Content`

Returns an empty body on success.

⚠

Deleting a domain does not remove the DNS records from your registrar. You should clean those up manually after deletion.

POST /domains/{id}/verify

Trigger a fresh domain readiness check. AgentSend updates sender verification from SES and DKIM, then separately checks whether the domain's MX points to AgentSend for inbound mail.

Path parameters

Parameter	Type	Description
`id` obrigatório	string (uuid)	The ID of the domain to verify.

curl

curl -X POST https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q/verify \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response `200 OK`

Returns the updated Domain object. Check sendingStatus and receivingStatus to see the latest result.

json — verified

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "verified",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

json — pending_dkim (ownership ok, DKIM not yet propagated)

{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "pending_dkim",
  "dnsRecords": [ /* ... */ ],
  "createdAt": "2024-11-01T09:00:00Z"
}

ℹ

DNS changes can take up to 48 hours to propagate worldwide. If verification returns pending_dkim or failed, wait a few minutes and call verify again.

← Anterior API: Webhooks Próximo → API: Account

Domains

Overview

The Domain Object

POST /domains

Request body

Response 201 Created

GET /domains

Parameters

Response 200 OK

GET /domains/{id}

Path parameters

Response 200 OK

DELETE /domains/{id}

Path parameters

Response 204 No Content

POST /domains/{id}/verify

Path parameters

Response 200 OK

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `204 No Content`

Response `200 OK`