Домены
`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 говорит, была бы отправка с домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестным, а не отказом, поэтому ветвитесь по canSend, который читается как domain.dig(:sending, :canSend), а не по status.
list возвращает одну OpenEmail::Page доменов в алфавитном порядке, а list_all возвращает их все одним Array. iterate передаёт их по одному в блок. Без блока он возвращает 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, и возвращает тот же Hash, что и get. tracking сообщает о нём при каждом чтении. Пока проверка не прошла, tracking.status равен pending, а отслеживаемые ссылки и пиксель открытия продолжают использовать хост OpenEmail по умолчанию. Как только проверка проходит, статус становится active, и новая почта с домена использует домен трекинга и для того, и для другого.
get также перечисляет адреса на домене. Связанный вызов addresses.list возвращает более узкий набор: адреса, которые этот ключ может указывать в заголовке From, каждый с вердиктом canSend. Он возвращает OpenEmail::AddressBookPage, где они лежат в addresses, а не в items, рядом с 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 код подтверждения: пока его нет, вызов выбрасывает 403, у которого step_up_required? равно true.
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 вроде Pathname("logo.svg"), File или загрузка Rails несут свой тип с собой. Другим байтам нужен content_type:, а изображение без типа отклоняется с 422 invalid_image. Логотип брендирует адрес веб-приложения, а на платном тарифе и письма, отправляемые от имени рабочего пространства.
Параметры: domains.get
idStringобязательно- Идентификатор из `domains.list`, UUID, выданный при добавлении домена, а не имя хоста, поэтому `get("example.com")` ничего не найдёт. Поиск ограничен не только идентификатором, но и рабочим пространством самого ключа, поэтому домен другого рабочего пространства даёт 404, выбрасываемый как `OpenEmail::NotFoundError`, а не 403. nil или пустой идентификатор выбрасывает ArgumentError ещё до отправки.
Параметры: domains.update
idStringобязательно- Тот же идентификатор домена, что принимает `get`. Нужна область доступа `domains:write`.
trackingHostString or nil- Поддомен домена, не более 512 символов, например `links.acme.com`. Пробелы по краям обрезаются, значение приводится к нижнему регистру, а начальные `https://` или `http://`, путь и завершающая точка удаляются. Новое значение проверяется на корректность, сохраняется и проверяется в том же вызове. Значение, которое у домена уже есть, запускает проверку заново, если последняя была не меньше 30 секунд назад. Передайте nil или пустую String, чтобы снять домен трекинга, и не указывайте поле, чтобы оставить его как есть.
Отклонённый хост выбрасывает OpenEmail::ApiError с trackingHost в param: 422 invalid_tracking_host для имени, которое нельзя использовать, например вне домена, 409 domain_not_verified для нового хоста, пока receiving.verified равно false и TXT-запись _openemail-challenge домена ещё не опубликована, и 409 tracking_host_in_use для имени, которое уже использует другой домен, или когда доменом трекинга управляет другой сервер OpenEmail. 422 приходит как OpenEmail::ValidationError, а каждый 409 как OpenEmail::ConflictError. Ключ, ограниченный определёнными адресами, получает 422 capability_unsupported, потому что домен трекинга применяется ко всем адресам на домене.
Изменение передаётся именованными аргументами или одним Hash, а его поля сохраняют имена API в camelCase, поэтому tracking_host: отправляется как написано и отклоняется с 422 unknown_parameter. update также принимает catchAll, storageHost для домена файлов вроде files.acme.com и dmarcPolicy. Каждое поле необязательно, и справочник методов описывает каждое. Гем повторяет update как чтение, потому что повтор найдёт хост уже заданным и самое большее проверит его снова.
Ответ: домен (domains.get)
objectString- Всегда строка `domain` как в строках `list`, так и здесь.
idString- UUID домена. Стабилен на протяжении всей жизни записи и является единственным дескриптором, который принимают остальные вызовы для доменов.
domainString- Голое имя хоста в нижнем регистре: `example.com`. Уникально в рамках всего продукта, один владелец на домен, так что два рабочих пространства не могут заявить на него права одновременно.
receiving.verifiedBoolean- True с того момента, как DNS показал MX домена, называющий хост, который приводит его почту сюда, и, если строка несёт токен подтверждения, соответствующую TXT-запись `_openemail-challenge`. Один MX ничего не доказывает, поскольку каждый домен, для которого мы принимаем почту, публикует одни и те же имена хостов. Поэтому и существует токен, и поэтому именно этот флаг является воротами, которые входящая доставка проверяет перед приёмом почты.
receiving.verifiedAtString or nil- Когда проверка прошла, в виде String ISO 8601. nil, пока она не прошла, а `verified` выводится именно из этого столбца, поэтому они никогда не расходятся.
receiving.catchAllBoolean- Принимается ли любая локальная часть адреса. По умолчанию включено для доменов, добавленных с тех пор, как это стало правилом. Когда выключено, принимаются только адреса, названные на домене, а остальные отклоняются на этапе SMTP, поэтому отправитель получает отказ, а не тишину.
receiving.lastCheckedAtString or nil- Когда DNS в последний раз спрашивали об этом домене. nil, если DNS никогда не спрашивали, и для того, кто добавил домен минуту назад, это читается совсем иначе, чем сбой. Чтение непроверенного домена снова опрашивает DNS, если последней проверке больше 20 секунд, поэтому опрос `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- Будет ли отправка с этого домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестностью, а не отказом, так что это может быть true, пока `status` равен `pending`. Ветвитесь по нему перед отправкой: false означает, что `emails.send` с этого домена будет отклонена с 409 `domain_not_sendable`.
sending.checkedAtString or nil- Когда состояние подписи проверялось в последний раз, в виде String ISO 8601. 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- True ровно тогда, когда `status` равен `active`, то есть когда отслеживаемые ссылки и пиксель открытия в новых письмах с домена используют этот хост.
tracking.targetString- Адрес, на который указывает запись CNAME, подготовленный только для этого домена трекинга. Пустая String, пока `host` равен nil и пока адрес для нового хоста ещё готовится.
tracking.recordHash or nil- Запись для публикации, Hash с `type` (всегда `CNAME`), `name` и `value`: имя берётся из `host`, а значением служит `target`. nil, когда домена трекинга нет и пока адрес для нового хоста ещё готовится, поэтому `dig(:tracking, :record, :value)` читает её безопасно.
tracking.checkedAtString or nil- Когда хост проверялся в последний раз, в виде String ISO 8601. nil до первой проверки.
tracking.verifiedAtString or nil- Когда проверка в последний раз прошла, в виде String ISO 8601. nil у хоста, который ни разу её не прошёл.
tracking.errorString or nil- Что обнаружила последняя проверка, словами, по которым владелец домена может действовать. nil, если последняя проверка прошла или проверок ещё не было. Хост, который не прошёл одну или две проверки, всё ещё `active` и несёт причину здесь.
addressesArray<Hash>- Все строки адресов на домене: это то, что `get` добавляет к строке `list`. Сюда входят строки, которые доставка записала сама при включённом catch-all, а они перестают приниматься в момент выключения catch-all, поэтому Array не является списком того, что будет принимать почту.
addresses[].addressString- Полный адрес, собранный заново из сохранённой локальной части и имени хоста и приведённый к нижнему регистру, так что он всегда соответствует `domain` выше, а не расходится с ним.
addresses[].enabledBoolean- False отключает адрес, и отключённый адрес отклоняется даже при включённом catch-all. Все строки выводятся в любом случае, поэтому фильтруйте по этому полю, а не считайте Array набором работающих адресов.
createdAtString- Когда была добавлена строка домена, в виде String ISO 8601. Это не момент проверки домена: он хранится в `receiving.verifiedAt`, который может быть nil, когда это поле задано.