Publiq

Broadcasts

Campañas de marketing enviadas a una audiencia o segmento (`publiq.broadcasts`).

El recurso broadcasts cubre el ciclo de vida de una campaña: crear en borrador a partir de una plantilla, dirigiéndola a una audiencia o a un segmento, consultar el estado, listar el historial y disparar (ahora o programado).

Referencia de métodos

broadcasts.create

broadcasts.create(params) → Promise<Broadcast>

Crea una broadcast en borrador, a partir de una plantilla versionada, dirigida a una audiencia entera o a un segmento. No se envía nada hasta llamar a broadcasts.send.

Parámetros
ParámetroTipoDescripción
fromEmailObligatoriostringCorreo remitente. El dominio debe estar verificado. Ver Dominios & DNS.
templateIdObligatoriostringID de la plantilla versionada a enviar. Ver Plantillas.
audienceIdOpcionalstringDirige a la audiencia entera. Usa audienceId o segmentId — nunca ambos. Ver Audiencias.
segmentIdOpcionalstringDirige a un segmento de la audiencia. Usa segmentId o audienceId — nunca ambos. Ver Segmentos.

Devuelve: La broadcast creada — { object: "broadcast", id, status: "draft", ... }. Guarda el id para revisar y enviar después.

const broadcast = await publiq.broadcasts.create({
fromEmail: 'news@yourdomain.com',
templateId: 'tpl_summer_sale',
audienceId: 'aud_123',
});
console.log(broadcast.id, broadcast.status); // "bc_...", "draft"
Debes elegir exactamente un objetivo: audienceId o segmentId. Pasar ambos (o ninguno) → 400 validation_error. Toda broadcast usa una plantilla guardada. Ver Audiencias, Segmentos y Plantillas.

broadcasts.get

broadcasts.get(id) → Promise<Broadcast>

Obtiene los detalles de una broadcast por id: estado actual y, si está programada, scheduled_at.

Parámetros
ParámetroTipoDescripción
idObligatoriostringID de la broadcast (devuelto por broadcasts.create).

Devuelve: La broadcast con su estado y, cuando está programada, scheduled_at. 404 si no existe en la organización.

const broadcast = await publiq.broadcasts.get('bc_123');
console.log(broadcast.status); // "scheduled"

broadcasts.list

broadcasts.list({ limit?, after? }) → Promise<BroadcastList>

Lista las broadcasts de la organización, de la más reciente a la más antigua, paginado por cursor.

Parámetros
ParámetroTipoDescripción
limitOpcionalnumberÍtems por página (por defecto 20, máx. 100).
afterOpcionalstringCursor: id del último ítem de la página anterior.

Devuelve: Envoltura de lista { object: "list", data: Broadcast[] }. Usa el id del último ítem como after en la próxima llamada.

const { data } = await publiq.broadcasts.list({ limit: 50 });
// next page:
const next = await publiq.broadcasts.list({ after: data[data.length - 1].id });
El listado se pagina por cursor: itera pasando el id del último ítem en after hasta que data venga vacío. Ver Errores & paginación.

broadcasts.send

broadcasts.send(id, { scheduledAt? }) → Promise<Broadcast>

Dispara una broadcast en borrador. Sin scheduledAt, el envío comienza de inmediato; con scheduledAt, se programa para un instante futuro en UTC.

Parámetros
ParámetroTipoDescripción
idObligatoriostringID de la broadcast a enviar (parámetro de ruta).
scheduledAtOpcionalstringInstante ISO-8601 en UTC, en el futuro, para programar el envío. Omítelo para enviar de inmediato.

Devuelve: La broadcast con status: "sending" (inmediato) o status: "scheduled" (programado).

// send now
await publiq.broadcasts.send('bc_123');

// schedule for a future date
await publiq.broadcasts.send('bc_123', { scheduledAt: '2026-08-01T09:00:00Z' });
Crear y enviar son dos pasos (crear → revisar → enviar), lo que permite programar antes de despachar. Los destinatarios suprimidos se omiten automáticamente. Ver Supresiones.

Los ejemplos muestran Node, Python y PHP. En Python los métodos son snake_case (ej.: cancel_run, from_spec) y reciben un dict; en PHP son camelCase y reciben un array asociativo. Las claves del cuerpo siempre son camelCase (templateKey, firstName, scheduledAt) — las respuestas de la API vienen en snake_case.

Broadcasts — Publiq Docs