Difusões

import time from openemail import openemailfrom openemail.types import BroadcastCreate draft: BroadcastCreate = {    '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'},} reach = openemail.broadcasts.preview(draft)print(reach['recipients'], reach['unsubscribed'], reach['suppressed']) broadcast = openemail.broadcasts.send(draft) latest = openemail.broadcasts.get(broadcast['id'])while latest['status'] in ('scheduled', 'queued', 'sending'):    time.sleep(5)    latest = openemail.broadcasts.get(broadcast['id']) for copy in openemail.broadcasts.iterate_recipients(broadcast['id']):    print(copy['email'], copy['status'], copy['opens'], copy['clicks']) bounced = openemail.broadcasts.list_recipients(broadcast['id'], filter='bounced')if bounced['items']:    content = openemail.broadcasts.get_recipient(broadcast['id'], bounced['items'][0]['emailId'])    print(content['subject'], content['bouncedAt']) stats = openemail.broadcasts.stats(broadcast['id'], grain='day')print(stats['totals']['opened'], stats['totals']['clicked'], stats['totals']['unsubscribed']) lately = openemail.broadcasts.stats(broadcast['id'], days=1)print(lately['window']['opened'] if lately['window'] else None) month = openemail.broadcasts.analytics(days=30)for row in month['broadcasts']:    print(row['subject'], row['sent'], row['opened']) later = openemail.broadcasts.send({**draft, 'scheduledAt': 'P1D'})openemail.broadcasts.cancel(later['id']) history = openemail.broadcasts.list(audience_id=draft['audienceIds'][0])print(latest['status'], latest['counts']['sent'], len(history['items']))

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. list_recipients lista-as com o que aconteceu a cada uma. As cópias não são arquivadas na pasta Enviados, porque a difusão é o registo.

send devolve de imediato 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, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats e analytics 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.list_contacts. 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 devolve-a tal como está.

list_recipients devolve uma página das pessoas para quem uma difusão foi, uma linha por cópia, ordenadas por endereço, como um dicionário com items, hasMore e nextCursor. list_all_recipients percorre todas as páginas para uma única lista e iterate_recipients produz uma cópia de cada vez, indo buscar a página seguinte só quando o ciclo a pede. limit vai de 1 a 200 e é 50 por omissão, e um cursor é reenviado com os mesmos filter e q.

BROADCAST_RECIPIENT_FILTERS nomeia cada filtro, e q pesquisa o endereço e o nome, sem distinguir maiúsculas de minúsculas. As aberturas e os cliques excluem proxies de imagens e verificadores de ligações, e ficam em 0 quando a difusão saiu com o seguimento desligado.

get_recipient(id, email_id) devolve uma cópia: a mesma linha, mais subject, html e text exatamente como essa pessoa os recebeu, com os campos de fusão preenchidos e a sua própria ligação para cancelar a subscrição. O HTML é de antes de ser acrescentado o seguimento de aberturas e cliques. Um email_id que não é uma cópia desta difusão lança 404 recipient_not_found, e uma difusão desconhecida lança 404 broadcast_not_found.

stats devolve os totais e uma série. totals conta as cópias sent, delivered, bounced, complained e failed, com pending para as que ainda esperam, e as pessoas que opened, clicked e unsubscribed, com opens e clicks como contagens de eventos. series é esparsa e começa pelas mais antigas, com um intervalo por grain (minute, hour ou day, por omissão hour) em que algo aconteceu, cortado em offset_minutes a leste de UTC. Conta cada pessoa uma vez, na primeira vez que lhe aconteceu, por isso a soma bate certo com os totais.

get e cancel devolvem um destes cada um, e send devolve um SentBroadcastResource, os mesmos campos mais replayed, que é True quando a resposta é a difusão que uma chamada anterior com a mesma chave de idempotência criou. list devolve uma página deles, um dicionário com items, hasMore e nextCursor, do mais recente para o mais antigo, e list_all e iterate percorrem todas as páginas. preview devolve um BroadcastPreviewResource com audienceIds, recipients, unsubscribed e suppressed. list_recipients devolve uma página de linhas BroadcastRecipientResource, get_recipient um BroadcastRecipientContentResource e stats um BroadcastStatsResource.

Cada linha de list_recipients, list_all_recipients e iterate_recipients. BroadcastRecipientContentResource, de get_recipient, acrescenta subject, html e text.

• broadcasts.preview()Referência completa
• broadcasts.send()Referência completa
• broadcasts.list()Referência completa
• broadcasts.list_all()Referência completa
• broadcasts.iterate()Referência completa
• broadcasts.get()Referência completa
• broadcasts.list_recipients()Referência completa
• broadcasts.list_all_recipients()Referência completa
• broadcasts.iterate_recipients()Referência completa
• broadcasts.get_recipient()Referência completa
• broadcasts.stats()Referência completa
• broadcasts.analytics()Referência completa
• broadcasts.cancel()Referência completa