Domaines et adresses

Deux espaces de noms couvrent vos domaines. openemail domains gère les domaines rattachés à l'espace de travail : les ajouter et les retirer, les enregistrements DNS dont chacun a besoin, s'il peut recevoir et envoyer, son catch-all, ses domaines de suivi et de fichiers, et ses adresses. openemail addresses répond à une question plus étroite : sous quelles adresses la clé ou la connexion que vous utilisez peut envoyer.

• —Une commande de domaine prend l'identifiant du domaine, un UUID venant de domains list ou domains create. Le nom d'hôte n'est pas accepté à sa place, donc openemail domains get acme.com donne un 404 et sort avec le code 5.
• —Une commande d'adresse prend l'identifiant du domaine puis celui de l'adresse, un UUID venant de domains list-addresses ou domains create-address.
• —domain et address fonctionnent aussi comme noms d'espace de noms. Les verbes de domaine répondent aux alias habituels, comme ls, show, new, edit et rm, tout comme addresses list. Les cinq verbes pour les adresses d'un domaine, comme create-address, n'en ont aucun.
• —openemail <command> --help liste chaque argument et option avec son type, le scope dont l'appel a besoin, sa méthode et son chemin, et ce qui revient. Ajoutez --json pour obtenir la même page sous forme de données.

Un domaine rapporte deux faits indépendants. receiving.verified vaut true dès que le DNS public répond avec ses enregistrements MX et son enregistrement TXT _openemail-challenge, et à partir de là il reçoit du courrier. sending.status est l'état de signature tel que la dernière vérification l'a vu : verified, pending, failed, no_identity ou unknown. sending.canSend indique si un envoi depuis le domaine serait accepté en ce moment, et un verdict négatif de plus d'un jour compte comme inconnu, un script doit donc se fier à canSend plutôt qu'à status. Tant qu'il vaut false, un envoi depuis le domaine est refusé avec 409 domain_not_sendable.

• —domains create lance la première vérification DNS pendant l'appel, donc chaque entrée de records porte déjà un status : found, missing, ou null quand elle n'a pas encore été vérifiée. Publiez chaque enregistrement exactement tel qu'il est donné, car les valeurs sont propres au domaine.
• —domains verify vérifie tout de suite. Dans les 10 secondes qui suivent la dernière vérification, elle ne vérifie rien de nouveau et renvoie le domaine tel quel. Sur un domaine vérifié, elle revérifie les enregistrements de signature, pour que sending soit à jour.
• —domains get revérifie un domaine non vérifié quand la dernière vérification date de plus de 20 secondes, donc interroger get fonctionne aussi et ne demande que domains:read, là où verify demande domains:write.
• —Un enregistrement publié à l'instant peut mettre quelques minutes à apparaître dans le DNS public.

Dans un terminal, get, create et verify affichent un champ par ligne, avec les blocs imbriqués comme receiving, sending et records en JSON compact. Ajoutez --json et lisez-les avec un outil comme jq, comme le font les exemples ci-dessous.

domains update modifie trois réglages indépendants les uns des autres. Une option omise reste inchangée, et sans aucune option le domaine revient inchangé.

• —Un nouvel hôte est enregistré et vérifié dans le même appel. Publiez un enregistrement CNAME nommé record.name avec la valeur record.value du bloc tracking ou storage de la réponse, avec tout proxy désactivé. Reconfigurer un hôte peut lui donner une autre valeur, publiez donc celle que rapporte la dernière réponse.
• —Tant qu'aucune vérification ne réussit, l'hôte indique pending et le nouveau courrier garde l'hôte OpenEmail par défaut. Dès qu'une vérification réussit, il indique active. OpenEmail continue de vérifier de lui-même, et un hôte actif qui échoue à trois vérifications de suite, ou dont la dernière vérification réussie date de 2 heures, indique failed tandis que le nouveau courrier revient à l'hôte par défaut.
• —Retirez un hôte avec null, comme dans --tracking-host null. Une valeur vide comme --tracking-host= est une erreur d'utilisation dans la CLI et sort avec le code 2.
• —Un nouvel hôte exige que le domaine soit vérifié, ou au moins que son enregistrement TXT _openemail-challenge soit publié. Sinon, l'appel est refusé avec 409 domain_not_verified.
• —Les options s'appliquent dans l'ordre : le catch-all, puis le domaine de suivi, puis le domaine de fichiers. Une option ultérieure refusée peut laisser enregistré un changement antérieur, envoyez-les donc dans des appels séparés quand chacune doit tenir seule.

Un domaine contient les adresses créées à la main ou via l'API, et celles que son catch-all a recueillies quand du courrier est arrivé pour elles la première fois. list-addresses montre les deux types, adresses désactivées comprises. Le catch-all lui-même n'est pas une ligne : c'est receiving.catchAll sur le domaine.

• —create-address prend --local-part, la partie devant le @, et un --label facultatif. Le domaine n'a pas besoin d'être déjà vérifié, mais l'adresse ne reçoit rien tant qu'il ne l'est pas. * seul est refusé, puisque c'est ainsi que s'écrit le catch-all.
• —Créer une adresse qui existe déjà, ou qui a été retirée, n'est pas une erreur. Elle revient activée, avec le libellé envoyé ou sans libellé, et garde son identifiant. Une adresse recueillie par le catch-all devient une adresse créée à la main, et continue donc de recevoir après la désactivation du catch-all.
• —Avec le catch-all activé, une nouvelle adresse démarre avec les réglages par adresse du catch-all, comme sa signature et son suivi, hors réglages de confidentialité. Ils sont copiés une fois et ne sont pas maintenus en phase.
• —update-address --no-enabled empêche l'adresse de recevoir du courrier, si bien que les expéditeurs reçoivent un rebond, et rien ne peut être envoyé depuis elle. Elle garde son courrier, ses réglages et les personnes qui peuvent y accéder, et --enabled reprend là où elle s'était arrêtée. --label la renomme, et --label null retire le nom.
• —delete-address va plus loin. Le courrier adressé à l'adresse est refusé même avec le catch-all activé, son transfert s'arrête, ses réglages sont supprimés, les personnes qui y avaient accès perdent cet accès, et sa connexion par mot de passe est révoquée. Le courrier qu'elle a déjà reçu reste dans la boîte mail. La recréer fait revenir le même identifiant, sans les anciens réglages ni les anciens accès.

openemail addresses list répond à la question derrière un 403 from_address_forbidden : quelles adresses la clé ou la connexion avec laquelle vous appelez peut mettre dans From. Elle demande emails:send plutôt qu'un scope de lecture, parce qu'elle décrit ce qu'un envoi accepterait.

• —Dans un terminal, elle affiche deux tableaux : les adresses, chacune avec son état d'activation et si vous pouvez envoyer depuis elle, puis les domaines, chacun avec s'il est vérifié pour la réception et pour l'envoi, et son catch-all.
• —unrestricted vaut true quand l'identifiant n'est restreint par rien. On peut alors envoyer depuis n'importe quelle partie locale sur les domaines de l'espace de travail, y compris celles que personne n'a créées. Sinon, canSend ne vaut true que pour une adresse activée que l'identifiant couvre, via un domaine entier qu'il détient ou sa propre liste d'adresses.
• —canSend vaut false pour une adresse désactivée, pour une adresse que l'identifiant ne couvre pas, et pour une adresse dont le domaine ne peut pas encore signer.
• —Seules les adresses créées sont listées. Un identifiant qui détient un domaine entier peut toujours envoyer sous n'importe quelle partie locale de ce domaine, et une adresse de sa liste sans boîte mail derrière peut servir à envoyer sans apparaître ici.
• —Avec --json, elle affiche { unrestricted, addresses, domains, hasMore, nextCursor } pour une page, et { unrestricted, addresses, domains } avec --all, plutôt que le document { items, hasMore, nextCursor } qu'affichent les autres listes. Avec --all dans un pipe, ou avec --ndjson, elle affiche une adresse par ligne.

openemail status lit votre connexion, addresses list et domains list en même temps et les affiche ensemble. Son tableau Sender addresses montre chaque adresse avec si elle peut envoyer et si elle est activée. Son tableau Domains montre chaque domaine comme verified ou not verified pour la réception, son état d'envoi et son catch-all. Elle affiche les 100 premiers de chaque et nomme la commande --all pour le reste.

• —Une partie que votre identifiant ne peut pas lire, comme les domaines sans domains:read ou les adresses sans emails:send, indique Not available avec la raison, et le reste s'affiche quand même.
• —Sans aucune adresse, elle suggère openemail domains create --domain example.com.
• —openemail status --json affiche un objet avec account, addresses, domains et unavailable, où unavailable donne la raison pour chaque partie qui n'a pas pu être lue.

La liaison d'un fournisseur DNS, pour que les enregistrements d'un nouveau domaine soient écrits pour vous, ne se fait que dans l'application web dans 0.0.2. openemail open providers, ou open dns, ouvre cette page. open domains ouvre les domaines et leurs enregistrements DNS, et open addresses les adresses. Le transfert se trouve aussi dans l'application web, et open forwarding <address> l'ouvre pour une adresse. --print affiche le lien au lieu d'ouvrir un navigateur.

openemail domains create --domain acme.com --json > acme.jsonjq -r '.records[] | [.type, .name, .value, (.priority // "")] | @tsv' acme.jsonopenemail domains verify "$(jq -r .id acme.json)"

id=b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6funtil openemail domains get "$id" --json | jq -e .receiving.verified > /dev/null; do  sleep 30doneopenemail domains get "$id" --json | jq '.sending | {status, canSend, error}'

openemail domains list-addresses "$id" --allopenemail domains create-address "$id" --local-part invoices --label Invoicesopenemail domains update "$id" --no-catch-all --dry-runopenemail domains update "$id" --no-catch-all

Créer invoices à la main lui permet de continuer à recevoir une fois le catch-all désactivé, tandis que le courrier pour toute autre adresse recueillie par le catch-all est refusé. La simulation affiche le PATCH et son corps sans l'envoyer.

openemail domains update "$id" --tracking-host links.acme.com --json | jq '.tracking | {status, record, error}'openemail domains update "$id" --tracking-host null

address_id=$(openemail domains list-addresses "$id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail domains update-address "$id" "$address_id" --no-enabledopenemail domains delete-address "$id" "$address_id" --yes

Désactiver d'abord l'adresse peut être annulé avec --enabled. La suppression, non, et dans un script elle exige --yes. Avec une connexion par navigateur, elle demande aussi un code de vérification, que --yes ne saute jamais.

openemail domains list --all | jq -r 'select(.sending.canSend | not) | [.domain, .sending.status] | @tsv'openemail addresses list --all --json | jq -r '.addresses[] | select(.canSend) | .address'

• —Une connexion ou une clé sans le scope s'arrête avec le code de sortie 4, nomme le scope manquant et explique comment l'obtenir.
• —domains delete et domains delete-address demandent confirmation. Répondre non sort avec le code 10 et ne change rien. Sans surveillance et sans --yes, elles s'arrêtent avec le code de sortie 2 avant tout envoi.
• —Avec une connexion par navigateur, ces deux suppressions demandent aussi un code de vérification, comme le fait l'application web. Sans surveillance, personne ne peut le taper, donc la commande s'arrête avec le code de sortie 4. Lancez d'abord openemail verify et les 60 minutes suivantes n'ont besoin d'aucun code. On ne demande jamais de code à une clé API.
• —--dry-run affiche la requête qu'un changement enverrait, avec son corps, et sort avec le code 0 sans l'envoyer ni vous demander de confirmer.
• —Une liste lit une page : --limit prend de 1 à 100 et le serveur en envoie 25 quand elle est omise, et --cursor prend le nextCursor de la page précédente. --all lit chaque page, --max <n> s'arrête après autant d'éléments, et --ndjson, ou --all dans un pipe, affiche un objet JSON par ligne. Avec --json, domains list et list-addresses affichent un seul document { items, hasMore, nextCursor }.
• —Une clé ou une connexion limitée à certains domaines ou adresses voit quand même chaque domaine et chaque adresse. Elle ne peut pas ajouter de domaine, et toute autre modification exige le domaine entier parmi les domaines qu'elle détient, sinon l'appel est refusé avec 422 capability_unsupported.
• —Un refus sort avec le code de son statut : 4 pour un 403, comme domain_allowance_reached quand le forfait n'autorise plus de domaines, 5 pour un 404, 6 pour un 409, comme domain_already_added ou domain_claimed, et 7 pour un 422, comme invalid_tracking_host ou workspace_limit_reached.
• —Le dernier domaine d'un espace de travail ne peut pas être retiré depuis la CLI. C'est un 409 last_domain, car le retirer supprime toute la boîte mail, ce que l'application web fait d'abord confirmer. Un domaine qui contient des adresses de compte réservées donne un 409 domain_holds_reserved_addresses.
• —domains create et les deux suppressions ne sont jamais relancées après une panne réseau. Un 409 domain_already_added, ou un 404 lors de votre propre second essai après une réponse perdue, signifie que le premier a fonctionné. verify, update, create-address et update-address sont relancées d'elles-mêmes, puisque les envoyer deux fois laisse le même résultat.