Diffusions

const draft = {  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' },} const reach = await openemail.broadcasts.preview(draft)console.log(reach.recipients, reach.unsubscribed, reach.suppressed) const broadcast = await openemail.broadcasts.send(draft) let latest = await openemail.broadcasts.get(broadcast.id)while (['scheduled', 'queued', 'sending'].includes(latest.status)) {  await new Promise((resolve) => setTimeout(resolve, 5_000))  latest = await openemail.broadcasts.get(broadcast.id)} for await (const copy of openemail.emails.iterate({ broadcastId: broadcast.id })) {  console.log(copy.id, copy.status)} const later = await openemail.broadcasts.send({ ...draft, scheduledAt: 'P1D' })await openemail.broadcasts.cancel(later.id) const history = await openemail.broadcasts.list({ audienceId: draft.audienceIds[0] })console.log(latest.status, latest.counts.sent, history.items.length)

Une diffusion envoie un message à tous les membres d'une ou plusieurs audiences, sous forme de copie distincte pour chaque personne. 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. emails.list({ broadcastId }) les liste. Les copies ne sont pas classées dans le dossier Envoyés, car la diffusion en fait foi.

send se résout aussitôt avec la diffusion queued, ou scheduled si vous passez scheduledAt, et l'envoi se poursuit en arrière-plan. send exige emails:send et audiences:read, preview exige audiences:read, list, listAll, iterate et get exigent emails:read, et cancel exige emails:send.

subject, html et text sont remplis pour chaque personne à partir de son contact. {{firstName}} est le premier mot du nom du contact, {{lastName}} le reste, {{name}} le nom complet, {{email}} l'adresse à laquelle part la copie et {{unsubscribeUrl}} le lien qui la désabonne.

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, et tout autre {{…}} est laissé exactement tel qu'il est écrit.

Passez template à la place de html et text pour envoyer un modèle enregistré. Les cinq mêmes valeurs lui parviennent comme props, mais seulement les props que le modèle déclare : un modèle qui déclare firstName le reçoit, et un modèle qui ne le déclare pas n'est jamais refusé pour autant. Tout ce qui est dans template.props va à l'identique dans chaque copie.

Chaque copie porte les en-têtes de désabonnement en un clic qui permettent à un client de messagerie d'afficher son propre bouton de désabonnement, 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 avec le lien. Un modèle est envoyé exactement tel quel : mettez donc {{unsubscribeUrl}} dans le modèle.

Le désabonnement marque la personne désabonnée dans chaque audience à laquelle cette diffusion est partie, et AudienceContactResource.unsubscribedAt l'indique sur audiences.listContacts. Elle reste dans l'audience et dans le carnet d'adresses, ses autres audiences ne sont pas touchées, et le courrier qui lui est envoyé un message à la fois part toujours. La retirer de l'audience puis l'y rajouter la réabonne.

Une diffusion atteint chaque contact d'au moins une des audienceIds, une fois quel que soit le nombre d'audiences qui le contiennent. Elle ignore le contact qui s'est désabonné de chacune de ces audiences dont il fait partie, et l'adresse figurant 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 send, mais avant que l'envoi ne l'atteigne, est inclus.

preview renvoie les mêmes chiffres sans envoyer : recipients, unsubscribed et suppressed. Un send qui n'atteindrait personne lève 422 no_recipients.

get lit counts en direct depuis les copies : interrogez-le pendant qu'une diffusion part. status passe de scheduled ou queued à sending et se fixe sur sent une fois que chaque copie confiée est partie ou a échoué. Il reste sending tant que des copies attendent encore, même après que completedAt indique que la dernière personne a été atteinte. failed signifie que la diffusion entière s'est arrêtée, et lastError dit pourquoi : l'adresse from ne peut plus servir à envoyer, le modèle ne se résout plus, la formule s'est épuisée en route, l'envoi lui-même a échoué à répétition, ou pas une seule copie n'a pu être écrite.

cancel arrête une diffusion scheduled, queued ou sending. Personne d'autre n'est ajouté et chaque copie encore en attente est annulée, tandis que les copies parties ne peuvent pas être rappelées. Une fois toutes les copies parties, cancel lève 409 broadcast_not_cancellable, et annuler une diffusion déjà annulée se résout avec elle telle qu'elle est.

send, get et cancel se résolvent chacun avec l'un d'eux. list se résout avec une page d'entre eux, { items, hasMore, nextCursor }, du plus récent au plus ancien, et listAll et iterate parcourent toutes les pages. preview se résout avec un BroadcastPreviewResource contenant audienceIds, recipients, unsubscribed et suppressed.