Home /Docs /Domain API

Domain API

Programmatically provision a sender domain. One call creates the domain, registers a sender email, and returns the SPF, DKIM and DMARC records your customer needs to publish at their DNS provider.

Overview

Create a new sender domain and receive the DNS records (SPF, DKIM, DMARC) that your customer must publish at their registrar. Optionally enables inbound mail when the domain's MX records already point at our relay.

The endpoint is part of the public Email API surface — it uses the same organization-scoped tokens as POST /api/v1/emails. Pair it with the in-app Domain Setup guide when you need to walk customers through publishing the records.

Authentication

Both headers are required. These are the same API tokens used for the transactional email endpoint (POST /api/v1/emails).

Header	Required	Description
X-Api-Access-Token	yes	Organization's API access token.
X-Api-Secret-Token	yes	Organization's API secret token.
Content-Type	yes	application/json

Generate / View API Tokens

Opens your workspace's Settings → Security.

POST /api/v1/emails/domains/generate

Creates the domain (if new), registers the sender email against your organization, and returns the DNS records to publish.

POST https://api-marketing.cllavio.com/api/v1/emails/domains/generate

Content-Type: application/json

Request body

{
  "email": "noreply@example.com",
  "replyTo": "support@example.com",
  "inbound": false
}

Field	Type	Required	Description
email	string	yes	Sender email address. The domain is extracted from the part after @.
replyTo	string	no	Optional reply-to address. Must be a valid email if provided.
inbound	boolean	no	When true, also enable inbound mail receiving. Requires MX records to already point at inbound.sendtrim.com or smtp.sendtrim.com — validated live before enabling. Defaults to false.

Response

201 Created — returns a map of DNS record name → TXT value that the customer must publish at their DNS provider.

{
  "SPF": "v=spf1 ip4:51.79.43.241 -all",
  "abc123._domainkey.example.com": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhki...",
  "_dmarc": "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
}

Publishing the records

Each key in the response maps to a single TXT record at your customer's DNS provider:

Response key	Type	Host	Value
SPF	TXT	The apex (e.g. example.com)	v=spf1 ip4:... -all
<selector>._domainkey.<domain>	TXT	The DKIM key name returned (e.g. abc123._domainkey.example.com)	v=DKIM1; k=rsa; p=...
_dmarc	TXT	_dmarc at the apex, or _dmarc.<subdomain> when using a subdomain	v=DMARC1; p=none; ...

Info: To check whether the customer has published the records, call the JWT-authenticated GET /api/v1/domains/validate?domain=<domain> endpoint. That endpoint is separate from this public API.

Domain reuse

If the calling organization has already authenticated this domain, the same DNS records are returned and the new sender email is registered against the existing record — no new DKIM keys are generated. The response still uses 201 Created.

{
  "SPF": "v=spf1 ip4:51.79.43.241 -all",
  "abc123._domainkey.example.com": "v=DKIM1; k=rsa; p=...",
  "_dmarc": "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
}

Enabling inbound

Pass "inbound": true to enable inbound mail receiving for the domain at creation time. We resolve the domain's MX records live before enabling — the flag is only honoured if MX points to one of:

inbound.sendtrim.com
smtp.sendtrim.com

If MX is missing or pointing elsewhere, the record is created with inbound disabled — the call still succeeds with 201 and the DNS records are returned. Fix the MX and toggle inbound on later from the dashboard, or call again once MX is in place.

Full webhook integration details live in the Inbound Email Webhooks guide.

Errors

Status	Body	When
400 Bad Request	"Invalid sender address: <email>"	email is missing or fails the email regex.
400 Bad Request	"Invalid reply-to address: <email>"	replyTo is provided but invalid.
401 Unauthorized	"Missing API credentials"	One or both token headers are missing or blank.
401 Unauthorized	"Invalid API credentials"	Tokens do not match any organization.
409 Conflict	"Domain is already taken"	The domain is registered to a different organization.
409 Conflict	"Email is already taken"	A sender with the same email already exists.
500 Internal Server Error	{ "error": "Failed to generate DNS records." }	Unexpected server error.

Example — cURL

curl -X POST "https://api-marketing.cllavio.com/api/v1/emails/domains/generate" \
  -H "X-Api-Access-Token: $ACCESS_TOKEN" \
  -H "X-Api-Secret-Token: $SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "noreply@example.com",
    "replyTo": "support@example.com",
    "inbound": false
  }'

Notes

The sender email created by this call is automatically activated for the organization — any previously active sender is deactivated.
DKIM private keys are stored server-side; only the public key is returned in the DKIM TXT record.
To verify the published DNS records, call GET /api/v1/domains/validate?domain=<domain> — a separate, JWT-authenticated endpoint that is not part of the public API.
Setting "inbound": true only succeeds when MX records for the domain already point to inbound.sendtrim.com or smtp.sendtrim.com. Otherwise the record is created with inbound disabled (no error).