Contactos

Un contacto es el registro que Bitelio guarda de un único destinatario de correo: un identificador único ligado a una dirección de correo.

Añadir contactos

Hay varias formas de incorporar contactos a un proyecto de Bitelio:

• Vía /v1/track — si registras un evento contra un correo que aún no está en el proyecto, el contacto se crea al vuelo (y empieza suscrito).
• Vía POST /contacts — crea o hace upsert de un contacto. Si el correo ya existe, se actualiza en lugar de rechazarse; la respuesta trae un bloque _meta: { isNew, isUpdate }, con estado 201 cuando el contacto se creó y 200 cuando se actualizó.
• Importación CSV masiva mediante POST /contacts/import — envía un CSV (≤ 5 MB) y luego sigue el job con GET /contacts/import/:jobId. email debe ser la primera columna; cada columna restante se convierte en una clave bajo data.*.
• Suscripción/baja/eliminación masiva mediante POST /contacts/bulk-subscribe, bulk-unsubscribe y bulk-delete — cada una toma como máximo 1000 IDs de contacto y devuelve un ID de job que puedes consultar en GET /contacts/bulk/:jobId.
• Añadiendo correos a un segmento estático con POST /segments/:id/members y createMissing: true, lo que crea cualquier dirección que aún no esté en el proyecto.
• A mano, desde el panel.

Datos del contacto

Se pueden adjuntar pares clave-valor arbitrarios a cualquier contacto, y esos datos alimentan luego la segmentación y la personalización de plantillas.

Tipos de datos

Para cada clave de un proyecto, Bitelio infiere el tipo a partir del primer valor no nulo que encuentra:

La inferencia de tipos ocurre una sola vez por proyecto, en la primera escritura. Así que si una clave se tipa como number, los valores de texto posteriores se siguen guardando — pero la interfaz de filtros de segmento sigue tratando la clave como number. ¿Mezclaste los tipos por accidente? La forma más limpia de arreglarlo es DELETE /contacts/fields/:field para eliminar el campo por completo, y luego reimportarlo con valores consistentes.

Valores no persistentes

Envolver un valor como { value, persistent: false } lo hace disponible para un único renderizado sin llegar a escribirlo nunca en el contacto:

{
  "email": "user@example.com",
  "data": {
    "firstName": "Ada",
    "resetCode": { "value": "ABC123", "persistent": false }
  }
}

Aquí firstName se guarda en el contacto, mientras que resetCode existe solo para este envío y se descarta después. Eso lo convierte en la herramienta adecuada para secretos efímeros — códigos de restablecimiento de contraseña, enlaces mágicos, tokens de un solo uso.

Tratamiento especial de valores

Unos pocos valores reciben un tratamiento especial cuando se crea o actualiza un contacto:

Claves reservadas

Un puñado de claves pertenecen a Bitelio y viven en el propio contacto en lugar de en data. Son legibles, pero no se pueden escribir a través de data:

Además, estas claves se eliminan silenciosamente de cualquier payload de data — incluirlas en /v1/track, POST /contacts o PATCH /contacts/:id ni las guarda ni produce un error:

id, bitelio_id, bitelio_email, unsubscribeUrl, subscribeUrl, manageUrl

Las tres últimas se generan de nuevo para cada destinatario en el momento del envío y aparecen como variables de plantilla (ver Plantillas).

Claves especiales

Estado de suscripción

Cada contacto lleva un indicador subscribed que rige qué categorías de correo le llegan. Los contactos creados vía /v1/track empiezan suscritos; con POST /contacts el indicador toma lo que envíes (por defecto false).

En las actualizaciones, omitir subscribed conserva lo que sea que tenga actualmente — la omisión y false son cosas distintas. Envía un true o false explícito siempre que quieras un cambio.

Cada vez que subscribed cambia, Bitelio registra un evento en el contacto automáticamente:

• pasa a true → un evento contact.subscribed
• pasa a false → un evento contact.unsubscribed

Esto ocurre sin importar qué causó el cambio — una edición en el panel, la página pública de cancelación, un job masivo, o una cancelación automática tras un rebote o una queja de spam. Los flujos de trabajo pueden ramificarse a partir de ambos eventos.

Cómo un contacto termina sin suscripción

Hay varios caminos hacia el estado sin suscripción:

• Manual — alguien lo activa/desactiva en el panel o mediante la API.
• Autoservicio — el contacto hace clic en un enlace de cancelación en un correo, cayendo en la página pública de cancelación alojada.
• Automático por rebote duro — un rebote permanente da de baja al contacto; los rebotes suaves dejan el estado sin cambios.
• Automático por queja — el contacto reporta tu correo como spam y su proveedor de buzón traslada la queja a Bitelio.

Correos según el estado de suscripción

Que un correo de marketing se entregue depende del indicador de suscripción; el correo transaccional siempre pasa, esté suscrito o no.

Qué sigue