# 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](verify.md) 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. |

```json
{
  "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](get.md).

```json
{
  "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

```bash
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`