Envíos masivos

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)

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. emails.list({ broadcastId }) las lista. Las copias no se archivan en la carpeta Enviados, porque el envío masivo es el registro.

send se resuelve enseguida con 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, listAll, iterate y get 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.listContacts. 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 se resuelve con él tal como está.

send, get y cancel se resuelven cada uno con uno de estos. list se resuelve con una página de ellos, { items, hasMore, nextCursor }, el más nuevo primero, y listAll e iterate recorren todas las páginas. preview se resuelve con un BroadcastPreviewResource con audienceIds, recipients, unsubscribed y suppressed.