Broadcasts

Campanhas de marketing enviadas a uma audiência ou segmento (`publiq.broadcasts`).

O recurso broadcasts cobre o ciclo de vida de uma campanha: criar em rascunho a partir de um template, direcionando a uma audiência ou a um segmento, consultar o status, listar o histórico e disparar (agora ou agendado).

Referência de métodos

`broadcasts.create`

broadcasts.create(params) → Promise<Broadcast>

Cria uma broadcast em rascunho a partir de um template versionado, direcionada a uma audiência inteira ou a um segmento. Nada é enviado até chamar broadcasts.send.

Parâmetros

Parâmetro	Tipo	Descrição
`fromEmail`Obrigatório	`string`	E-mail remetente. O domínio precisa estar verificado. Veja Domínios & DNS.
`templateId`Obrigatório	`string`	ID do template versionado a ser enviado. Veja Templates.
`audienceId`Opcional	`string`	Direciona para a audiência inteira. Use `audienceId` ou `segmentId` — nunca os dois. Veja Audiências.
`segmentId`Opcional	`string`	Direciona para um segmento da audiência. Use `segmentId` ou `audienceId` — nunca os dois. Veja Segmentos.

Retorna: A broadcast criada — { object: "broadcast", id, status: "draft", ... }. Guarde o id para revisar e enviar depois.

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"

É preciso escolher exatamente um alvo: audienceId ou segmentId. Passar os dois (ou nenhum) → 400 validation_error. Toda broadcast usa um template salvo. Veja Audiências, Segmentos e Templates.

`broadcasts.get`

broadcasts.get(id) → Promise<Broadcast>

Busca os detalhes de uma broadcast pelo id: status atual e, se agendada, o scheduled_at.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da broadcast (retornado por `broadcasts.create`).

Retorna: A broadcast com seu status e, quando agendada, scheduled_at. 404 se não existir na organização.

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

`broadcasts.list`

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

Lista as broadcasts da organização, da mais recente à mais antiga, com paginação por cursor.

Parâmetros

Parâmetro	Tipo	Descrição
`limit`Opcional	`number`	Itens por página (padrão 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` do último item da página anterior.

Retorna: Envelope de lista { object: "list", data: Broadcast[] }. Use o id do último item como after na próxima chamada.

const { data } = await publiq.broadcasts.list({ limit: 50 });
// next page:
const next = await publiq.broadcasts.list({ after: data[data.length - 1].id });

A listagem é paginada por cursor: itere passando o id do último item em after até data vir vazio. Veja Erros & paginação.

`broadcasts.send`

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

Dispara uma broadcast em rascunho. Sem scheduledAt, o envio começa imediatamente; com scheduledAt, agenda para um instante futuro em UTC.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID da broadcast a enviar (parâmetro de caminho).
`scheduledAt`Opcional	`string`	Instante ISO-8601 em UTC, no futuro, para agendar o envio. Omita para enviar imediatamente.

Retorna: A broadcast com status: "sending" (envio imediato) ou status: "scheduled" (agendado).

// 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' });

Criar e enviar são duas etapas (criar → revisar → enviar), o que permite agendar antes de disparar. Destinatários suprimidos são pulados automaticamente. Veja Supressões.

Os exemplos mostram Node, Python e PHP. No Python os métodos são snake_case (ex.: cancel_run, from_spec) e recebem um dict; no PHP são camelCase e recebem um array associativo. As chaves do corpo são sempre camelCase (templateKey, firstName, scheduledAt) — o retorno da API vem em snake_case.