이메일 발신 도메인 등록
발신에 사용할 도메인을 등록하고, 소유 증명에 필요한 DNS 레코드(CNAME 3건)를 받습니다.
등록만으로는 발신할 수 없습니다. 응답의 dnsRecords 3건을 도메인 DNS 에 심은 뒤
검증 API 를 호출해야 verified 가 됩니다. DNS 전파에는 보통 수 분~수 시간이 걸립니다.
멱등입니다. 같은 계정이 같은 도메인을 다시 등록하면 새 리소스를 만들지 않고 기존 항목을
200 으로 돌려줍니다. 새로 등록된 경우에만 201 입니다.
⚠️ 한 도메인은 ClawOps 전체에서 한 계정만 소유합니다. 다른 계정이 이미 등록했다면 409 입니다.
단, 등록만 해두고 72시간 동안 소유를 증명하지 않은 도메인은 회수되어 다른 계정이 등록할 수
있습니다 — 등록 후에는 DNS 를 설정하고 검증까지 마치세요.
루트 도메인과 하위 도메인은 별개입니다. example.com 과 mail.example.com 을 모두 쓰려면
각각 등록해야 합니다.
Authentication
API Key를 Bearer 토큰으로 전달
Path parameters
계정 ID
Request
등록할 도메인. 소유한 도메인의 전체 이름을 입력합니다.
URL(https://...)·이메일 주소(user@...)·wildcard(*.example.com)·포트·IP 주소는 거절됩니다. 대소문자, 끝 점(example.com.), 한글 도메인은 정규화되므로 그대로 보내도 됩니다.
Response
이미 등록된 도메인 — 기존 항목 반환(멱등)
도메인 리소스 id. 조회·검증·삭제에 이 값을 사용합니다.
정규화된 도메인. 대소문자·끝 점·한글 도메인(punycode 변환)이 모두 정규화되어 저장·응답됩니다. 루트 도메인과 하위 도메인은 서로 다른 리소스입니다.
pending=DNS 설정 또는 확인 대기, verified=DKIM 확인 완료(발신 가능), failed=DNS 레코드를 확인하지 못함(고객 DNS 를 고쳐야 풀립니다).
일시적인 공급자 장애로는 이 값이 내려가지 않습니다 — 그 경우 검증 요청이 503 을 반환하고 상태는 마지막 성공 결과를 유지합니다. 반대로 CNAME 을 지우면 verified 였던 도메인도 failed 로 내려갑니다. 다시 심으면 verified 로 돌아옵니다.
심어야 하는 DNS 레코드. 순서는 계약이 아닙니다.
⛔ 여기 실린 레코드가 전부 필수인 것은 아닙니다. 각 항목의 requirement 를 보고 나누십시오 — required(DKIM CNAME 3건)를 모두 심어야 발송이 열리고, recommended (반송 주소 mail_from_* · dmarc)는 없어도 발송은 되며 도달률에만 영향을 줍니다. optional 은 그 기능을 쓸 때만 심습니다.
receivingEnabled 가 true 면 여기에 수신용 MX 1건(purpose: inbound)이 함께 실립니다. 꺼져 있으면 실리지 않습니다 — 수신을 쓰지 않는 도메인에 MX 를 심으면 그 도메인의 메일이 전부 ClawOps 로 온 뒤 버려지기 때문입니다.
⚠️ dmarc 는 이미 심어 두신 것을 우리가 확인했으면 실리지 않습니다(dmarcStatus 참고). 그 값은 고객 도메인 전체의 정책이라 우리가 제안하는 시작점(p=none)으로 덮어쓰면 안 됩니다.
이 도메인으로 메일을 받을지 여부. status 가 verified 인 도메인만 켤 수 있습니다.
⚠️ 켜는 것만으로 수신되지 않습니다 — dnsRecords 에 나타나는 MX 를 심어야 합니다. 반대로 끄면 MX 가 남아 있어도 받지 않습니다. 그 경우 메일은 ClawOps 까지 도착한 뒤 버려지고 수신 요금은 청구됩니다. 수신을 그만둘 때는 MX 도 함께 지우세요.
ClawOps 가 실제로 조회한 이 도메인의 MX 판정입니다. 수신을 켜지 않았으면 null 입니다.
pending=켰지만 아직 확인하지 않음 · verified=우리 MX 가 있고 우선순위도 단독 최저 · not_found=MX 에 우리 호스트가 없음 · not_lowest_priority=더 낮거나 같은 우선순위의 다른 MX 가 있어 메일이 그쪽으로 가거나 나뉨 · unsupported_region=이 도메인이 등록된 리전은 수신을 지원하지 않음.
⚠️ DNS 조회 자체에 실패하면 이 값은 바뀌지 않습니다. 확인 API 가 200 을 주는데 receivingCheckedAt 이 그대로라면 조회하지 못한 것입니다 — 잠시 뒤 다시 호출하세요. 우리 쪽 일시 장애가 verified 를 뒤집는 일은 없습니다.
MX 를 마지막으로 실제 조회한 시각. 조회에 실패하면 갱신되지 않습니다.
반송 주소(mail_from_* 레코드)가 실제로 섰는지. 아직 시도한 적이 없으면 null 입니다.
pending=레코드를 찾는 중 · verified=반송 주소가 내 도메인으로 섭니다 · failed=탐지를 포기했습니다(레코드를 심고 검증 API 를 다시 호출하면 재설정됩니다).
⛔ status 와 다른 축입니다. 이 값이 pending 이나 failed 여도 메일은 정상 발송됩니다 — 반송 주소만 ClawOps 기본값으로 돌아갈 뿐입니다. 발송 가능 여부는 status 로 판단하십시오.
ClawOps 가 실제로 조회한 이 도메인의 DMARC 정책입니다. 아직 조회한 적이 없으면 null 입니다(검증 API 를 호출하면 채워집니다).
not_found=레코드가 없거나 p 태그가 없어 무효 · spf_strict=aspf=s 가 걸려 있음 · monitor=p=none · enforced=p=quarantine 또는 p=reject.
⛔ spf_strict 는 조치가 필요합니다. 반송 주소(mail_from_*)를 모두 심어도 aspf=s 가 있으면 SPF 정렬이 서지 않아 그 설정이 아무 효과도 내지 못합니다. 그런데 메일은 계속 발송되고 DKIM 으로 DMARC 도 통과하므로, 이 값을 보지 않으면 알 방법이 없습니다. aspf=s 를 빼시면 됩니다(기본값이 relaxed 이고, 그때 정렬이 섭니다).
⚠️ DNS 조회 자체에 실패하면 이 값은 바뀌지 않습니다 — receivingStatus 와 같은 규칙입니다. 그리고 이 값은 발송을 막지 않습니다. DMARC 는 고객 도메인의 정책이지 ClawOps 의 요구사항이 아닙니다.
공급자 상태를 마지막으로 실제 조회한 시각. 조회 자체가 실패하면 갱신되지 않습니다.
최초로 검증된 시각. 이후 DKIM 이 깨졌다가 복구되어도 이 값은 바뀌지 않습니다. 지금 발신 가능한지는 status 로 판단하세요.
⚠️ 이 시각까지 검증을 마치지 않으면 다른 계정이 이 도메인을 등록할 수 있습니다. 한 도메인은 ClawOps 전체에서 한 계정만 소유하는데, 등록만 해두고 소유를 증명하지 않은 도메인이 그 자리를 무기한 붙들면 실제 소유자가 등록할 방법이 없기 때문입니다.
검증 API 를 호출할 때마다 이 시각은 뒤로 밀립니다 — DNS 전파를 기다리는 동안 계속 호출하고 있다면 회수되지 않습니다. status 가 verified 나 failed 면 회수 대상이 아니므로 null 입니다.