Domaines
`domains.list`, `list_all`, `iterate`, `get` et `update`.
Toutes les méthodes
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]}"endLa réception et l'envoi sont deux faits indépendants et sont renvoyés sous forme de deux Hashes. 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.dig(:sending, :canSend), plutôt que sur status.
list renvoie une OpenEmail::Page de domaines par ordre alphabétique, et list_all les renvoie tous dans un seul Array. iterate les passe un par un à un bloc. Sans bloc, il renvoie un 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 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 Hash 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::AddressBookPage, qui les place dans addresses plutôt que dans items, à côté de domains et unrestricted. Son list_all renvoie un OpenEmail::AddressBook.
app_host est un espace de noms à part entière, client.app_host. 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 step_up_required? vaut true.
branding définit cette marque. 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. update modifie les polices et l'arrière-plan, upload_image(variant, data, content_type: nil) téléverse l'une des quatre images, et remove_image(variant) en supprime une. variant vaut mark, wordmark, wordmark-dark ou login-background, et OpenEmail::BRAND_IMAGE_VARIANTS les nomme. data est une String binaire, un IO ou un Pathname. Un Pathname comme Pathname("logo.svg"), un File ou un upload Rails apporte son type avec lui. Les autres octets ont besoin de content_type:, 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 forme d'`OpenEmail::NotFoundError`, plutôt qu'un 403. Un id nil ou vide lève ArgumentError 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 nil- 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 nil ou une String vide pour supprimer le domaine de suivi, et omettez le champ pour ne pas y toucher.
Un hôte refusé lève une OpenEmail::ApiError 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 forme d'OpenEmail::ValidationError et chaque 409 sous forme d'OpenEmail::ConflictError. 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 se compose d'arguments nommés ou d'un seul Hash, et ses champs gardent les noms en camelCase de l'API : tracking_host: est donc envoyé tel quel et refusé avec un 422 unknown_parameter. update prend aussi catchAll, storageHost pour un domaine de fichiers comme files.acme.com, et dmarcPolicy. Chaque champ est optionnel et la référence des méthodes les couvre tous. La gem 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.verifiedBoolean- 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 nil- Quand la vérification a réussi, sous forme de String ISO 8601. nil 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.catchAllBoolean- 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 nil- La dernière fois que le DNS a été interrogé sur ce domaine. nil 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 nil- 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. nil 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.canSendBoolean- 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 nil- Quand l'état de la signature a été vérifié pour la dernière fois, sous forme de String ISO 8601. nil quand il ne l'a jamais été, ce qui se lit très différemment d'un échec.
sending.errorString or nil- Le dernier échec de signature, en toutes lettres, ou nil une fois la vérification réussie.
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.
trackingHash- 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 nil- Le domaine de suivi, comme `links.acme.com`, ou nil 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.activeBoolean- 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 String vide tant que `host` vaut nil, et tant que l'adresse d'un nouvel hôte est encore en préparation.
tracking.recordHash or nil- L'enregistrement à publier, un Hash avec `type` (toujours `CNAME`), `name` et `value`, nommé d'après `host` avec `target` pour valeur. nil 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 : `dig(:tracking, :record, :value)` le lit donc sans risque.
tracking.checkedAtString or nil- Quand l'hôte a été vérifié pour la dernière fois, sous forme de String ISO 8601. nil jusqu'à la première vérification.
tracking.verifiedAtString or nil- Quand une vérification a réussi pour la dernière fois, sous forme de String ISO 8601. nil pour un hôte qui n'en a jamais réussi.
tracking.errorString or nil- Ce qu'a trouvé la dernière vérification, en des termes sur lesquels le propriétaire du domaine peut agir. nil 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<Hash>- 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é : l'Array n'est donc pas une liste 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[].enabledBoolean- 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 l'Array comme l'ensemble des adresses qui fonctionnent.
createdAtString- Quand la ligne du domaine a été ajoutée, sous forme de String ISO 8601. Ce n'est pas le moment où le domaine a été vérifié : c'est `receiving.verifiedAt`, qui peut valoir nil alors que ce champ est défini.