Envoyer aux audiences

Envoie un message à tous les membres d'une ou plusieurs audiences, sous forme de copie distincte pour chaque personne et personnalisée à partir de chaque contact. Chaque copie a exactement un destinataire et ni cc ni bcc, si bien que personne ne voit à qui d'autre elle est partie, et chaque copie est un e-mail ordinaire avec son propre identifiant msg_, ses événements, son suivi et ses webhooks. L'appel répond 202 tout de suite et l'envoi se poursuit en arrière-plan : suivez-le avec GET /broadcasts/{id}.

Exige emails:send et audiences:read. audienceIds contient de 1 à 10 identifiants. Le corps vient de html et/ou text, ou d'un template enregistré, jamais des deux, et subject est obligatoire sauf si le modèle le fournit.

curl -X POST "$OE/broadcasts" -H "$AUTH" -H 'content-type: application/json' -d '{  "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>",  "text": "Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}",  "tags": { "campaign": "release-2026-09" },  "scheduledAt": "PT2H"}'

{  "object": "broadcast",  "id": "brd_5a8c1e3f7b2d94a06c8e1f3b",  "status": "scheduled",  "mode": "live",  "source": "api",  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "counts": {    "recipients": 412,    "created": 0,    "skipped": 0,    "failedToQueue": 0,    "queued": 0,    "sending": 0,    "sent": 0,    "failed": 0,    "cancelled": 0  },  "lastError": null,  "scheduledAt": "2026-09-23T14:00:00.000Z",  "startedAt": null,  "completedAt": null,  "cancelledAt": null,  "createdAt": "2026-09-23T12:00:00.000Z",  "updatedAt": "2026-09-23T12:00:00.000Z",  "replayed": false}

Chaque contact d'au moins une des audiences, compté une fois quel que soit le nombre d'audiences qui le contiennent. Deux sortes de contacts sont exclues : celui qui s'est désabonné de chacune des audiences choisies dont il fait partie, et celui dont l'adresse figure sur la liste de suppression après un rebond ou une plainte, ou parce que quelqu'un l'y a ajoutée. Un contact ajouté à l'une des audiences après l'appel, mais avant que l'envoi ne l'atteigne, est inclus.

L'envoi parcourt les audiences 50 personnes à la fois et confie chaque copie au même circuit que POST /emails, si bien que chaque copie est réessayée, suivie et rapportée comme n'importe quel autre message. POST /broadcasts/preview renvoie le nombre dont partirait cet appel, sans rien envoyer.

subject, html et text sont remplis pour chaque personne. Chaque champ accepte une valeur de repli après une barre, utilisée quand le contact n'a pas de valeur pour lui : {{firstName|there}} devient donc "there" pour un contact enregistré sans nom. Les valeurs sont échappées dans html, les espaces entre les accolades sont permis, et tout autre {{…}} est laissé exactement tel qu'il est écrit.

Avec template à la place d'un corps, les cinq mêmes valeurs sont transmises comme props, mais seulement les props que le modèle déclare. Un modèle qui déclare firstName le reçoit, et un prop qu'il ne déclare pas n'est jamais envoyé, si bien que les copies n'échouent jamais sur un prop inconnu. Tout ce que vous mettez dans template.props va à l'identique dans chaque copie.

Chaque copie porte List-Unsubscribe et List-Unsubscribe-Post: List-Unsubscribe=One-Click. C'est ce qui permet à un client de messagerie d'afficher son propre bouton de désabonnement, et ce que les grands fournisseurs de boîtes exigent du courrier en masse.

Un corps html ou text qui ne place pas {{unsubscribeUrl}} lui-même reçoit un pied de page d'une ligne : "You are receiving this because you are on this mailing list. Unsubscribe". Un modèle est envoyé exactement tel quel : mettez donc {{unsubscribeUrl}} dans le modèle.

Le lien ouvre une page avec un bouton Se désabonner, si bien qu'un analyseur de liens qui le récupère ne désabonne personne, tandis que la requête en un clic d'un client de messagerie désabonne immédiatement. Dans les deux cas, la personne est marquée désabonnée dans chaque audience à laquelle cette diffusion est partie, ce qui apparaît comme unsubscribedAt sur GET /audiences/{id}/contacts. Ses autres audiences, son contact et le courrier qui lui est envoyé un message à la fois ne sont pas touchés.