SDK
Domaines
`domains.list`, `get` et `update`.
Toutes les méthodes
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 })Réception et envoi sont deux faits indépendants et reviennent en deux objets. receiving.verified signifie que le MX du domaine amène son courrier ici et que son défi de propriété est publié. sending rapporte la vérification de signature sortante : status vaut verified, pending, failed, no_identity ou unknown, et canSend dit 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 : branchez donc sur canSend plutôt que sur status.
update définit, revérifie ou supprime le domaine de suivi personnalisé du domaine, un sous-domaine tel que links.acme.com, et se résout en le même DomainDetailResource que get. tracking le rapporte à 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 réussit, il vaut active et le courrier nouvellement envoyé depuis le domaine utilise le domaine de suivi pour les deux.
get liste aussi les adresses du domaine. addresses.list() est l'appel voisin : toutes les adresses que CETTE CLÉ peut mettre dans un en-tête From, ce qui est plus restreint.
Paramètres : domains.get
domainIdstringobligatoire- L'id issu de `domains.list`, un UUID créé quand le domaine a été ajouté, et non le nom d'hôte : `get('example.com')` ne trouve donc rien. La recherche est limitée à la connexion de la clé autant qu'à l'id : le domaine d'un autre espace de travail donne donc un 404 plutôt qu'un 403.
Paramètres : domains.update
idstringobligatoire- Le même id de domaine que prend `get`. `domains:write` est la portée requise.
patch.trackingHoststring | nullobligatoire- Un sous-domaine du domaine, de 512 caractères au plus, tel que `links.acme.com`. Il est nettoyé des espaces 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 porte déjà relance la vérification, sauf si la dernière date de moins de 30 secondes. `null` ou une chaîne vide supprime le domaine de suivi.
Un hôte refusé lève une OpenEmailApiError nommant trackingHost dans param : 422 invalid_tracking_host pour un nom inutilisable, par exemple hors du domaine, 409 domain_not_verified pour un nouvel hôte tant que receiving.verified est false et que l'enregistrement TXT _openemail-challenge du domaine n'est pas publié, et 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. Une clé limitée à des adresses précises obtient 422 capability_unsupported, parce qu'un domaine de suivi s'applique à toutes les adresses du domaine.
Réponse : DomainDetailResource
object'domain'- Toujours la chaîne `domain`, aussi bien sur les lignes de `list` que sur celle-ci.
idstring- L'UUID du domaine. Stable toute la vie de la ligne, et la seule référence qu'acceptent les autres appels de domaine.
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 | null- Quand la vérification a réussi, 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.catchAllboolean- 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 le reste est rejeté au moment du SMTP, si bien que l'expéditeur reçoit un avis de non-remise plutôt que le silence.
receiving.lastCheckedAtstring | null- Quand le DNS a été interrogé pour la dernière fois sur ce domaine. Null signifie qu'on n'a jamais regardé, ce qui se lit très différemment d'un échec pour quelqu'un qui a ajouté un domaine il y a une minute. Cet endpoint rapporte le résultat stocké, sans jamais lancer de vérification propre.
receiving.errorstring | null- Pourquoi la dernière vérification n'est pas passée, en mots sur lesquels le propriétaire peut agir : `No MX records yet. DNS changes can take a few minutes to spread.` en est un exemple courant. Null une fois qu'elle passe, et stocké plutôt que dérivé pour qu'un rechargement et la revérification programmée disent la même chose.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown'- L'état de la signature sortante tel que l'a vu la dernière vérification. Lu depuis la vérification stockée plutôt que sondé sur cette requête : `sending.checkedAt` dit donc son ancienneté.
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 | null- Quand l'état de signature a été vérifié pour la dernière fois, ISO-8601. Null signifie jamais, ce qui se lit très différemment d'un échec.
sending.errorstring | 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 par `sending.status`, disant ce que cet état signifie en mots sur lesquels un propriétaire de domaine peut agir. De la prose destinée à un humain. Branchez sur `sending.canSend` plutôt que sur elle.
trackingDomainTracking- 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 | null- Le domaine de suivi, tel que `links.acme.com`, ou null quand aucun n'est défini.
tracking.status'none' | 'pending' | 'active' | 'failed'- `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- Vrai exactement quand `status` vaut `active`, c'est-à-dire quand les liens suivis et le pixel d'ouverture du courrier nouvellement envoyé depuis le domaine utilisent cet hôte.
tracking.targetstring- L'adresse que vise l'enregistrement CNAME, préparée pour ce seul domaine de suivi. Une chaîne vide tant que `host` est null, et tant que l'adresse d'un nouvel hôte est encore en préparation.
tracking.record{ type: 'CNAME'; name: string; value: string } | null- L'enregistrement à publier, nommé d'après `host` et ayant `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.
tracking.checkedAtstring | null- Quand l'hôte a été vérifié pour la dernière fois, ISO-8601. Null jusqu'à la première vérification.
tracking.verifiedAtstring | null- Quand une vérification a réussi pour la dernière fois, ISO-8601. Null pour un hôte qui n'en a jamais passé une.
tracking.errorstring | null- Ce qu'a trouvé la dernière vérification, en mots sur lesquels le propriétaire du domaine peut agir. Null quand la dernière a réussi ou qu'aucune n'a encore tourné. Un hôte qui a raté une ou deux vérifications est encore `active` et porte ici la raison.
addressesArray<{ address: string; enabled: boolean }>- Chaque ligne d'adresse du domaine, ce que `get` ajoute par rapport à une ligne de `list`. Elle inclut les lignes que la remise a écrites elle-même sous catch-all, et celles-ci cessent d'être acceptées dès que le catch-all est désactivé : le tableau n'est donc pas la 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 actif. Toutes les lignes sont listées dans les deux cas : filtrez donc là-dessus plutôt que de lire le tableau comme l'ensemble des adresses qui fonctionnent.
createdAtstring- Quand la ligne du domaine a été ajoutée, ISO-8601. Pas le moment de sa vérification : c'est `receiving.verifiedAt`, qui peut être null alors que celui-ci est renseigné.