도메인
`domains.list`, `list_all`, `iterate`, `get`, `update`.
모든 메서드
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"end수신과 발신은 서로 독립적인 두 가지 사실이며 두 개의 Hash로 반환됩니다. receiving.verified는 도메인의 MX가 메일을 이곳으로 가져오고 소유권 확인 항목이 게시되어 있다는 뜻입니다. sending은 발신 서명 검사 결과를 보고합니다: status는 verified, pending, failed, no_identity, unknown 중 하나이고, canSend는 지금 이 도메인에서 보낸 메일이 수락될지를 말해 줍니다. 하루보다 오래된 부정적 판정은 거부가 아니라 unknown으로 취급되므로, status가 아니라 domain.dig(:sending, :canSend)로 읽는 canSend로 분기하세요.
list는 알파벳순으로 정렬된 도메인의 OpenEmail::Page 하나를 반환하고, list_all은 전부를 하나의 Array로 반환합니다. iterate는 하나씩 블록에 yield합니다. 블록이 없으면 Enumerator를 반환합니다.
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)update는 links.acme.com 같은 서브도메인인 도메인 전용 추적 도메인을 설정하거나 다시 검사하거나 제거하며, get과 같은 Hash를 반환합니다. tracking이 모든 조회에서 그 상태를 보고합니다. 검사를 통과하기 전까지 tracking.status는 pending이고, 추적 링크와 열람 픽셀은 기본 OpenEmail 호스트를 계속 사용합니다. 한 번 통과하면 active가 되고, 그 도메인에서 나가는 새 메일은 두 가지 모두에 추적 도메인을 사용합니다.
get은 도메인의 주소도 나열합니다. 관련된 호출은 addresses.list입니다: 이 키가 From 헤더에 넣을 수 있는 주소로, 범위가 더 좁으며 각각 canSend 판정을 가집니다. 이는 OpenEmail::AddressBookPage를 반환하는데, 주소를 items가 아니라 addresses에 domains, unrestricted와 나란히 담습니다. 그 list_all은 OpenEmail::AddressBook 하나를 반환합니다.
app_host는 별도의 네임스페이스로, client.app_host입니다. get, set, verify, delete는 워크스페이스의 웹 앱 주소를 읽고 바꾸며, 이 주소는 이 도메인 중 하나 또는 워크스페이스가 관리하는 다른 도메인에 속한 mailbox.acme.com 같은 서브도메인으로 워크스페이스 사람들이 워크스페이스 브랜드로 로그인하는 곳입니다. set은 게시할 DNS 레코드를 record에, 워크스페이스 밖의 도메인이면 ownershipRecord에도 담아 반환합니다. delete와 주소를 교체하는 set은 OAuth 앱에 인증 코드를 요구합니다: 코드를 얻기 전까지 호출은 step_up_required?가 true인 403을 발생시킵니다.
branding은 그 브랜드를 설정합니다. get은 마크, 로고, 다크 모드용 로고, 로그인 사진의 링크와 두 글꼴, 로그인 배경을 읽습니다. update는 글꼴과 배경을 바꾸고, upload_image(variant, data, content_type: nil)은 이미지 네 개 중 하나를 업로드하며, remove_image(variant)는 하나를 제거합니다. variant는 mark, wordmark, wordmark-dark, login-background 중 하나이며, OpenEmail::BRAND_IMAGE_VARIANTS가 이들을 정의합니다. data는 바이너리 String, IO, Pathname 중 하나입니다. Pathname("logo.svg") 같은 Pathname, File, Rails 업로드는 자체 유형을 가지고 옵니다. 그 밖의 바이트에는 content_type:이 필요하며, 유형이 없는 이미지는 422 invalid_image로 거부됩니다. 웹 앱 주소와, 유료 요금제에서 워크스페이스를 위해 보내는 이메일에 브랜드를 입히는 것은 로고입니다.
매개변수: domains.get
idString필수- `domains.list`에서 얻은 id로, 호스트명이 아니라 도메인이 추가될 때 발급된 UUID이므로 `get("example.com")`으로는 아무것도 찾지 못합니다. 조회는 id뿐 아니라 키 자신의 워크스페이스로도 한정되므로, 다른 워크스페이스의 도메인은 403이 아니라 `OpenEmail::NotFoundError`로 발생하는 404입니다. nil이나 빈 id는 무엇이든 보내기 전에 ArgumentError를 발생시킵니다.
매개변수: domains.update
idString필수- `get`이 받는 것과 같은 도메인 id입니다. 필요한 스코프는 `domains:write`입니다.
trackingHostString or nil- 해당 도메인의 서브도메인이며 최대 512자입니다. 예를 들어 `links.acme.com`입니다. 값은 공백이 제거되고 소문자로 바뀌며, 앞의 `https://`나 `http://`, 경로, 끝의 점은 제거됩니다. 새 값은 같은 호출에서 검증되고 저장되고 검사됩니다. 도메인이 이미 가진 값을 다시 보내면 검사를 다시 실행하되, 마지막 검사가 30초 이내였다면 실행하지 않습니다. nil이나 빈 String을 전달하면 추적 도메인을 제거하고, 필드를 생략하면 그대로 둡니다.
거부된 호스트는 param에 trackingHost를 담은 OpenEmail::ApiError를 발생시킵니다: 도메인 밖에 있는 이름처럼 사용할 수 없는 이름은 422 invalid_tracking_host, receiving.verified가 false이고 도메인의 _openemail-challenge TXT 레코드가 아직 게시되지 않은 상태에서의 새 호스트는 409 domain_not_verified, 다른 도메인이 이미 쓰고 있거나 추적 도메인이 다른 OpenEmail 서버에서 관리되는 이름은 409 tracking_host_in_use입니다. 422는 OpenEmail::ValidationError로, 각 409는 OpenEmail::ConflictError로 도착합니다. 특정 주소로 제한된 키는 422 capability_unsupported를 받는데, 추적 도메인은 그 도메인의 모든 주소에 적용되기 때문입니다.
변경 내용은 키워드 인자나 Hash 하나이며, 그 필드는 API의 camelCase 이름을 그대로 쓰므로 tracking_host:는 쓰인 그대로 보내져 422 unknown_parameter로 거부됩니다. update는 catchAll, files.acme.com 같은 파일 도메인을 위한 storageHost, 그리고 dmarcPolicy도 받습니다. 모든 필드는 선택 사항이며, 메서드 레퍼런스에서 각각을 다룹니다. 반복해도 호스트가 이미 설정되어 있어 기껏해야 다시 검사할 뿐이므로, gem은 update를 읽기처럼 재시도합니다.
응답: 도메인(domains.get)
objectString- `list` 행에서나 여기서나 항상 문자열 `domain`입니다.
idString- 도메인의 UUID입니다. 행이 존재하는 동안 변하지 않으며, 다른 도메인 호출들이 받는 유일한 핸들입니다.
domainString- 소문자로 된 호스트명 자체입니다. 예: `example.com`. 제품 전체에서 유일하며 도메인당 소유자는 하나이므로, 두 워크스페이스가 같은 도메인을 주장할 수 없습니다.
receiving.verifiedBoolean- 도메인의 MX가 메일을 이곳으로 가져오는 호스트를 가리키고, 행에 확인 토큰이 있는 경우 그에 맞는 `_openemail-challenge` TXT 레코드까지 DNS에서 확인되면 true가 됩니다. 우리가 수신을 맡는 모든 도메인이 같은 호스트명을 게시하므로 MX만으로는 아무것도 증명되지 않으며, 그래서 토큰이 존재하고 또 이 플래그가 수신 배달이 메일을 수락하기 전에 확인하는 관문인 것입니다.
receiving.verifiedAtString or nil- 검증이 통과한 시각이며 ISO 8601 String입니다. 통과하지 않은 동안에는 nil이고, `verified`는 정확히 이 컬럼에서 파생되므로 둘이 어긋날 수 없습니다.
receiving.catchAllBoolean- 임의의 local-part를 수락할지 여부입니다. 이 규칙이 생긴 이후 추가된 도메인에서는 기본으로 켜져 있습니다. 꺼져 있으면 도메인에 등록된 주소만 수락되고 나머지는 SMTP 단계에서 거부되므로, 발신자는 침묵이 아니라 반송을 받습니다.
receiving.lastCheckedAtString or nil- 이 도메인에 대해 마지막으로 DNS에 질의한 시각입니다. 한 번도 질의하지 않았으면 nil이며, 1분 전에 도메인을 추가한 사람에게 이는 실패와 전혀 다르게 읽힙니다. 검증되지 않은 도메인을 읽으면 마지막 검사가 20초보다 오래되었을 때 DNS에 다시 질의하므로, `get`을 폴링하는 것이 검증을 기다리는 한 방법이며, `verify`는 즉시 검사합니다.
receiving.errorString or nil- 마지막 검사가 통과하지 못한 이유를 소유자가 조치할 수 있는 말로 담습니다: `No MX records yet. DNS changes can take a few minutes to spread.`가 대표적입니다. 통과하면 nil이 되며, 파생값이 아니라 저장된 값이므로 새로고침과 예약된 재검사가 같은 말을 합니다.
sending.statusString- 마지막 검사가 본 발신 서명 상태입니다: `verified`, `pending`, `failed`, `no_identity`, `unknown` 중 하나입니다. 저장된 검사 결과에서 읽으므로, 얼마나 오래된 값인지는 `sending.checkedAt`이 알려 줍니다.
sending.canSendBoolean- 지금 이 도메인에서 보낸 메일이 수락될지 여부입니다. 하루보다 오래된 부정적 판정은 거부가 아니라 unknown으로 취급되므로, `status`가 `pending`인데도 이 값이 true일 수 있습니다. 발송 전에는 이 값으로 분기하세요. false라면 이 도메인에서의 `emails.send`는 409 `domain_not_sendable`로 거부됩니다.
sending.checkedAtString or nil- 서명 상태를 마지막으로 검사한 시각이며 ISO 8601 String입니다. 한 번도 검사하지 않았으면 nil이며, 이는 실패와는 전혀 다르게 읽힙니다.
sending.errorString or nil- 마지막 서명 실패를 설명하는 문장이며, 통과하고 나면 nil입니다.
sending.noteString- `sending.status`에 따라 선택되는 다섯 문장 중 하나로, 그 상태가 무엇을 뜻하는지 도메인 소유자가 조치할 수 있는 말로 설명합니다. 사람이 읽는 산문이므로, 분기는 이 값이 아니라 `sending.canSend`로 하세요.
trackingHash- 도메인 전용 추적 도메인이며, `list` 행에서나 여기서나 동일하게 담기고 `update`가 바꾸는 대상입니다.
tracking.hostString or nil- `links.acme.com` 같은 추적 도메인이며, 설정되지 않았으면 nil입니다.
tracking.statusString- `none`은 추적 도메인이 설정되지 않았다는 뜻, `pending`은 아직 한 번도 검사를 통과하지 못했다는 뜻, `active`는 새 메일이 그것을 사용한다는 뜻, `failed`는 이전에 통과했다가 이후 사용에서 빠졌다는 뜻입니다. 활성 호스트는 연속 세 번 검사에 실패하거나 마지막으로 통과한 검사가 2시간을 넘기면 사용에서 빠집니다.
tracking.activeBoolean- `status`가 `active`일 때에 한해 true이며, 그때가 바로 이 도메인에서 나가는 새 메일의 추적 링크와 열람 픽셀이 그 호스트를 사용하는 때입니다.
tracking.targetString- CNAME 레코드가 가리키는 주소로, 이 추적 도메인 전용으로 준비된 것입니다. `host`가 nil인 동안, 그리고 새 호스트용 주소가 아직 준비 중인 동안에는 빈 String입니다.
tracking.recordHash or nil- 게시해야 할 레코드로, `type`(항상 `CNAME`), `name`, `value`를 가진 Hash이며, 이름은 `host`를 따르고 값은 `target`입니다. 추적 도메인이 없을 때, 그리고 새 호스트용 주소가 아직 준비 중일 때는 nil이므로, `dig(:tracking, :record, :value)`로 안전하게 읽을 수 있습니다.
tracking.checkedAtString or nil- 호스트를 마지막으로 검사한 시각이며 ISO 8601 String입니다. 첫 검사 전까지는 nil입니다.
tracking.verifiedAtString or nil- 마지막으로 검사를 통과한 시각이며 ISO 8601 String입니다. 한 번도 통과한 적 없는 호스트는 nil입니다.
tracking.errorString or nil- 마지막 검사가 발견한 내용을, 도메인 소유자가 바로 조치할 수 있는 표현으로 담습니다. 마지막 검사가 통과했거나 아직 검사가 실행되지 않았다면 nil입니다. 한두 번 검사에 실패한 호스트는 여전히 `active`이며 그 사유가 여기에 담깁니다.
addressesArray<Hash>- 도메인에 있는 모든 주소 행이며, `list` 행에 비해 `get`이 추가로 제공하는 것입니다. catch-all 하에서 배달 과정이 스스로 기록한 행도 포함되고 그런 행은 catch-all을 끄는 순간 더 이상 수락되지 않으므로, 이 Array는 수신할 주소의 목록이 아닙니다.
addresses[].addressString- 저장된 local-part와 호스트명을 합쳐 소문자로 재구성한 전체 주소이므로, 위의 `domain`과 어긋나지 않고 항상 일치합니다.
addresses[].enabledBoolean- false는 주소를 비활성화하며, 비활성화된 주소는 catch-all이 켜져 있어도 거부됩니다. 어느 쪽이든 모든 행이 목록에 나오므로, Array를 동작하는 주소의 집합으로 읽지 말고 이 값으로 필터링하세요.
createdAtString- 도메인 행이 추가된 시각이며 ISO 8601 String입니다. 검증된 시각이 아닙니다: 그것은 `receiving.verifiedAt`이며, 이 값이 있어도 그쪽은 nil일 수 있습니다.