Importar y exportar contactos

Usa el asistente de importación para traer contactos desde una hoja de cálculo, y la exportación para descargar los contactos que coinciden con tus filtros actuales. Esta página también explica las acciones masivas y el endpoint de exportación de la API, para hacer lo mismo desde el código.

Antes de empezar

• Crea los campos personalizados que quieras rellenar desde el archivo. El asistente solo puede asignar columnas a campos que ya existen.
• Crea las listas de contactos a las que quieras que se unan los contactos. Las importaciones cuentan para el límite de suscriptores de cada lista.
• Importa solo a personas que hayan aceptado recibir tus comunicaciones. Las revisiones del acceso de producción preguntan cómo consigues a tus suscriptores. Consulta Acceso de producción (verificación del espacio de trabajo).

Preparar el archivo

El asistente lee archivos .csv, .xlsx y .xls con hasta 2500 contactos por archivo. Divide las listas más grandes en varios archivos.

email,first_name,last_name,company,birthday
ada@example.com,Ada,Lovelace,Acme,1990-04-12
grace@example.com,Grace,Hopper,Acme,1906-12-09
alan@example.com,Alan,Turing,,

Consejos para una importación limpia:

• Pon un contacto en cada fila y los nombres de las columnas en la primera fila. De los archivos de Excel solo se lee la primera hoja.
• Nombra las columnas como tus campos para que el asistente las asigne por ti. El encabezado de una columna se asigna automáticamente cuando coincide con el nombre o la clave de un campo, sin distinguir mayúsculas y minúsculas, por ejemplo email, First name, first_name o la clave de un campo personalizado como company.
• Guarda los archivos CSV en UTF-8 para que los nombres con tildes se importen correctamente.
• Escribe las fechas como YYYY-MM-DD. Las celdas de fecha de los archivos de Excel también funcionan. Los demás formatos de fecha se rechazan.
• Comprueba las direcciones. Una sola dirección de email no válida detiene toda la importación con un error que indica la fila, por ejemplo «Contact #12 has an invalid email address.». Las filas con la celda de email vacía se omiten.
• Los valores de selección múltiple se importan como un único valor de texto. Para guardar varias opciones como lista, establécelas con la API.

Importar contactos

1. Abre el asistente. Ve a Email Marketing›Contacts y selecciona Import.

2. Elige el archivo. En CSV File, selecciona tu archivo. Deja marcada File has header si la primera fila contiene los nombres de las columnas. El asistente muestra las primeras filas y el número total de filas, con un aviso si el archivo tiene más de 2500 filas. Selecciona Continue.

3. Asigna las columnas. Para cada columna, elige el campo del contacto que rellena: Email, First name, Last name, uno de tus campos personalizados, o Exclude para omitirla. Debes asignar una columna a Email. Cada fila muestra valores de ejemplo para que puedas comprobar la asignación.

4. Elige las listas. En Audiences, elige las listas de contactos a las que deben unirse los contactos, o déjalo vacío para importar los contactos sin añadirlos a ninguna lista. Selecciona Continue.

5. Revisa e importa. La vista previa muestra el archivo, el número de contactos, las listas, la asignación de columnas y los 10 primeros contactos tal como se guardarán. Selecciona Import.

Emailit valida primero todo el archivo. Si hay algún problema, como una dirección no válida, un campo personalizado desconocido o una lista que está llena, no se importa nada y se enumeran los errores para que puedas corregir el archivo. Si no, la importación se ejecuta en segundo plano en lotes de 500. Actualiza la página Contacts al cabo de un momento para ver los contactos nuevos.

Qué ocurre con los contactos existentes

Los contactos se identifican por su dirección de email, sin distinguir mayúsculas y minúsculas.

Algunas cosas más que debes saber:

• La lista de asignación incluye Unsubscribed, pero la importación no lo aplica. Para marcar como dadas de baja a las personas importadas, selecciónalas después en la página Contacts y usa la acción masiva Unsubscribe.
• Las importaciones no envían eventos de webhook contact.* ni subscriber.*, y no inician automatizaciones como Added to audience.
• Si una lista fuera a superar su límite de suscriptores, la importación se rechaza con el límite en el mensaje, por ejemplo «Pay as you go includes 10,000 subscribers per audience.». Consulta Listas de contactos.

Exportar contactos

1. Acota la lista. En Email Marketing›Contacts, usa el buscador y Filter para mostrar los contactos que quieras. Sin búsqueda ni filtros, la exportación incluye todos los contactos.

2. Exporta. Selecciona Export y elige CSV o XLSX. Tu navegador descarga contacts.csv o contacts.xlsx.

Una exportación puede incluir hasta 10.000 contactos. Si coinciden más contactos, la exportación falla, así que añade filtros, como una lista o un intervalo de fechas de creación, y exporta por partes.

El archivo tiene una fila por contacto y estas columnas:

Usar la API

La API no permite importar archivos. Para añadir muchos contactos desde el código, llama a Crear un contacto para cada uno, o a Añadir un suscriptor para crear el contacto y su pertenencia a la lista en una sola llamada.

Acciones masivas

POST /v2/contacts/bulk ejecuta una acción sobre un máximo de 100 contactos, indicados por su ID con_:

curl https://api.emailit.com/v2/contacts/bulk \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_to_audience",
    "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"],
    "audience_id": "aud_5hJ2kL8mNp4Qr"
  }'

{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"]
}

La petición falla por completo si ids tiene más de 100 elementos (400) o si algún contacto o la lista no existen (404, con los ID desconocidos en missing). Para procesar más contactos, recorre las páginas de Listar contactos y envía lotes de 100.

Exportación

GET /v2/contacts/export devuelve el mismo archivo que el panel. Establece format en csv (el valor por defecto) o xlsx, y añade los filtros, la búsqueda y el orden de Listar contactos que necesites:

curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_5hJ2kL8mNp4Qr&unsubscribed=false" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv

Si coinciden más de 10.000 contactos, el endpoint devuelve 422 con «Export is limited to 10000 contacts. Narrow your filters and try again.»

Ver también