이메일 발신 도메인 검증
공급자에 지금 상태를 물어보고 결과를 저장한 뒤 갱신된 도메인을 돌려줍니다.
DNS 레코드를 심은 뒤 이 API 를 호출해 verified 가 되었는지 확인합니다.
멱등입니다. 몇 번을 호출해도 상태만 갱신됩니다. DNS 전파 대기 중에는 pending 이 그대로
유지되므로, 수 분 간격으로 다시 호출하세요.
⚠️ 공급자에 일시적으로 연결하지 못하면 503 이며, 저장된 상태는 바뀌지 않습니다 —
이미 verified 였던 도메인이 우리 쪽 장애로 실패 처리되는 일은 없습니다.
반대로 CNAME 이 사라진 것이 확인되면 failed 로 내려갑니다.
⚠️ 요청 본문은 없지만 Content-Length: 0 은 필요합니다. 본문도 이 헤더도 없는 POST 는
ClawOps 에 닿기 전에 게이트웨이가 411 Length Required 로 거절합니다(HTML 응답이라
{ error, code } 형식도 아닙니다). 대부분의 HTTP 클라이언트·SDK 는 이 헤더를 자동으로
붙이지만, curl -X POST 는 붙이지 않습니다 — curl -X POST -H 'Content-Length: 0' …
또는 curl -X POST -d '{}' … 로 호출하세요.
Authentication
API Key를 Bearer 토큰으로 전달
Path parameters
계정 ID
도메인 리소스 ID
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 입니다.