Contatos

Gerencie contatos e seus atributos, dentro de audiências (`publiq.contacts`).

O recurso contacts representa uma pessoa dentro de uma audiência: criar, listar, atualizar atributos, importar em massa e remover. Contatos são a base para envio de broadcasts e para variáveis de template.

Referência de métodos

`contacts.create`

contacts.create(audienceId, params) → Promise<Contact>

Cria um contato dentro de uma audiência, com e-mail obrigatório e atributos opcionais.

Parâmetros

Parâmetro	Tipo	Descrição
`audienceId`Obrigatório	`string`	ID da audiência onde o contato será adicionado (parte da URL).
`email`Obrigatório	`string`	E-mail do contato.
`firstName`Opcional	`string`	Primeiro nome (máx. 200 caracteres).
`lastName`Opcional	`string`	Sobrenome (máx. 200 caracteres).
`attributes`Opcional	`object`	Atributos livres do contato (ex.: `{ plan: "pro", city: "SP" }`).

Retorna: O contato criado — { object: "contact", id, email, ... }.

const contact = await publiq.contacts.create('aud_123', {
email: 'ana@example.com',
firstName: 'Ana',
lastName: 'Silva',
attributes: { plan: 'pro', city: 'SP' },
});
console.log(contact.id); // "ct_..."

Os attributes viram automaticamente variáveis de template ({{ first_name }}, {{ plan }}) sem precisar passá-las de novo em emails.send. Veja Variáveis.

`contacts.list`

contacts.list(audienceId, { limit?, after? }) → Promise<ContactList>

Lista os contatos de uma audiência, com paginação por cursor.

Parâmetros

Parâmetro	Tipo	Descrição
`audienceId`Obrigatório	`string`	ID da audiência cujos contatos serão listados (parte da URL).
`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: Contact[] }. Use o id do último item como after na próxima chamada.

const { data } = await publiq.contacts.list('aud_123', { limit: 50 });
// next page:
const next = await publiq.contacts.list('aud_123', { 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.

`contacts.update`

contacts.update(id, params) → Promise<Contact>

Atualiza nome e/ou atributos de um contato existente. attributes faz merge raso com os valores atuais — chaves omitidas são preservadas.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do contato a atualizar.
`firstName`Opcional	`string`	Novo primeiro nome.
`lastName`Opcional	`string`	Novo sobrenome.
`attributes`Opcional	`object`	Atributos a mesclar (merge raso) com os existentes (ex.: `{ plan: "enterprise" }`).

Retorna: O contato atualizado.

const contact = await publiq.contacts.update('ct_123', {
attributes: { plan: 'enterprise' },
});
console.log(contact.attributes);

Como attributes faz merge raso, os novos atributos também ficam disponíveis de imediato como variáveis de template. Veja Variáveis.

`contacts.import`

contacts.import(audienceId, params) → Promise<ImportResult>

Importa contatos em massa (até 1000 por chamada) para uma audiência. É skip-and-continue: linhas inválidas ou duplicadas são puladas, sem falhar o lote inteiro.

Parâmetros

Parâmetro	Tipo	Descrição
`audienceId`Obrigatório	`string`	ID da audiência que receberá os contatos importados (parte da URL).
`contacts`Obrigatório	`Array<{ email, firstName?, lastName?, attributes? }>`	Lista de contatos a importar (até 1000 itens). Cada item exige `email`; `firstName`, `lastName` e `attributes` são opcionais.

Retorna: Resultado da importação com contagens — { created, skipped, invalid } (em snake_case na resposta).

const result = await publiq.contacts.import('aud_123', {
contacts: [
  { email: 'ana@example.com', firstName: 'Ana' },
  { email: 'bob@example.com', firstName: 'Bob', attributes: { plan: 'pro' } },
],
});
console.log(result.created, result.skipped, result.invalid);

Limite de 1000 contatos por chamada. O lote nunca falha por completo: linhas com e-mail inválido ou já existente são puladas — sempre confira skipped/invalid no retorno para saber o que não entrou.

`contacts.delete`

contacts.delete(id) → Promise<void>

Remove um contato permanentemente.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do contato a remover.

Retorna: Nenhum conteúdo (204).

await publiq.contacts.delete('ct_123');

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.