# 이메일 발신 도메인 추가

`POST /v1/email-sender-domains` · 권한 `email-sender-domains:write` · 모든 요금제

환경의 이메일을 발송할 수 있는 도메인을 추가하며, DKIM으로 서명합니다. 도메인은 `pending_dns` 상태로 시작합니다. 반환된 `records`를 DNS에 게시한 후 도메인을 [확인](verify.md)하십시오.

발신 도메인은 `production` 환경에서만 추가할 수 있으며, 환경당 최대 10개까지 추가할 수 있습니다. 이름은 IDNA 2008 A-label로 변환되며, 끝에 있는 점은 제거됩니다.

두 개의 DKIM CNAME(`akp1`, `akp2`)은 플랫폼이 보유한 키를 가리키므로, 키를 교체할 때 고객님 측에서 DNS를 변경할 필요가 없습니다. 반송 경로 CNAME은 반송 메일을 플랫폼으로 되돌려 보냅니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `domain` | string | 예 | 발신에 사용할 도메인 또는 하위 도메인(유니코드 허용), 최대 253자. |
| `Idempotency-Key` | header | 아니요 | 같은 키로 반복된 요청에 대해 동일한 응답을 반환합니다. |

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

## 응답

`201 Created`와 함께 새 발신 도메인을 반환하며, `ETag`에는 해당 버전이 설정됩니다. 각 필드에 대한 설명은 [이메일 발신 도메인 조회](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"
}
```

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 409 | `conflict` | 이 환경에 해당 도메인이 이미 추가되어 있습니다. |
| 409 | `domain_limit_reached` | 환경에 이미 발신 도메인 10개가 있습니다. |
| 422 | `validation_failed` | `/domain required`: 도메인이 없습니다. `/domain invalid`: IP 주소, 단일 레이블, 공용 접미사(예: `co.uk`), 플랫폼 도메인(`keenauth.com`, `keenauth.app` 및 해당 하위 도메인), 또는 DKIM 레코드 이름이 253옥텟을 초과하는 이름입니다. `/domain production_only`: 환경이 `production`이 아닙니다. |
| 422 | `idempotency_key_reuse` | `Idempotency-Key`가 다른 요청에 사용되었습니다. |
| 401 | `unauthenticated` | 자격 증명이 없거나, 잘못되었거나, 취소되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 기간 이후에 다시 시도하십시오. |

## 예시

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