Importar contactos desde CSV

Carga contactos en bloque — con sus campos personalizados — desde un archivo CSV, vía el panel o la API

Cuando transmitir contactos uno por uno mediante /v1/track no es práctico — migrar desde otra plataforma, poblar una lista nueva, sincronizar un lote grande — Bitelio te permite importarlos en bloque desde un archivo CSV.

Formato CSV

Tu archivo necesita una fila de encabezado, y email es la única columna que debe estar presente. Cualquier columna adicional se guarda en el contacto como campo personalizado en data.<columnName>.

Un archivo mínimo:

email
ada@example.com
grace@example.com
linus@example.com

Un archivo más completo con campos personalizados:

email,firstName,plan,signupDate
ada@example.com,Ada,pro,2026-01-15T00:00:00Z
grace@example.com,Grace,enterprise,2025-11-02T00:00:00Z
linus@example.com,Linus,free,2026-04-21T00:00:00Z

Con este archivo, cada contacto importado obtiene data.firstName, data.plan y data.signupDate.

Reglas y límites

Tamaño de archivo: 5 MB máximo por carga. Las listas más grandes deben dividirse en varias importaciones.
Codificación: UTF-8. Los archivos en otras codificaciones corren el riesgo de que los valores de campos personalizados salgan corruptos.
Columna de email: obligatoria y validada. Cualquier fila cuyo email esté ausente o mal formado vuelve en el reporte de errores.
Nombres de columna reservados: id, subscribed, createdAt, updatedAt y las variables de URL autogeneradas (unsubscribeUrl, etc.) se descartan silenciosamente — déjalas fuera de tu archivo.
Columnas de fecha: dales formato ISO 8601 (2026-05-06T12:00:00Z) para que Bitelio las tipe como fechas, desbloqueando los operadores de segmento within / olderThan.
Columnas booleanas: los valores true, false, yes, no (en cualquier capitalización) se convierten en booleanos y aparecen como un interruptor booleano en los filtros de segmento.
Columnas numéricas: enteros y decimales simples (42, 3.14) se convierten en números, usables con los operadores de segmento gt / lt. Los valores con ceros a la izquierda (01234), un prefijo +, o notación científica se mantienen como texto — esto protege a los ID, códigos postales y números de teléfono de corromperse.
Contactos existentes: cuando el email de una fila ya pertenece a un contacto, ese contacto se actualiza — las columnas del CSV se fusionan en su data. No se crea un duplicado y el resto del registro queda intacto.

Importar tu CSV

Ve a Contactos y pulsa Importar.
Selecciona el CSV. Bitelio comprueba el encabezado y te muestra una vista previa de las primeras filas.
Confirma — la importación se pone en cola y se procesa en segundo plano.
Una vez terminada, la página de Importaciones muestra el resultado, incluyendo cualquier error a nivel de fila.

Para automatización, usa la API de importación:

Paso 1 — subir el CSV

curl -X POST https://api.bitelio.com/contacts/import \
  -H "Authorization: Bearer sk_..." \
  -F "file=@contacts.csv"

La respuesta incluye un jobId:

{ "jobId": "imp_abc123", "status": "queued" }

Paso 2 — consultar el estado

curl https://api.bitelio.com/contacts/import/imp_abc123 \
  -H "Authorization: Bearer sk_..."

Sigue consultando a un intervalo de pocos segundos hasta que status marque completed o failed. La respuesta final trae los recuentos:

{
  "jobId": "imp_abc123",
  "status": "completed",
  "totalRows": 12000,
  "imported": 11985,
  "updated": 8,
  "skipped": 0,
  "errors": [
    { "row": 47,   "email": "bad@",      "reason": "invalid_email" },
    { "row": 1042, "email": "@example",  "reason": "invalid_email" }
  ]
}

imported es el número de contactos creados desde cero, mientras que updated cuenta los existentes cuyo data fue parcheado. Cada entrada en errors te da el número de fila y el motivo, así que las filas problemáticas pueden corregirse y volver a subirse.

Consejos

Contactos sin suscripción: todo contacto importado empieza suscrito. Si el CSV contiene personas que nunca aceptaron participar, configura un flujo de trabajo que filtre a quien no debas contactar, o importa primero y luego ejecuta POST /contacts/bulk-unsubscribe para que queden en el registro sin ser enviables.
Los campos personalizados aparecen en segmentos de inmediato: en el momento en que termina la importación, los segmentos dinámicos pueden filtrar sobre cualquiera de las columnas importadas.
Reimportaciones idempotentes: volver a subir el mismo CSV actualiza los contactos en su lugar en vez de duplicarlos — así que, tras corregir una columna, una nueva subida empuja el valor corregido a cada fila coincidente.

Relacionado

Campos personalizados — cómo se tipan y se usan los campos data.<column> que importas.
Operaciones masivas — bulk-subscribe, bulk-unsubscribe, bulk-delete para acciones masivas sobre contactos existentes (máximo 1000 por llamada).