Contacts, audiences et diffusions

Quatre espaces de noms couvrent les personnes à qui vous écrivez. Les contacts sont le carnet d'adresses de l'espace de travail, les audiences sont des listes nommées de contacts, une diffusion envoie un message à tous les membres de certaines audiences, et la liste de suppression contient les adresses auxquelles l'espace de travail n'enverra pas. Chaque commande appelle une méthode du SDK, les pages du SDK décrivent donc les mêmes appels plus en détail.

• —Un contact n'a pas d'identifiant. Son adresse est la clé que prend chaque commande contacts, sans espaces autour et en minuscules, donc [email protected] et [email protected] sont un seul contact. Une audience a un identifiant aud_, une diffusion un identifiant brd_, et une suppression l'identifiant qu'affiche suppressions list.
• —Chaque contact fait partie de l'audience par défaut tant qu'il existe. Cette audience ne peut être ni supprimée, ni vidée, ni réduite, et builtin y vaut default.
• —Le carnet d'adresses appartient à l'espace de travail, donc chaque membre et chaque clé lisent et écrivent le même.
• —Chaque espace de noms répond aussi à son singulier, comme dans openemail contact get, et les alias habituels fonctionnent : ls, show, new, edit et rm. Dans suppressions, dont les verbes sont add et remove, new mène à add et rm à remove.

Le carnet d'adresses de l'espace de travail : les personnes à qui un membre a écrit depuis le compositeur de l'application, plus toute personne enregistrée à la main. Le courrier entrant n'ajoute personne, pas plus qu'un envoi via l'API ou la CLI.

Des listes nommées de contacts, jusqu'à 100 par espace de travail. Une adresse doit être un contact avant d'en rejoindre une, sauf via import-contacts, qui enregistre les nouvelles adresses au passage.

Un message à tous les membres de jusqu'à 10 audiences, envoyé sous forme d'une copie distincte pour chaque personne, avec les champs de fusion remplis et un lien de désabonnement. Chaque copie est un e-mail ordinaire avec son propre identifiant msg_, ses événements et ses webhooks.

Les adresses auxquelles cet espace de travail n'enverra pas : les rebonds définitifs et les plaintes, enregistrés au moment où ils surviennent, et toute adresse ajoutée à la main. Un envoi à l'une d'elles est refusé pour ce destinataire avant que rien ne parte.

La plupart des commandes ont besoin du scope de lecture ou d'écriture de leur espace de noms. Quelques-unes en demandent un autre, parce qu'elles lisent ou modifient autre chose :

• —Une clé limitée à certaines adresses ou certains domaines lit et écrit le même carnet d'adresses que toute autre clé. Elle ne voit que les diffusions envoyées depuis une adresse ou un domaine qu'elle couvre, ne reçoit que les contacts enregistrés de list-people, et se voit refuser avec 422 capability_unsupported par contacts list-threads, activity, block et unblock, ainsi que par suppressions add et remove.
• —Une connexion par navigateur d'un membre qui n'atteint que certaines adresses est refusée avec 422 capability_unsupported sur chaque commande contacts, audiences et broadcasts. suppressions add refuse une connexion par navigateur de quiconque n'est pas le propriétaire de l'espace de travail.

Construire une audience à partir d'un fichier, puis compter qui une diffusion à cette audience atteindrait. import-contacts enregistre les adresses qui ne sont pas encore des contacts, et le relancer ne crée ni n'ajoute rien en double.

[  { "email": "[email protected]", "name": "Ada Lovelace" },  { "email": "[email protected]", "name": "Grace Hopper" },  { "email": "[email protected]" }]

AUDIENCE=$(openemail audiences create --name 'Product updates' --json | jq -r .id)openemail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonopenemail broadcasts preview --audience-ids "$AUDIENCE"

Vérifier une diffusion avec --dry-run, qui affiche la requête et n'envoie rien, puis l'envoyer. La diffusion est créée tout de suite et envoyée en arrière-plan, interrogez donc get pour la suivre. Ce corps ne place pas {{unsubscribeUrl}}, donc chaque copie reçoit un pied de page de désabonnement d'une ligne.

{  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "html": "<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>",  "scheduledAt": "2026-10-01T09:00:00Z"}

openemail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(openemail broadcasts send --data @broadcast.json --yes --json | jq -r .id)openemail broadcasts get "$BROADCAST"openemail broadcasts stats "$BROADCAST" --grain day

Voir qui une diffusion n'a pas atteint. --ndjson affiche un destinataire par ligne, et --all --json un document avec toutes les pages.

openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailopenemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"openemail suppressions list --reason bounce --all --max 50

Copier les membres abonnés d'une audience dans une autre. jq transforme le flux en corps que prend add-contacts, et --data - le lit depuis stdin. --max 200 le limite aux 200 adresses qu'accepte un appel.

openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | openemail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

Supprimer chaque contact que le compositeur a relevé sur un domaine. delete-many prend jusqu'à 200 adresses par appel, donc xargs -n 200 découpe une liste plus longue. Vérifiez d'abord les lots avec --dry-run, car il n'y a pas d'annulation possible.

openemail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 openemail contacts delete-many --dry-run < leaving.txtxargs -n 200 openemail contacts delete-many --yes < leaving.txt

Cesser d'envoyer à une adresse, en autoriser une à nouveau et bloquer un expéditeur. removable indique quelles lignes suppressions remove acceptera.

openemail suppressions add --email [email protected]openemail suppressions list --q [email protected] --json | jq -r '.items[] | select(.removable) | .id'openemail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesopenemail contacts block [email protected]

Ces commandes demandent confirmation dans un terminal avant de s'exécuter :

• —--yes confirme pour vous. Sans surveillance, avec --json ou --no-input, en CI ou sans terminal, une commande qui demanderait confirmation s'arrête avec Refusing to run unattended. Pass --yes to confirm. et le code de sortie 2.
• —--dry-run affiche la requête que la commande enverrait et sort avec le code 0, sans rien demander ni rien changer.
• —Avec une connexion par navigateur, audiences delete demande d'abord un code de vérification, comme le fait l'application web. --yes ne le saute jamais, et sans surveillance la commande s'arrête avec le code de sortie 4. Lancez openemail verify au préalable, ou utilisez une clé API, à laquelle on ne demande jamais de code.
• —audiences empty ne demande jamais de code de vérification, vérifiez donc l'identifiant avant de passer --yes.

Chaque commande qui liste lit une page. Quand il en reste d'autres, passez le curseur affiché à --cursor, avec les mêmes filtres, ou lisez-les toutes :

• —--all lit chaque page et diffuse les éléments : un tableau dans un terminal, et un objet JSON par ligne quand la sortie est redirigée ou avec --ndjson.
• —--max <n> s'arrête après autant d'éléments, et implique --all.
• —--json affiche un seul document { items, hasMore, nextCursor }, --all compris.
• —Un curseur mal formé ou périmé donne un 400 invalid_cursor. Recommencez sans curseur.

• —contacts create refuse une adresse déjà dans le carnet avec 409 contact_exists, pour qu'une nouvelle tentative n'écrase jamais un nom que quelqu'un a modifié. contacts save ne refuse jamais : elle enregistre, garde ou fait revenir l'adresse, quel que soit son état.
• —contacts delete accepte aussi une adresse qui n'a jamais été vue que dans le courrier, ce qui retire cette personne de list-people. Le courrier reste. Il n'y a pas d'annulation possible : enregistrer à nouveau l'adresse crée un contact sans nom, sans notes et sans autre audience que celle par défaut.
• —L'adresse est l'identité d'un contact, donc contacts update ne peut pas la changer. Déplacer un contact, c'est un delete suivi d'un create.
• —contacts set-photo lit l'image depuis un fichier, ou depuis stdin avec -. Passez --content-type, comme image/jpeg : sans cela, l'image peut partir en application/octet-stream, que le serveur refuse avec 422 invalid_image.
• —broadcasts send --scheduled-at accepte une heure ISO 8601 comme 2026-10-01T09:00:00Z, ou une durée ISO 8601 comme PT2H ou P1D, jusqu'à 365 jours dans le futur. Les délais courts qu'accepte send --at, comme 2h, sont refusés ici.
• —Les champs de fusion fonctionnent dans --subject, --html et --text : {{firstName}}, {{lastName}}, {{name}}, {{email}} et {{unsubscribeUrl}}, chacun avec une valeur de repli après une barre verticale, comme dans {{firstName|there}}. Un corps qui ne place pas {{unsubscribeUrl}} reçoit un pied de page de désabonnement d'une ligne. Un modèle est envoyé tel quel, mettez donc le lien dans le modèle.
• —Une diffusion est vérifiée par rapport aux envois mensuels du forfait avant que quoi que ce soit ne soit écrit, et chaque copie compte comme un envoi. Une diffusion que le quota ne peut pas couvrir est refusée avec 429 send_quota_exceeded, et rien ne reste derrière.
• —Passez votre propre --idempotency-key à broadcasts send quand un script risque de relancer l'étape. La même clé répond avec la diffusion qu'elle a créée au lieu d'en envoyer une nouvelle.
• —Un contact qui se désabonne d'une diffusion reste dans l'audience avec unsubscribedAt défini, et les diffusions suivantes vers cette audience l'ignorent. audiences list-contacts --statuses unsubscribed les liste.
• —Un rebond définitif reste sur la liste de suppression. suppressions remove le refuse avec 409 suppression_not_removable, et removable l'indique à l'avance sur chaque ligne.