Envíos masivos

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']))

Un envío masivo manda un mensaje a todos los de una o más audiencias, como copia aparte para cada persona. Cada copia tiene exactamente un destinatario y ni cc ni bcc, así que nadie ve a quién más se envió, y cada copia es un correo normal con su propio id msg_, eventos, seguimiento y webhooks. list_recipients las lista con lo que pasó con cada una. Las copias no se archivan en la carpeta Enviados, porque el envío masivo es el registro.

send devuelve enseguida el envío masivo en queued, o scheduled si pasas scheduledAt, y el envío sigue en segundo plano. send necesita emails:send y audiences:read, preview necesita audiences:read, list, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats y analytics necesitan emails:read, y cancel necesita emails:send.

subject, html y text se rellenan para cada persona a partir de su contacto. {{firstName}} es la primera palabra del nombre del contacto, {{lastName}} el resto, {{name}} el nombre completo, {{email}} la dirección a la que va la copia y {{unsubscribeUrl}} el enlace que la da de baja.

Cada campo admite un valor de reserva tras una barra, que se usa cuando el contacto no tiene valor para él, así que {{firstName|there}} se convierte en "there" para un contacto guardado sin nombre. Los valores se escapan en html, y cualquier otro {{…}} se deja tal como está escrito.

Pasa template en lugar de html y text para enviar una plantilla guardada. Los mismos cinco valores le llegan como props, pero solo los props que declara la plantilla, así que una plantilla que declara firstName lo recibe y una que no lo declara nunca se rechaza por ello. Todo lo que hay en template.props va igual a todas las copias.

Cada copia lleva las cabeceras de baja con un clic que permiten a un cliente de correo mostrar su propio botón de baja, algo que los grandes proveedores de buzones exigen al correo masivo. Un cuerpo html o text que no coloca {{unsubscribeUrl}} por sí mismo recibe un pie de una línea con el enlace. Una plantilla se envía exactamente como es, así que pon {{unsubscribeUrl}} en la plantilla.

Darse de baja marca a la persona como dada de baja en todas las audiencias a las que fue ese envío masivo, y AudienceContactResource.unsubscribedAt lo muestra en audiences.list_contacts. Sigue en la audiencia y en la agenda, sus otras audiencias no se tocan y el correo que se le envía de uno en uno sigue saliendo. Sacarla de la audiencia y volver a añadirla la deja suscrita de nuevo.

Un envío masivo llega a todo contacto de al menos una de las audienceIds, una vez aunque esté en varias. Omite al contacto que se dio de baja de todas esas audiencias en las que está, y a una dirección de la lista de supresión tras un rebote o una queja, o porque alguien la añadió. Un contacto añadido a una de las audiencias después de send, pero antes de que el envío le llegue, sí lo recibe.

preview devuelve las mismas cifras sin enviar: recipients, unsubscribed y suppressed. Un send que no llegaría a nadie lanza 422 no_recipients.

get lee counts en vivo de las copias, así que consúltalo mientras un envío masivo sale. status pasa de scheduled o queued a sending y se queda en sent cuando cada copia entregada ha salido o ha fallado. Sigue en sending mientras aún hay copias esperando, aunque completedAt ya diga que se alcanzó a la última persona. failed significa que todo el envío masivo se detuvo, y lastError dice por qué: ya no se puede enviar desde la dirección from, la plantilla dejó de resolverse, el plan se agotó a mitad, el propio envío falló una y otra vez, o no se pudo escribir ni una sola copia.

cancel detiene un envío masivo que está scheduled, queued o sending. No se añade a nadie más y se cancela cada copia que aún espera, mientras que las copias que salieron no se pueden recuperar. Cuando todas las copias han salido, cancel lanza 409 broadcast_not_cancellable, y cancelar uno ya cancelado lo devuelve tal como está.

list_recipients devuelve una página de las personas a las que fue un envío masivo, una fila por copia, ordenadas por dirección, como un diccionario con items, hasMore y nextCursor. list_all_recipients recorre todas las páginas en una sola lista e iterate_recipients entrega una copia cada vez, pidiendo la página siguiente solo cuando el bucle la necesita. limit va de 1 a 200 y por defecto es 50, y un cursor se vuelve a enviar con los mismos filter y q.

BROADCAST_RECIPIENT_FILTERS nombra cada filtro, y q busca en la dirección y el nombre, sin distinguir mayúsculas. Las aperturas y los clics excluyen los proxies de imágenes y los escáneres de enlaces, y se quedan en 0 cuando el envío masivo salió con el seguimiento desactivado.

get_recipient(id, email_id) devuelve una copia: la misma fila, más subject, html y text exactamente como los recibió esa persona, con los campos de combinación rellenados y su propio enlace de baja. El HTML es el de antes de añadir el seguimiento de aperturas y clics. Un email_id que no es una copia de este envío masivo lanza 404 recipient_not_found, y un envío masivo desconocido lanza 404 broadcast_not_found.

stats devuelve los totales y una serie. totals cuenta las copias sent, delivered, bounced, complained y failed, con pending para las que aún esperan, y las personas que opened, clicked y unsubscribed, con opens y clicks como recuentos de eventos. series es dispersa y va de la más antigua a la más reciente, un intervalo por grain (minute, hour o day, por defecto hour) en el que pasó algo, cortado en offset_minutes al este de UTC. Cuenta a cada persona una vez, la primera vez que le pasó, así que suma los totales.

get y cancel devuelven uno de estos cada uno, y send devuelve un SentBroadcastResource, los mismos campos más replayed, que es True cuando la respuesta es el envío masivo que creó una llamada anterior con la misma clave de idempotencia. list devuelve una página de ellos, un diccionario con items, hasMore y nextCursor, el más nuevo primero, y list_all e iterate recorren todas las páginas. preview devuelve un BroadcastPreviewResource con audienceIds, recipients, unsubscribed y suppressed. list_recipients devuelve una página de filas BroadcastRecipientResource, get_recipient un BroadcastRecipientContentResource y stats un BroadcastStatsResource.

Cada fila de list_recipients, list_all_recipients e iterate_recipients. BroadcastRecipientContentResource, de get_recipient, añade subject, html y text.

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