Email Domains

Add and verify sending domains, check their DNS status, and set your default — all via API. Useful for provisioning pipelines that need to configure domains automatically.

Scopes required:

Operation	Scope
List or get domains	domains:read
Add, verify, update, or delete domains	domains:manage (implies domains:read)

---

Add a domain

Adds a new sending domain and returns the DNS records you need to configure at your registrar.

Auth: domains:manage scope, or a JWT admin user.

Request body

Field		Type	Description
domain	required	string	The domain or subdomain to add (e.g. mail.example.com)
isDefault	optional	boolean	Set as the default sending domain. Defaults to false.

Example

{
  "domain": "mail.example.com",
  "isDefault": false
}

Response

201 — domain object. The dnsRecords field contains the DNS entries to add at your registrar. Each record has a type, name, and value.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "domain": "mail.example.com",
  "status": "pending",
  "isDefault": false,
  "isActive": true,
  "dnsRecords": {
    "spf": {
      "type": "TXT",
      "name": "mail.example.com",
      "value": "v=spf1 include:spf.brixus365.com ~all",
      "ttl": 3600
    },
    "dkim": {
      "type": "CNAME",
      "name": "bx1._domainkey.mail.example.com",
      "value": "bx1.dkim.brixus365.com",
      "ttl": 3600
    }
  },
  "verificationAttempts": 0,
  "lastVerifiedAt": null,
  "lastVerificationError": null,
  "createdAt": "2026-05-06T10:00:00Z",
  "updatedAt": "2026-05-06T10:00:00Z"
}

Add all DNS records returned in dnsRecords, then call Verify a domain to confirm them. DNS changes can take minutes to hours to propagate.

---

List domains

Returns all domains configured for the tenant.

Auth: domains:read scope, or any JWT user.

Response

200

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "domain": "mail.example.com",
      "status": "verified",
      "isDefault": true,
      "isActive": true,
      ...
    }
  ],
  "total": 1
}

---

Get a domain

Returns details for a single domain, including its current verification status and DNS records.

Auth: domains:read scope, or any JWT user.

Response

200 — domain object (same shape as Add a domain).

---

Verify a domain

Triggers an immediate DNS check. Call this after adding the required records at your registrar, or to re-check a domain that previously failed verification.

Auth: domains:manage scope, or a JWT admin user.

No request body required.

Response

200

{
  "success": true,
  "message": "Domain verified successfully.",
  "verifiedRecords": ["SPF", "DKIM"],
  "failedRecords": [],
  "warnings": [],
  "status": "verified"
}

Field	Description
success	Whether all required records passed
verifiedRecords	Record types that were found and valid
failedRecords	Record types missing or incorrect — fix these and retry
warnings	Optional records not found — sends still work but deliverability may be lower
status	”verified” or “failed”

If failedRecords is non-empty, check your DNS configuration and retry. DNS propagation can take up to 48 hours depending on your registrar and TTL settings.

---

Update a domain

Updates domain settings. All fields are optional — only fields included in the request body are changed.

Auth: domains:manage scope, or a JWT admin user.

Request body

Field	Type	Description
isDefault	boolean	Make this the default domain for transactional sends
isActive	boolean	Enable or disable the domain

Response

200 — updated domain object.

---

Delete a domain

Removes the domain from the tenant. DNS records at your registrar can be cleaned up afterward.

Auth: domains:manage scope, or a JWT admin user.

Response

204 No Content

---

Status values

Status	Meaning
pending	Domain added — DNS records not yet verified
verified	All required DNS records confirmed — domain can send
failed	Last verification attempt failed — check lastVerificationError and retry after fixing the records

---

What’s next

You want to…	Go to
Verify a domain through the dashboard instead	Verify your sending domain
Send your first email	Sending emails
Manage API keys via the API	API Keys