Домены
`domains.list`, `list_all`, `iterate`, `get` и `update`.
Все методы
from openemail import openemail domains = openemail.domains.list()domain = openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') print(domain['receiving']['verified'], domain['sending']['status'])for address in domain['addresses']: print(address['address'], address['enabled']) updated = openemail.domains.update(domain['id'], {'trackingHost': 'links.acme.com'})tracking = updated['tracking']print(tracking['status']) if tracking['record'] is not None: print(tracking['record']['name'], tracking['record']['value']) openemail.domains.update(domain['id'], {'trackingHost': None})Приём и отправка являются двумя независимыми фактами, и возвращаются они двумя объектами. 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, а это более узкий набор.
app_host является отдельным пространством имён. get, set, verify и delete читают и меняют адрес веб-приложения рабочего пространства, поддомен, например mailbox.acme.com, на одном из этих доменов или на любом другом домене, которым управляет рабочее пространство, где его люди входят под брендом рабочего пространства. set возвращает записи DNS для публикации, а delete запрашивает у OAuth-приложения код подтверждения, как и set, который заменяет уже имеющийся у рабочего пространства хост.
branding задаёт этот бренд. get читает ссылки на знак, логотип, логотип для тёмной темы и фото страницы входа, оба шрифта и фон страницы входа. update меняет шрифты и фон, upload_image(variant, data, content_type=...) загружает одно из четырёх изображений, а remove_image(variant) удаляет одно. Адрес веб-приложения и, на платном тарифе, письма от имени рабочего пространства брендирует именно логотип.
Параметры: domains.get
idstrобязательно- Идентификатор из `domains.list` (UUID, созданный при добавлении домена), а не имя хоста, так что `get('example.com')` ничего не найдёт. Поиск ограничен не только идентификатором, но и собственным подключением ключа, так что домен другого рабочего пространства даёт 404, а не 403.
Параметры: domains.update
idstrобязательно- Тот же идентификатор домена, что принимает `get`. Нужна область доступа `domains:write`.
patch['trackingHost']str | None- Поддомен этого домена, не длиннее 512 символов, например `links.acme.com`. Он обрезается и приводится к нижнему регистру, а ведущие `https://` или `http://`, путь и завершающая точка удаляются. Новое значение проверяется, сохраняется и тут же проверяется на месте тем же вызовом. Значение, которое у домена уже есть, запускает проверку заново, если только предыдущая не была меньше 30 секунд назад. `None` или пустая строка удаляет домен трекинга.
Отклонённый хост выбрасывает OpenEmailApiError с trackingHost в param: 422 invalid_tracking_host для имени, которое использовать нельзя, например вне домена; 409 domain_not_verified для нового хоста, пока receiving.verified ложно и TXT-запись _openemail-challenge домена ещё не опубликована; и 409 tracking_host_in_use для имени, которое уже использует другой домен, либо когда доменом отслеживания управляет другой сервер OpenEmail. Ключ, ограниченный конкретными адресами, получает 422 capability_unsupported, потому что домен отслеживания применяется ко всем адресам домена.
Ответ: DomainDetailResource
objectLiteral['domain']- Всегда строка `domain` как в строках `list`, так и здесь.
idstr- UUID домена. Стабилен всё время жизни строки и единственная ручка, которую принимают остальные вызовы по доменам.
domainstr- Голое имя хоста в нижнем регистре: `example.com`. Уникально в рамках всего продукта, один владелец на домен, так что два рабочих пространства не могут заявить на него права одновременно.
receiving.verifiedbool- True с того момента, как DNS показал MX домена, называющий хост, который приводит его почту сюда, и, если строка несёт токен подтверждения, соответствующую TXT-запись `_openemail-challenge`. Один MX ничего не доказывает, поскольку каждый домен, для которого мы принимаем почту, публикует одни и те же имена хостов. Поэтому и существует токен, и поэтому именно этот флаг является воротами, которые входящая доставка проверяет перед приёмом почты.
receiving.verifiedAtstr | None- Когда подтверждение прошло, ISO-8601. Null, пока оно не прошло, а `verified` выводится ровно из этой колонки, так что эти двое не могут разойтись.
receiving.catchAllbool- Принимается ли любая локальная часть. Включено по умолчанию для доменов, добавленных с тех пор, как это стало правилом; при выключенном принимаются только адреса, названные на домене, а остальные отвергаются во время SMTP, так что отправитель получает отбой, а не тишину.
receiving.lastCheckedAtstr | None- Когда DNS в последний раз спрашивали об этом домене. Null означает, что не смотрели ни разу, и для того, кто добавил домен минуту назад, это читается совсем иначе, чем неудача. Этот эндпоинт сообщает сохранённый результат и никогда не запускает собственную проверку.
receiving.errorstr | None- Почему последняя проверка не прошла, словами, по которым владелец может действовать. Типичный пример: `No MX records yet. DNS changes can take a few minutes to spread.` Null, когда она проходит, и хранится, а не выводится, чтобы перезагрузка и плановая перепроверка говорили одно и то же.
sending.statusLiteral['verified', 'pending', 'failed', 'no_identity', 'unknown']- Состояние исходящей подписи таким, каким его увидела последняя проверка. Читается из сохранённой проверки, а не зондируется при этом запросе, так что `sending.checkedAt` говорит, насколько оно старое.
sending.canSendbool- Будет ли отправка с этого домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестностью, а не отказом, так что это может быть true, пока `status` равен `pending`. Ветвитесь по нему перед отправкой: false означает, что `emails.send` с этого домена будет отклонена с 409 `domain_not_sendable`.
sending.checkedAtstr | None- Когда состояние подписи проверялось в последний раз, ISO-8601. Null означает «никогда», что читается совсем иначе, чем сбой.
sending.errorstr | None- Последний сбой подписи словами или null, когда проверка проходит.
sending.notestr- Одно из пяти предложений, выбираемое по `sending.status`, объясняющее, что это состояние значит, словами, по которым владелец домена может действовать. Проза для чтения человеком. Ветвитесь по `sending.canSend`, а не по этому полю.
trackingDomainTracking- Собственный домен трекинга этого домена как в строках `list`, так и здесь. Именно его меняет `update`.
tracking.hoststr | None- Домен трекинга, например `links.acme.com`, или null, когда он не задан.
tracking.statusLiteral['none', 'pending', 'active', 'failed']- `none` означает, что домен трекинга не задан, `pending` означает, что он ни разу не проходил проверку, `active` означает, что новая почта его использует, а `failed` означает, что он проходил раньше и с тех пор выбыл из использования. Активный хост выбывает после трёх неудачных проверок подряд либо когда его последней успешной проверке больше 2 часов.
tracking.activebool- True ровно тогда, когда `status` равен `active`, то есть когда отслеживаемые ссылки и пиксель открытия в новых письмах с домена используют этот хост.
tracking.targetstr- Адрес, на который указывает запись CNAME, подготовленный только для этого домена трекинга. Пустая строка, пока `host` равен null и пока адрес для нового хоста ещё готовится.
tracking.recordDomainTrackingRecord | None- Запись, которую нужно опубликовать: её имя берётся из `host`, а значение из `target`. Null, когда tracking-домена нет и пока адрес для нового хоста ещё готовится.
tracking.checkedAtstr | None- Когда хост проверялся в последний раз, ISO-8601. Null до первой проверки.
tracking.verifiedAtstr | None- Когда проверка в последний раз была успешной, ISO-8601. Null для хоста, который ни разу её не прошёл.
tracking.errorstr | None- Что обнаружила последняя проверка, словами, по которым владелец домена может действовать. Null, когда последняя проверка прошла успешно или ни одной ещё не было. Хост, проваливший одну-две проверки, всё ещё `active` и несёт причину здесь.
addresseslist[DomainDetailResourceAddressesItem]- Все строки адресов на домене. Именно их `get` добавляет к строке `list`. Сюда входят строки, которые доставка написала сама при catch-all, и они перестают приниматься в тот момент, когда catch-all выключают, так что этот массив не является списком того, что будет принимать почту.
addresses[].addressstr- Полный адрес, собранный заново из сохранённой локальной части и имени хоста и приведённый к нижнему регистру, так что он всегда соответствует `domain` выше, а не расходится с ним.
addresses[].enabledbool- False отключает адрес, а отключённый отвергается даже при включённом catch-all. Все строки перечисляются в любом случае, так что фильтруйте по этому полю, а не читайте массив как набор работающих адресов.
createdAtstr- Когда была добавлена строка домена, ISO-8601. Не когда он подтвердился: это `receiving.verifiedAt`, который может быть null, пока это поле заполнено.
Справочник
domains.list()Полный справочникdomains.list_all()Полный справочникdomains.iterate()Полный справочникdomains.get()Полный справочникdomains.update()Полный справочникapp_host.get()Полный справочникapp_host.set()Полный справочникapp_host.verify()Полный справочникapp_host.delete()Полный справочникbranding.get()Полный справочникbranding.update()Полный справочникbranding.upload_image()Полный справочникbranding.remove_image()Полный справочник