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 говорит, будет ли отправка с домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестностью, а не отказом, так что ветвитесь по canSend, а не по status.

update задаёт, перепроверяет или снимает собственный домен трекинга — поддомен вроде links.acme.com — и разрешается в тот же DomainDetailResource, что и get. tracking сообщает о нём при каждом чтении. Пока проверка не прошла, tracking.status равен pending, и отслеживаемые ссылки и пиксель открытия продолжают использовать хост OpenEmail по умолчанию. Как только проверка проходит, он становится active, и новая почта с домена использует домен трекинга для обоих.

get также перечисляет адреса на домене. addresses.list() — родственный вызов: все адреса, которые ЭТОТ КЛЮЧ может поставить в заголовок From, а это уже. This is narrower.

Параметры: domains.get

domainIdstringобязательно: Идентификатор из `domains.list` — UUID, созданный при добавлении домена, а не имя хоста, так что `get('example.com')` ничего не найдёт. Поиск ограничен не только идентификатором, но и собственным подключением ключа, так что домен другого рабочего пространства — это 404, а не 403.

Параметры: domains.update

idstringобязательно: Тот же идентификатор домена, что принимает `get`. Нужная область доступа — `domains:write`.
patch.trackingHoststring | nullобязательно: Поддомен этого домена, не длиннее 512 символов, например `links.acme.com`. Он обрезается и приводится к нижнему регистру, а ведущие `https://` или `http://`, путь и завершающая точка удаляются. Новое значение проверяется, сохраняется и тут же проверяется на месте тем же вызовом. Значение, которое у домена уже есть, запускает проверку заново, если только предыдущая не была меньше 30 секунд назад. `null` или пустая строка удаляет домен трекинга.

Отклонённый хост бросает OpenEmailApiError с trackingHost в param: 422 invalid_tracking_host для имени, которое использовать нельзя, например вне домена; 409 domain_not_verified для нового хоста, пока receiving.verified равно false и TXT-запись _openemail-challenge домена ещё не опубликована; и 409 tracking_host_in_use для имени, которое уже использует другой домен, либо когда доменом трекинга управляет другой сервер OpenEmail. Ключ, ограниченный конкретными адресами, получает 422 capability_unsupported, потому что домен трекинга применяется ко всем адресам домена.

Ответ: DomainDetailResource

object'domain': Всегда строка `domain` — и в строках `list`, и здесь.
idstring: UUID домена. Стабилен всё время жизни строки и единственная ручка, которую принимают остальные вызовы по доменам.
domainstring: Голое имя хоста в нижнем регистре: `example.com`. Уникально в рамках всего продукта, один владелец на домен, так что два рабочих пространства не могут заявить на него права одновременно.
receiving.verifiedboolean: True с того момента, как DNS показал MX домена, называющий хост, который приводит его почту сюда, и, если строка несёт токен подтверждения, соответствующую TXT-запись `_openemail-challenge`. Один MX ничего не доказывает, поскольку каждый домен, для которого мы принимаем почту, публикует одни и те же имена хостов, — поэтому и существует токен, и поэтому именно этот флаг является воротами, которые входящая доставка проверяет перед приёмом почты.
receiving.verifiedAtstring | null: Когда подтверждение прошло, ISO-8601. Null, пока оно не прошло, а `verified` выводится ровно из этой колонки, так что эти двое не могут разойтись.
receiving.catchAllboolean: Принимается ли любая локальная часть. Включено по умолчанию для доменов, добавленных с тех пор, как это стало правилом; при выключенном принимаются только адреса, названные на домене, а остальные отвергаются во время SMTP, так что отправитель получает отбой, а не тишину.
receiving.lastCheckedAtstring | null: Когда DNS в последний раз спрашивали об этом домене. Null означает, что не смотрели ни разу, и для того, кто добавил домен минуту назад, это читается совсем иначе, чем неудача. Этот эндпоинт сообщает сохранённый результат и никогда не запускает собственную проверку.
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: Будет ли отправка с этого домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестностью, а не отказом, так что это может быть true, пока `status` равен `pending`. Ветвитесь по нему перед отправкой: 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: True ровно тогда, когда `status` равен `active`, то есть когда отслеживаемые ссылки и пиксель открытия в новой почте с домена используют этот хост.
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 }>: Все строки адресов на домене — это то, что `get` добавляет к строке `list`. Сюда входят строки, которые доставка написала сама при catch-all, и они перестают приниматься в тот момент, когда catch-all выключают, так что этот массив не является списком того, что будет принимать почту.
addresses[].addressstring: Полный адрес, собранный заново из сохранённой локальной части и имени хоста и приведённый к нижнему регистру, так что он всегда соответствует `domain` выше, а не расходится с ним.
addresses[].enabledboolean: False отключает адрес, а отключённый отвергается даже при включённом catch-all. Все строки перечисляются в любом случае, так что фильтруйте по этому полю, а не читайте массив как набор работающих адресов.
createdAtstring: Когда была добавлена строка домена, ISO-8601. Не когда он подтвердился: это `receiving.verifiedAt`, который может быть null, пока это поле заполнено.