Add an email sender domain

POST /v1/email-sender-domains · permission email-sender-domains:write · all plans

Adds a domain your environment's email can be sent from, signed with DKIM. The domain starts as pending_dns; publish the returned records in your DNS and verify the domain.

Sender domains can be added only in production environments, at most 10 per environment. The name is converted to an IDNA 2008 A-label and a trailing dot is removed.

The two DKIM CNAMEs (akp1, akp2) point to keys the platform holds, so key rotation never needs a DNS change on your side. The return-path CNAME carries bounces back to the platform.

Request

Field	Type	Required	Description
`domain`	string	yes	Domain or subdomain to send from (Unicode allowed), at most 253 characters.
`Idempotency-Key`	header	no	Replays the same response for a repeated request with the same key.

{
  "domain": "mail.example.com"
}

Response

201 Created with the new sender domain and ETag set to its version. The fields are described in Get an email sender domain.

{
  "id": "sdom_01k7r9m3q5t8v2w4x6y8z0a2b4",
  "domain": "mail.example.com",
  "status": "pending_dns",
  "active_selector": "akp1",
  "dkim_status": null,
  "return_path_status": null,
  "dmarc_alignment": null,
  "last_checked_at": null,
  "failing_since": null,
  "degraded_since": null,
  "records": [
    {
      "type": "CNAME",
      "name": "akp1._domainkey.mail.example.com",
      "value": "akp1.sdom_01k7r9m3q5t8v2w4x6y8z0a2b4.dkim.eu.keenauth.app",
      "required": true
    },
    {
      "type": "CNAME",
      "name": "akp2._domainkey.mail.example.com",
      "value": "akp2.sdom_01k7r9m3q5t8v2w4x6y8z0a2b4.dkim.eu.keenauth.app",
      "required": true
    },
    {
      "type": "CNAME",
      "name": "rp.mail.example.com",
      "value": "rp.eu.mail.keenauth.app",
      "required": true
    }
  ],
  "version": 1,
  "created_at": "2026-10-19T09:00:00Z",
  "updated_at": "2026-10-19T09:00:00Z"
}

Errors

HTTP	code	When
409	`conflict`	The domain is already added to this environment.
409	`domain_limit_reached`	The environment already has 10 sender domains.
422	`validation_failed`	`/domain required`: no domain. `/domain invalid`: an IP address, a single label, a public suffix (for example `co.uk`), a platform domain (`keenauth.com`, `keenauth.app` and their subdomains) or a name so long that its DKIM record name exceeds 253 octets. `/domain production_only`: the environment is not `production`.
422	`idempotency_key_reuse`	The `Idempotency-Key` was used with a different request.
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks the required permission.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.
503	`service_unavailable`	A dependency is temporarily unavailable; retry after the `Retry-After` period.

Example

curl -X POST https://api.eu.keenauth.com/v1/email-sender-domains \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2e8a-7d3b-4c9e-a1f0-2b6d8e4c7a90" \
  -d '{"domain":"mail.example.com"}'

CLI: keenauth email-sender-domains create --domain mail.example.com