Домены
`domains->list`, `listAll`, `iterate`, `get` и `update`.
Все методы
$page = $client->domains->list(); foreach ($page as $row) { echo $row['domain'], ' ', $row['sending']['canSend'] ? 'can send' : 'cannot send yet', PHP_EOL;} $domain = $client->domains->get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f');echo $domain['receiving']['verified'] ? 'receiving' : 'not verified yet', ' ', $domain['sending']['status'], PHP_EOL; foreach ($domain['addresses'] as $entry) { echo $entry['address'], ' ', $entry['enabled'] ? 'on' : 'off', PHP_EOL;}Приём и отправка являются двумя независимыми фактами и возвращаются двумя массивами. receiving.verified означает, что MX домена доставляет его почту сюда и что проверка владения опубликована. sending сообщает о проверке подписи исходящей почты: status равен verified, pending, failed, no_identity или unknown, а canSend говорит, была бы отправка с домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестным, а не отказом, поэтому ветвитесь по canSend, который читается как $domain['sending']['canSend'], а не по status.
list возвращает одну OpenEmail\Result\Page доменов в алфавитном порядке, а listAll возвращает их все одним массивом. iterate возвращает Generator, который выдаёт их по одному.
$domainId = 'b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f'; $updated = $client->domains->update($domainId, ['trackingHost' => 'links.acme.com']);$record = $updated['tracking']['record'];echo $updated['tracking']['status'], ' ', $record['name'] ?? '', ' ', $record['value'] ?? '', PHP_EOL; $client->domains->update($domainId, ['trackingHost' => null]);update задаёт, перепроверяет или снимает собственный домен трекинга, поддомен вроде links.acme.com, и возвращает тот же массив, что и get. tracking сообщает о нём при каждом чтении. Пока проверка не прошла, tracking.status равен pending, а отслеживаемые ссылки и пиксель открытия продолжают использовать хост OpenEmail по умолчанию. Как только проверка проходит, статус становится active, и новая почта с домена использует домен трекинга и для того, и для другого.
get также перечисляет адреса на домене. Связанный вызов addresses->list возвращает более узкий набор: адреса, которые этот ключ может указывать в заголовке From, каждый с вердиктом canSend. Он возвращает OpenEmail\Result\AddressBookPage, где они лежат в addresses, а не в items, рядом с domains и unrestricted. Его listAll возвращает один OpenEmail\Result\AddressBook.
appHost является отдельным пространством имён, $client->appHost. get, set, verify и delete читают и меняют адрес веб-приложения рабочего пространства, поддомен вроде mailbox.acme.com на одном из этих доменов или на любом другом домене, которым управляет рабочее пространство: там его люди входят под брендом рабочего пространства. set возвращает DNS-записи для публикации в record, а для домена вне рабочего пространства ещё и в ownershipRecord. delete и set, заменяющий адрес, запрашивают у приложения OAuth код подтверждения: пока его нет, вызов выбрасывает 403, у которого isStepUpRequired() равно true.
branding задаёт этот бренд. branding->get читает ссылки на знак, логотип, логотип для тёмной темы и фото для страницы входа, два шрифта и фон страницы входа. branding->update меняет шрифты и фон, branding->uploadImage($variant, $data, contentType: ...) загружает одно из четырёх изображений, а branding->removeImage($variant) удаляет одно из них. Вариант принимает значения mark, wordmark, wordmark-dark или login-background, и OpenEmail\Constants\BrandImageVariants их перечисляет. Данные передаются как строка байтов, ресурс потока, SplFileInfo либо поток PSR-7 или загруженный файл. SplFileInfo вроде new \SplFileInfo('logo.svg'), поток, открытый на файле, или загрузка Laravel либо Symfony несут свой тип с собой. Другим байтам нужен contentType:, а изображение без типа отклоняется с 422 invalid_image. Логотип брендирует адрес веб-приложения, а на платном тарифе и письма, отправляемые от имени рабочего пространства.
Параметры: domains->get
idstringобязательно- Идентификатор из `domains->list`, UUID, выданный при добавлении домена, а не имя хоста, поэтому `get('example.com')` ничего не найдёт. Поиск ограничен не только идентификатором, но и рабочим пространством самого ключа, поэтому домен другого рабочего пространства даёт 404, выбрасываемый как `NotFoundException`, а не 403. Пустой идентификатор выбрасывает `InvalidArgumentException` ещё до отправки.
Параметры: domains->update
idstringобязательно- Тот же идентификатор домена, что принимает `get`. Нужна область доступа `domains:write`.
trackingHoststring or null- Поддомен домена, не более 512 символов, например `links.acme.com`. Пробелы по краям обрезаются, значение приводится к нижнему регистру, а начальные `https://` или `http://`, путь и завершающая точка удаляются. Новое значение проверяется на корректность, сохраняется и проверяется в том же вызове. Значение, которое у домена уже есть, запускает проверку заново, если последняя была не меньше 30 секунд назад. Передайте null или пустую строку, чтобы снять домен трекинга, и не указывайте ключ, чтобы оставить его как есть.
Отклонённый хост выбрасывает ApiException с trackingHost в param: 422 invalid_tracking_host для имени, которое нельзя использовать, например вне домена, 409 domain_not_verified для нового хоста, пока receiving.verified равно false и TXT-запись _openemail-challenge домена ещё не опубликована, и 409 tracking_host_in_use для имени, которое уже использует другой домен, или когда доменом трекинга управляет другой сервер OpenEmail. 422 приходит как ValidationException, а каждый 409 как ConflictException. Ключ, ограниченный определёнными адресами, получает 422 capability_unsupported, потому что домен трекинга применяется ко всем адресам на домене.
Изменение представляет собой один массив с ключами по именам 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.verifiedbool- True с того момента, как DNS показал MX домена, называющий хост, который приводит его почту сюда, и, если строка несёт токен подтверждения, соответствующую TXT-запись `_openemail-challenge`. Один MX ничего не доказывает, поскольку каждый домен, для которого мы принимаем почту, публикует одни и те же имена хостов. Поэтому и существует токен, и поэтому именно этот флаг является воротами, которые входящая доставка проверяет перед приёмом почты.
receiving.verifiedAtstring or null- Когда проверка прошла, в виде строки ISO 8601. null, пока она не прошла, а `verified` выводится именно из этого столбца, поэтому они никогда не расходятся.
receiving.catchAllbool- Принимается ли любая локальная часть адреса. По умолчанию включено для доменов, добавленных с тех пор, как это стало правилом. Когда выключено, принимаются только адреса, названные на домене, а остальные отклоняются на этапе SMTP, поэтому отправитель получает отказ, а не тишину.
receiving.lastCheckedAtstring or null- Когда DNS в последний раз спрашивали об этом домене. null, если DNS никогда не спрашивали, и для того, кто добавил домен минуту назад, это читается совсем иначе, чем сбой. Чтение непроверенного домена снова опрашивает DNS, если последней проверке больше 20 секунд, поэтому опрос `get` является одним из способов дождаться проверки, а `verify` проверяет сразу.
receiving.errorstring or null- Почему последняя проверка не прошла, словами, по которым владелец может действовать. Типичный пример: `No MX records yet. DNS changes can take a few minutes to spread.` Как только проверка проходит, значение становится null. Оно хранится, а не выводится, поэтому перезагрузка и плановая перепроверка говорят одно и то же.
sending.statusstring- Состояние подписи исходящей почты по данным последней проверки: `verified`, `pending`, `failed`, `no_identity` или `unknown`. Читается из сохранённой проверки, поэтому `sending.checkedAt` показывает её возраст.
sending.canSendbool- Будет ли отправка с этого домена принята прямо сейчас. Отрицательный вердикт старше суток считается неизвестностью, а не отказом, так что это может быть true, пока `status` равен `pending`. Ветвитесь по нему перед отправкой: false означает, что `emails->send` с этого домена будет отклонена с 409 `domain_not_sendable`.
sending.checkedAtstring or null- Когда состояние подписи проверялось в последний раз, в виде строки ISO 8601. null, если не проверялось никогда, а это читается совсем иначе, чем сбой.
sending.errorstring or null- Последний сбой подписи словами или null, когда проверка проходит.
sending.notestring- Одна из пяти фраз, выбираемая по `sending.status`, которая объясняет, что означает это состояние, словами, по которым владелец домена может действовать. Это текст для человека, поэтому ветвитесь по `sending.canSend`, а не по нему.
trackingarray- Собственный домен трекинга этого домена как в строках `list`, так и здесь. Именно его меняет `update`.
tracking.hoststring or null- Домен трекинга, например `links.acme.com`, или null, когда он не задан.
tracking.statusstring- `none` означает, что домен трекинга не задан, `pending` означает, что он ни разу не проходил проверку, `active` означает, что новая почта его использует, а `failed` означает, что он проходил раньше и с тех пор выбыл из использования. Активный хост выбывает после трёх неудачных проверок подряд либо когда его последней успешной проверке больше 2 часов.
tracking.activebool- True ровно тогда, когда `status` равен `active`, то есть когда отслеживаемые ссылки и пиксель открытия в новых письмах с домена используют этот хост.
tracking.targetstring- Адрес, на который указывает CNAME-запись, подготовленный исключительно для этого tracking-домена. Это пустая строка, пока `host` равен null и пока адрес для нового хоста ещё готовится.
tracking.recordarray or null- Запись для публикации, массив с `type` (всегда `CNAME`), `name` и `value`: имя берётся из `host`, а значением служит `target`. null, когда домена трекинга нет и пока адрес для нового хоста ещё готовится, поэтому `$domain['tracking']['record']['value'] ?? null` читает её безопасно.
tracking.checkedAtstring or null- Когда хост проверялся в последний раз, в виде строки ISO 8601. null до первой проверки.
tracking.verifiedAtstring or null- Когда проверка в последний раз прошла, в виде строки ISO 8601. null у хоста, который ни разу её не прошёл.
tracking.errorstring or null- Что обнаружила последняя проверка, словами, по которым владелец домена может действовать. null, если последняя проверка прошла или проверок ещё не было. Хост, который не прошёл одну или две проверки, всё ещё `active` и несёт причину здесь.
addressesarray- Все строки адресов на домене: это то, что `get` добавляет к строке `list`. Сюда входят строки, которые доставка записала сама при включённом catch-all, а они перестают приниматься в момент выключения catch-all, поэтому список не является списком того, что будет принимать почту.
addresses[].addressstring- Полный адрес, собранный заново из сохранённой локальной части и имени хоста и приведённый к нижнему регистру, так что он всегда соответствует `domain` выше, а не расходится с ним.
addresses[].enabledbool- False отключает адрес, и отключённый адрес отклоняется даже при включённом catch-all. Все строки выводятся в любом случае, поэтому фильтруйте по этому полю, а не считайте список набором работающих адресов.
createdAtstring- Когда была добавлена строка домена, в виде строки ISO 8601. Это не момент проверки домена: он хранится в `receiving.verifiedAt`, который может быть null, когда это поле задано.