Contactos

Gestiona contactos y sus atributos, dentro de audiencias (`publiq.contacts`).

El recurso contacts representa una persona dentro de una audiencia: crear, listar, actualizar atributos, importar en masa y eliminar. Los contactos son la base para el envío de broadcasts y para variables de plantilla.

Referencia de métodos

`contacts.create`

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

Crea un contacto dentro de una audiencia, con correo obligatorio y atributos opcionales.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia donde se añadirá el contacto (parte de la URL).
`email`Obligatorio	`string`	Correo del contacto.
`firstName`Opcional	`string`	Primer nombre (máx. 200 caracteres).
`lastName`Opcional	`string`	Apellido (máx. 200 caracteres).
`attributes`Opcional	`object`	Atributos libres del contacto (ej.: `{ plan: "pro", city: "SP" }`).

Devuelve: El contacto creado — { 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_..."

Los attributes se convierten automáticamente en variables de plantilla ({{ first_name }}, {{ plan }}) sin necesidad de pasarlas de nuevo en emails.send. Ver Variables.

`contacts.list`

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

Lista los contactos de una audiencia, paginado por cursor.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia cuyos contactos se listarán (parte de la URL).
`limit`Opcional	`number`	Ítems por página (por defecto 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` del último ítem de la página anterior.

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

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

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.

`contacts.update`

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

Actualiza el nombre y/o los atributos de un contacto existente. attributes hace un merge superficial con los valores actuales — las claves omitidas se conservan.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID del contacto a actualizar.
`firstName`Opcional	`string`	Nuevo primer nombre.
`lastName`Opcional	`string`	Nuevo apellido.
`attributes`Opcional	`object`	Atributos a fusionar (merge superficial) con los existentes (ej.: `{ plan: "enterprise" }`).

Devuelve: El contacto actualizado.

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

Como attributes hace merge superficial, los nuevos atributos también quedan disponibles de inmediato como variables de plantilla. Ver Variables.

`contacts.import`

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

Importa contactos en masa (hasta 1000 por llamada) a una audiencia. Es skip-and-continue: las filas inválidas o duplicadas se omiten sin fallar el lote entero.

Parámetros

Parámetro	Tipo	Descripción
`audienceId`Obligatorio	`string`	ID de la audiencia que recibirá los contactos importados (parte de la URL).
`contacts`Obligatorio	`Array<{ email, firstName?, lastName?, attributes? }>`	Lista de contactos a importar (hasta 1000 ítems). Cada ítem requiere `email`; `firstName`, `lastName` y `attributes` son opcionales.

Devuelve: Resultado de la importación con conteos — { created, skipped, invalid } (en snake_case en la respuesta).

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);

Límite de 1000 contactos por llamada. El lote nunca falla por completo: las filas con correo inválido o ya existente se omiten — siempre revisa skipped/invalid en la respuesta para saber qué no entró.

`contacts.delete`

contacts.delete(id) → Promise<void>

Elimina permanentemente un contacto.

Parámetros

Parámetro	Tipo	Descripción
`id`Obligatorio	`string`	ID del contacto a eliminar.

Devuelve: Sin contenido (204).

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

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.