Difusões

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)

Uma difusão envia uma mensagem para todos em uma ou mais audiências, como cópia separada para cada pessoa. Cada cópia tem exatamente um destinatário e nem cc nem bcc, por isso ninguém vê para quem mais foi, e cada cópia é um e-mail normal com o seu próprio id msg_, eventos, seguimento e webhooks. emails.list({ broadcastId }) lista-as. As cópias não são arquivadas na pasta Enviados, porque a difusão é o registo.

send resolve de imediato com a difusão em queued, ou scheduled quando passa scheduledAt, e o envio continua em segundo plano. send precisa de emails:send e audiences:read, preview precisa de audiences:read, list, listAll, iterate e get precisam de emails:read, e cancel precisa de emails:send.

subject, html e text são preenchidos para cada pessoa a partir do seu contacto. {{firstName}} é a primeira palavra do nome do contacto, {{lastName}} o resto, {{name}} o nome completo, {{email}} o endereço para onde vai a cópia e {{unsubscribeUrl}} a ligação que lhe cancela a subscrição.

Cada campo aceita um valor alternativo depois de uma barra, usado quando o contacto não tem valor para ele, por isso {{firstName|there}} passa a "there" para um contacto guardado sem nome. Os valores são escapados em html, e qualquer outro {{…}} fica exatamente como foi escrito.

Passe template em vez de html e text para enviar um modelo guardado. Os mesmos cinco valores chegam-lhe como props, mas só as props que o modelo declara, por isso um modelo que declara firstName recebe-o e um que não o declara nunca é recusado por isso. Tudo o que está em template.props vai igual para todas as cópias.

Cada cópia leva os cabeçalhos para cancelar a subscrição com um clique, que permitem a um cliente de correio mostrar o seu próprio botão, algo que os grandes fornecedores de caixas de correio exigem ao correio em massa. Um corpo html ou text que não coloque {{unsubscribeUrl}} por si recebe um rodapé de uma linha com a ligação. Um modelo é enviado exatamente como está, por isso ponha {{unsubscribeUrl}} no modelo.

Cancelar a subscrição marca a pessoa sem subscrição em todas as audiências para onde essa difusão foi, e AudienceContactResource.unsubscribedAt mostra-o em audiences.listContacts. Continua na audiência e no livro de endereços, as outras audiências não são tocadas, e o correio que lhe é enviado uma mensagem de cada vez continua a sair. Retirá-la da audiência e voltar a adicioná-la dá-lhe subscrição de novo.

Uma difusão alcança todos os contactos de pelo menos uma das audienceIds, uma vez por mais audiências que os contenham. Ignora o contacto que cancelou a subscrição de todas essas audiências em que está, e o endereço na lista de supressão após uma devolução ou uma queixa, ou porque alguém o adicionou. Um contacto adicionado a uma das audiências depois de send, mas antes de o envio lá chegar, é incluído.

preview devolve os mesmos números sem enviar: recipients, unsubscribed e suppressed. Um send que não alcançaria ninguém lança 422 no_recipients.

get lê counts ao vivo a partir das cópias, por isso consulte-o enquanto uma difusão envia. status passa de scheduled ou queued para sending e fixa-se em sent quando cada cópia entregue saiu ou falhou. Continua sending enquanto ainda há cópias à espera, mesmo depois de completedAt dizer que a última pessoa foi alcançada. failed significa que a difusão inteira parou, e lastError diz porquê: o endereço from já não pode enviar, o modelo deixou de se resolver, o plano esgotou-se a meio, o próprio envio falhou repetidamente, ou nem uma cópia pôde ser escrita.

cancel para uma difusão que está scheduled, queued ou sending. Ninguém mais é adicionado e cada cópia ainda à espera é cancelada, enquanto as cópias que saíram não podem ser recuperadas. Quando todas as cópias saíram, cancel lança 409 broadcast_not_cancellable, e cancelar uma difusão já cancelada resolve com ela tal como está.

send, get e cancel resolvem cada um com um destes. list resolve com uma página deles, { items, hasMore, nextCursor }, do mais recente para o mais antigo, e listAll e iterate percorrem todas as páginas. preview resolve com um BroadcastPreviewResource com audienceIds, recipients, unsubscribed e suppressed.