SDK

도메인

`domains.list`, `get`, `update`.

모든 메서드

usage.ts

const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })

수신과 발신은 서로 독립적인 두 가지 사실이며 두 개의 객체로 반환됩니다. receiving.verified는 도메인의 MX가 메일을 이곳으로 가져오고 소유권 확인 항목이 게시되어 있다는 뜻입니다. sending은 발신 서명 검사 결과를 보고합니다. status는 verified, pending, failed, no_identity, unknown 중 하나이고, canSend는 지금 이 도메인에서 보낸 메일이 수락될지를 말해 줍니다. 하루보다 오래된 부정적 판정은 거부가 아니라 unknown으로 취급되므로, status가 아니라 canSend로 분기하세요.

update는 links.acme.com 같은 서브도메인인 도메인 전용 추적 도메인을 설정하거나 다시 검사하거나 제거하며, get과 같은 DomainDetailResource로 resolve됩니다. tracking이 모든 조회에서 그 상태를 보고합니다. 검사를 통과하기 전까지 tracking.status는 pending이고, 추적 링크와 열람 픽셀은 기본 OpenEmail 호스트를 계속 사용합니다. 한 번 통과하면 active가 되고, 그 도메인에서 나가는 새 메일은 두 가지 모두에 추적 도메인을 사용합니다.

get은 도메인에 있는 주소 목록도 함께 반환합니다. addresses.list()는 관련된 호출로, 이 키가 From 헤더에 넣을 수 있는 모든 주소를 돌려주므로 범위가 더 좁습니다.

매개변수: domains.get

domainIdstring필수: `domains.list`에서 얻은 id로, 호스트명이 아니라 도메인이 추가될 때 발급된 UUID이므로 `get('example.com')`으로는 아무것도 찾지 못합니다. 조회는 id뿐 아니라 키 자신의 connection으로도 한정되므로, 다른 워크스페이스의 도메인은 403이 아니라 404입니다.

매개변수: domains.update

idstring필수: `get`이 받는 것과 같은 도메인 id입니다. 필요한 스코프는 `domains:write`입니다.
patch.trackingHoststring | null필수: 해당 도메인의 서브도메인이며 최대 512자입니다. 예를 들어 `links.acme.com`입니다. 값은 공백이 제거되고 소문자로 바뀌며, 앞의 `https://`나 `http://`, 경로, 끝의 점은 제거됩니다. 새 값은 같은 호출에서 검증되고 저장되고 검사됩니다. 도메인이 이미 가진 값을 다시 보내면 검사를 다시 실행하되, 마지막 검사가 30초 이내였다면 실행하지 않습니다. `null`이나 빈 문자열은 추적 도메인을 제거합니다.

거부된 호스트는 param에 trackingHost를 담은 OpenEmailApiError를 던집니다. 도메인 밖에 있는 이름처럼 사용할 수 없는 이름은 422 invalid_tracking_host, receiving.verified가 false이고 도메인의 _openemail-challenge TXT 레코드가 아직 게시되지 않은 상태에서의 새 호스트는 409 domain_not_verified, 다른 도메인이 이미 쓰고 있거나 추적 도메인이 다른 OpenEmail 서버에서 관리되는 이름은 409 tracking_host_in_use입니다. 특정 주소로 제한된 키는 422 capability_unsupported를 받는데, 추적 도메인은 그 도메인의 모든 주소에 적용되기 때문입니다.

응답: DomainDetailResource

object'domain': `list` 행에서나 여기서나 항상 문자열 `domain`입니다.
idstring: 도메인의 UUID입니다. 행이 존재하는 동안 변하지 않으며, 다른 도메인 호출들이 받는 유일한 핸들입니다.
domainstring: 소문자로 된 호스트명 자체입니다. 예: `example.com`. 제품 전체에서 유일하며 도메인당 소유자는 하나이므로, 두 워크스페이스가 같은 도메인을 주장할 수 없습니다.
receiving.verifiedboolean: 도메인의 MX가 메일을 이곳으로 가져오는 호스트를 가리키고, 행에 확인 토큰이 있는 경우 그에 맞는 `_openemail-challenge` TXT 레코드까지 DNS에서 확인되면 true가 됩니다. 우리가 수신을 맡는 모든 도메인이 같은 호스트명을 게시하므로 MX만으로는 아무것도 증명되지 않으며, 그래서 토큰이 존재하고 또 이 플래그가 수신 배달이 메일을 수락하기 전에 확인하는 관문인 것입니다.
receiving.verifiedAtstring | null: 검증이 통과한 시각이며 ISO-8601입니다. 통과하지 않은 동안에는 null이고, `verified`는 정확히 이 컬럼에서 파생되므로 둘이 어긋날 수 없습니다.
receiving.catchAllboolean: 임의의 local-part를 수락할지 여부입니다. 이 규칙이 생긴 이후 추가된 도메인에서는 기본으로 켜져 있습니다. 꺼져 있으면 도메인에 등록된 주소만 수락되고 나머지는 SMTP 단계에서 거부되므로, 발신자는 침묵이 아니라 반송을 받습니다.
receiving.lastCheckedAtstring | null: 이 도메인에 대해 DNS를 마지막으로 조회한 시각입니다. null은 한 번도 조회하지 않았다는 뜻으로, 1분 전에 도메인을 추가한 사람에게는 실패와 전혀 다르게 읽힙니다. 이 엔드포인트는 저장된 결과를 보고할 뿐 자체적으로 검사를 실행하지 않습니다.
receiving.errorstring | null: 마지막 검사가 통과하지 못한 이유를 소유자가 조치할 수 있는 말로 담습니다. `No MX records yet. DNS changes can take a few minutes to spread.`가 대표적입니다. 통과하면 null이 되며, 파생값이 아니라 저장된 값이므로 새로고침과 예약된 재검사가 같은 말을 합니다.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': 마지막 검사가 본 발신 서명 상태입니다. 이 요청에서 탐지하는 것이 아니라 저장된 검사 결과에서 읽으므로, 얼마나 오래된 값인지는 `sending.checkedAt`이 알려 줍니다.
sending.canSendboolean: 지금 이 도메인에서 보낸 메일이 수락될지 여부입니다. 하루보다 오래된 부정적 판정은 거부가 아니라 unknown으로 취급되므로, `status`가 `pending`인데도 이 값이 true일 수 있습니다. 발송 전에는 이 값으로 분기하세요. false라면 이 도메인에서의 `emails.send`는 409 `domain_not_sendable`로 거부됩니다.
sending.checkedAtstring | null: 서명 상태를 마지막으로 검사한 시각이며 ISO-8601입니다. null은 한 번도 검사하지 않았다는 뜻으로, 실패와는 전혀 다르게 읽힙니다.
sending.errorstring | null: 마지막 서명 실패를 설명하는 문장이며, 통과하고 나면 null입니다.
sending.notestring: `sending.status`에 따라 선택되는 다섯 문장 중 하나로, 그 상태가 도메인 소유자가 조치할 수 있는 말로 무엇을 뜻하는지 설명합니다. 사람이 읽는 산문입니다. 분기는 이 값이 아니라 `sending.canSend`로 하세요.
trackingDomainTracking: 도메인 전용 추적 도메인이며, `list` 행에서나 여기서나 동일하게 담기고 `update`가 바꾸는 대상입니다.
tracking.hoststring | null: `links.acme.com` 같은 추적 도메인이며, 설정되지 않았으면 null입니다.
tracking.status'none' | 'pending' | 'active' | 'failed': `none`은 추적 도메인이 설정되지 않았다는 뜻, `pending`은 아직 한 번도 검사를 통과하지 못했다는 뜻, `active`는 새 메일이 그것을 사용한다는 뜻, `failed`는 이전에 통과했다가 이후 사용에서 빠졌다는 뜻입니다. 활성 호스트는 연속 세 번 검사에 실패하거나 마지막으로 통과한 검사가 2시간을 넘기면 사용에서 빠집니다.
tracking.activeboolean: `status`가 `active`일 때에 한해 true이며, 그때가 그 도메인에서 나가는 새 메일의 추적 링크와 열람 픽셀이 이 호스트를 사용하는 시점입니다.
tracking.targetstring: CNAME 레코드가 가리킬 주소로, 이 추적 도메인만을 위해 준비된 값입니다. `host`가 null인 동안, 그리고 새 호스트용 주소가 아직 준비 중인 동안에는 빈 문자열입니다.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: 게시할 레코드로, 이름은 `host`를 따르고 값은 `target`입니다. 추적 도메인이 없을 때, 그리고 새 호스트용 주소가 아직 준비 중일 때는 null입니다.
tracking.checkedAtstring | null: 호스트를 마지막으로 검사한 시각이며 ISO-8601입니다. 첫 검사 전까지는 null입니다.
tracking.verifiedAtstring | null: 검사를 마지막으로 통과한 시각이며 ISO-8601입니다. 한 번도 통과하지 못한 호스트에서는 null입니다.
tracking.errorstring | null: 마지막 검사에서 발견한 내용을 도메인 소유자가 조치할 수 있는 말로 담습니다. 마지막 검사가 통과했거나 아직 아무 검사도 실행되지 않았으면 null입니다. 한두 번 검사에 실패한 호스트는 여전히 `active`이며 그 사유를 여기에 담습니다.
addressesArray<{ address: string; enabled: boolean }>: 도메인에 있는 모든 주소 행이며, `list` 행에 비해 `get`이 추가로 제공하는 것입니다. catch-all 하에서 배달 과정이 스스로 기록한 행도 포함되고 그런 행은 catch-all을 끄는 순간 더 이상 수락되지 않으므로, 이 배열은 수신할 주소의 목록이 아닙니다.
addresses[].addressstring: 저장된 local-part와 호스트명을 합쳐 소문자로 재구성한 전체 주소이므로, 위의 `domain`과 어긋나지 않고 항상 일치합니다.
addresses[].enabledboolean: false는 주소를 비활성화하며, 비활성화된 주소는 catch-all이 켜져 있어도 거부됩니다. 어느 쪽이든 모든 행이 목록에 나오므로, 배열을 동작하는 주소의 집합으로 읽지 말고 이 값으로 필터링하세요.
createdAtstring: 도메인 행이 추가된 시각이며 ISO-8601입니다. 검증된 시각이 아닙니다. 그것은 `receiving.verifiedAt`이며, 이 값이 있어도 그쪽은 null일 수 있습니다.