이메일 발신 도메인 추가

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

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

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

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

요청

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

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

응답

201 Created와 함께 새 발신 도메인을 반환하며, ETag에는 해당 버전이 설정됩니다. 각 필드에 대한 설명은 이메일 발신 도메인 조회를 참조하십시오.

{
  "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` 기간 이후에 다시 시도하십시오.

예시

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