Domaines
`domains->list`, `listAll`, `iterate`, `get` et `update`.
Toutes les méthodes
$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;}La réception et l'envoi sont deux faits indépendants et sont renvoyés sous forme de deux tableaux. receiving.verified signifie que le MX du domaine amène son courrier ici et que sa preuve de propriété est publiée. sending rend compte de la vérification de signature sortante : status vaut verified, pending, failed, no_identity ou unknown, et canSend indique si un envoi depuis le domaine serait accepté à cet instant. Un verdict négatif de plus d'un jour est traité comme inconnu plutôt que comme un refus : branchez-vous donc sur canSend, lu avec $domain['sending']['canSend'], plutôt que sur status.
list renvoie une OpenEmail\Result\Page de domaines par ordre alphabétique, et listAll les renvoie tous dans un seul tableau. iterate renvoie un Generator qui les fournit un par un.
$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 définit, revérifie ou supprime le domaine de suivi personnalisé du domaine, un sous-domaine comme links.acme.com, et renvoie le même tableau que get. tracking le signale à chaque lecture. Tant qu'aucune vérification n'a réussi, tracking.status vaut pending et les liens suivis comme le pixel d'ouverture continuent d'utiliser l'hôte OpenEmail par défaut. Dès qu'une vérification réussit, il vaut active et le nouveau courrier du domaine utilise le domaine de suivi pour les deux.
get liste aussi les adresses du domaine. addresses->list est l'appel apparenté : les adresses que cette clé peut mettre dans un en-tête From, ce qui est plus restreint, chacune avec un verdict canSend. Il renvoie une OpenEmail\Result\AddressBookPage, qui les place dans addresses plutôt que dans items, à côté de domains et unrestricted. Son listAll renvoie un OpenEmail\Result\AddressBook.
appHost est un espace de noms à part entière, $client->appHost. get, set, verify et delete lisent et modifient l'adresse de l'application web de l'espace de travail, un sous-domaine comme mailbox.acme.com sur l'un de ces domaines ou sur tout autre domaine que contrôle l'espace de travail, où ses membres se connectent sous la marque de l'espace de travail. set renvoie les enregistrements DNS à publier, dans record et, pour un domaine extérieur à l'espace de travail, dans ownershipRecord. delete, et un set qui remplace une adresse, demandent un code de vérification à une application OAuth : tant qu'elle n'en a pas, l'appel lève un 403 dont isStepUpRequired() vaut true.
branding définit cette marque. branding->get lit les liens vers l'emblème, le logo, le logo pour le mode sombre et la photo de connexion, les deux polices et l'arrière-plan de connexion. branding->update modifie les polices et l'arrière-plan, branding->uploadImage($variant, $data, contentType: ...) téléverse l'une des quatre images, et branding->removeImage($variant) en supprime une. La variante vaut mark, wordmark, wordmark-dark ou login-background, et OpenEmail\Constants\BrandImageVariants les nomme. Les données sont une chaîne d'octets, une ressource de flux, un SplFileInfo ou un flux ou un fichier téléversé PSR-7. Un SplFileInfo comme new \SplFileInfo('logo.svg'), un flux ouvert sur un fichier, ou un upload Laravel ou Symfony apporte son type avec lui. Les autres octets ont besoin de contentType:, et une image sans type est refusée avec un 422 invalid_image. Le logo est ce qui donne sa marque à l'adresse de l'application web et, avec un forfait payant, aux e-mails envoyés pour l'espace de travail.
Paramètres : domains->get
idstringobligatoire- L'id issu de `domains->list`, un UUID créé à l'ajout du domaine, et non le nom d'hôte : `get('example.com')` ne trouve donc rien. La recherche est limitée à l'espace de travail de la clé autant qu'à l'id : le domaine d'un autre espace de travail donne donc un 404, levé sous la forme d'une `NotFoundException`, plutôt qu'un 403. Un id vide lève `InvalidArgumentException` avant tout envoi.
Paramètres : domains->update
idstringobligatoire- Le même id de domaine que prend `get`. `domains:write` est la portée requise.
trackingHoststring or null- Un sous-domaine du domaine, 512 caractères au maximum, comme `links.acme.com`. Il est rogné et mis en minuscules, et un `https://` ou `http://` en tête, un chemin et un point final sont retirés. Une nouvelle valeur est validée, enregistrée et vérifiée dans le même appel. La valeur que le domaine a déjà relance la vérification, sauf si la dernière date de moins de 30 secondes. Passez null ou une chaîne vide pour supprimer le domaine de suivi, et omettez la clé pour ne pas y toucher.
Un hôte refusé lève une ApiException qui nomme trackingHost dans param : un 422 invalid_tracking_host pour un nom inutilisable, comme un nom hors du domaine, un 409 domain_not_verified pour un nouvel hôte tant que receiving.verified vaut false et que l'enregistrement TXT _openemail-challenge du domaine n'est pas encore publié, et un 409 tracking_host_in_use pour un nom qu'un autre domaine utilise déjà, ou quand le domaine de suivi est géré par un autre serveur OpenEmail. Le 422 arrive sous la forme d'une ValidationException et chaque 409 sous la forme d'une ConflictException. Une clé limitée à des adresses précises reçoit un 422 capability_unsupported, car un domaine de suivi s'applique à toutes les adresses du domaine.
Le patch est un seul tableau dont les clés sont les noms en camelCase de l'API : une clé comme tracking_host est donc envoyée telle quelle et refusée avec un 422 unknown_parameter. update prend aussi catchAll, storageHost pour un domaine de fichiers comme files.acme.com, et dmarcPolicy. Chaque clé est optionnelle et la référence des méthodes les couvre toutes. Le client réessaie update comme une lecture, car une répétition trouve l'hôte déjà défini et, au pire, le vérifie de nouveau.
Réponse : un domaine (domains->get)
objectstring- Toujours la chaîne `domain`, aussi bien sur les lignes de `list` que sur celle-ci.
idstring- L'UUID du domaine. Stable pendant toute la vie de la ligne, et le seul identifiant qu'acceptent les autres appels sur les domaines.
domainstring- Le nom d'hôte nu, en minuscules : `example.com`. Unique dans tout le produit, un seul propriétaire par domaine : deux espaces de travail ne peuvent donc pas le revendiquer tous les deux.
receiving.verifiedbool- Vrai dès que le DNS a montré que le MX du domaine nomme un hôte qui amène son courrier ici et, lorsque la ligne porte un jeton de défi, l'enregistrement TXT `_openemail-challenge` correspondant. Le MX seul ne prouve rien, puisque chaque domaine pour lequel nous recevons publie les mêmes noms d'hôte : d'où le jeton, et d'où le fait que cet indicateur soit la barrière que la remise entrante vérifie avant d'accepter du courrier.
receiving.verifiedAtstring or null- Quand la vérification a réussi, sous forme de chaîne ISO 8601. null tant que ce n'est pas le cas, et `verified` est dérivé exactement de cette colonne : les deux ne peuvent donc jamais se contredire.
receiving.catchAllbool- Indique si toute partie locale est acceptée. Activé par défaut pour les domaines ajoutés depuis que cette règle existe. Désactivé, seules les adresses nommées sur le domaine sont acceptées et les autres sont rejetées dès la phase SMTP : l'expéditeur reçoit donc un rebond plutôt que le silence.
receiving.lastCheckedAtstring or null- La dernière fois que le DNS a été interrogé sur ce domaine. null quand le DNS n'a jamais été interrogé, ce qui se lit très différemment d'un échec pour quelqu'un qui a ajouté un domaine il y a une minute. Lire un domaine non vérifié interroge de nouveau le DNS dès que la dernière vérification a plus de 20 secondes : interroger régulièrement `get` est donc une façon d'attendre la vérification, et `verify` vérifie immédiatement.
receiving.errorstring or null- Pourquoi la dernière vérification n'a pas réussi, en termes sur lesquels le propriétaire peut agir : `No MX records yet. DNS changes can take a few minutes to spread.` en est un exemple typique. null une fois la vérification réussie, et stocké plutôt que dérivé, pour qu'un rechargement et la revérification planifiée disent la même chose.
sending.statusstring- L'état de la signature sortante tel que l'a vu la dernière vérification : `verified`, `pending`, `failed`, `no_identity` ou `unknown`. Il est lu dans la vérification stockée : `sending.checkedAt` indique donc son âge.
sending.canSendbool- Si un envoi depuis ce domaine serait accepté à l'instant. Un verdict négatif vieux de plus d'un jour est traité comme inconnu plutôt que comme un refus : ceci peut donc être vrai alors que `status` vaut `pending`. Branchez dessus avant un envoi : un false signifie que `emails->send` depuis ce domaine est refusé par un 409 `domain_not_sendable`.
sending.checkedAtstring or null- Quand l'état de la signature a été vérifié pour la dernière fois, sous forme de chaîne ISO 8601. null quand il ne l'a jamais été, ce qui se lit très différemment d'un échec.
sending.errorstring or null- Le dernier échec de signature en toutes lettres, ou null une fois qu'elle réussit.
sending.notestring- L'une de cinq phrases, choisie selon `sending.status`, qui dit ce que signifie cet état en des termes sur lesquels un propriétaire de domaine peut agir. C'est un texte destiné à un humain : branchez-vous donc sur `sending.canSend` plutôt que sur celui-ci.
trackingarray- Le domaine de suivi personnalisé du domaine, aussi bien sur les lignes de `list` que sur celle-ci, et ce que modifie `update`.
tracking.hoststring or null- Le domaine de suivi, tel que `links.acme.com`, ou null quand aucun n'est défini.
tracking.statusstring- `none` signifie qu'aucun domaine de suivi n'est défini, `pending` qu'il n'a jamais passé de vérification, `active` que le courrier nouvellement envoyé l'utilise, et `failed` qu'il en était là et a depuis cessé d'être employé. Un hôte actif est écarté après trois vérifications ratées d'affilée, ou dès que sa dernière vérification réussie remonte à plus de 2 heures.
tracking.activebool- Vaut true exactement quand `status` est `active`, c'est-à-dire quand les liens suivis et le pixel d'ouverture des nouveaux messages issus du domaine utilisent l'hôte.
tracking.targetstring- L'adresse vers laquelle pointe l'enregistrement CNAME, préparée pour ce seul domaine de suivi. C'est une chaîne vide tant que `host` est null, et tant que l'adresse d'un nouvel hôte est encore en cours de préparation.
tracking.recordarray or null- L'enregistrement à publier, un tableau avec `type` (toujours `CNAME`), `name` et `value`, nommé d'après `host` avec `target` pour valeur. null quand il n'y a pas de domaine de suivi, et tant que l'adresse d'un nouvel hôte est encore en préparation : `$domain['tracking']['record']['value'] ?? null` le lit donc sans risque.
tracking.checkedAtstring or null- Quand l'hôte a été vérifié pour la dernière fois, sous forme de chaîne ISO 8601. null jusqu'à la première vérification.
tracking.verifiedAtstring or null- Quand une vérification a réussi pour la dernière fois, sous forme de chaîne ISO 8601. null pour un hôte qui n'en a jamais réussi.
tracking.errorstring or null- Ce qu'a trouvé la dernière vérification, en des termes sur lesquels le propriétaire du domaine peut agir. null quand la dernière vérification a réussi ou qu'aucune n'a encore été faite. Un hôte qui a échoué à une ou deux vérifications reste `active` et porte la raison ici.
addressesarray- Chaque ligne d'adresse du domaine, ce que `get` ajoute par rapport à une ligne de `list`. Cela inclut les lignes que la distribution a écrites elle-même sous le catch-all, et celles-ci cessent d'être acceptées dès que le catch-all est désactivé : la liste n'est donc pas celle de ce qui recevra.
addresses[].addressstring- L'adresse complète, reconstruite à partir de la partie locale stockée et du nom d'hôte puis mise en minuscules, de sorte qu'elle corresponde toujours au `domain` ci-dessus au lieu de s'en écarter.
addresses[].enabledbool- False désactive l'adresse, et une adresse désactivée est rejetée même quand le catch-all est activé. Chaque ligne est listée dans les deux cas : filtrez donc sur ce champ plutôt que de lire la liste comme l'ensemble des adresses qui fonctionnent.
createdAtstring- Quand la ligne du domaine a été ajoutée, sous forme de chaîne ISO 8601. Ce n'est pas le moment où le domaine a été vérifié : c'est `receiving.verifiedAt`, qui peut valoir null alors que ce champ est défini.