# Importar y exportar contactos

> Importa contactos desde un archivo CSV o Excel con el asistente de importación, exporta los contactos filtrados a CSV o XLSX, y ejecuta acciones masivas y exportaciones con la API.

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](/es/docs/contacts/custom-fields/) que quieras rellenar desde el archivo. El asistente solo puede asignar columnas a campos que ya existen.
- Crea las [listas de contactos](/es/docs/audiences/) 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)](/es/docs/workspaces/production-access/).

## 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.

```csv title="contacts.csv"
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.

| Caso | Resultado |
| --- | --- |
| La dirección es nueva | Se crea un contacto. |
| La dirección ya existe | Se actualiza el contacto. Los nombres solo se sobrescriben cuando el archivo tiene un valor. Los valores de campos personalizados del archivo sustituyen a los guardados, y una celda vacía en una columna asignada a un campo personalizado borra ese campo. Los demás campos personalizados se conservan. |
| La dirección aparece dos veces en el archivo | Las dos filas se aplican en orden, así que prevalece la última. |
| El contacto aún no está en la lista seleccionada | Se une a la lista como suscrito. |
| El contacto se había dado de baja de la lista seleccionada | Se vuelve a suscribir a esa lista. |

> **Las importaciones vuelven a suscribir a las personas:** Si importas un contacto en una lista de la que se dio de baja, se vuelve a suscribir. Antes de importar en una lista existente, quita de tu archivo a las personas que se dieron de baja, o importa sin elegir esa lista.

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](/es/docs/audiences/#limits).

## 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:

| Columna | Valor |
| --- | --- |
| `email` | La dirección de email del contacto. |
| `first_name`, `last_name` | El nombre y los apellidos del contacto. |
| `unsubscribed` | `true` si el estado de marketing es **Unsubscribed**; si no, `false`. |
| `audiences` | Los nombres de todas las listas a las que pertenece el contacto, separados por `; `. |
| Una columna por cada clave de campo personalizado | El valor guardado. Los valores de selección múltiple se unen con `;`. |
| `created_at`, `updated_at` | Marcas de tiempo ISO 8601. |

## Usar la API

La API no permite importar archivos. Para añadir muchos contactos desde el código, llama a [Crear un contacto](/es/docs/api-reference/contacts/create/) para cada uno, o a [Añadir un suscriptor](/es/docs/api-reference/audiences/subscribers/add/) para crear el contacto y su pertenencia a la lista en una sola llamada.

### Acciones masivas

[`POST /v2/contacts/bulk`](/es/docs/api-reference/contacts/bulk/) ejecuta una acción sobre un máximo de 100 contactos, indicados por su ID `con_`:

| `action` | Efecto | Necesita `audience_id` |
| --- | --- | --- |
| `add_to_audience` | Añade los contactos a la lista. Los contactos con `unsubscribed: true` se unen como dados de baja. | Sí |
| `remove_from_audience` | Elimina su pertenencia a la lista. | Sí |
| `unsubscribe` | Establece `unsubscribed: true` (estado de marketing **Unsubscribed**). | No |
| `resubscribe` | Establece `unsubscribed: false`. | No |
| `delete` | Elimina los contactos y sus pertenencias. | No |

```bash
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"
  }'
```

```json
{
  "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](/es/docs/api-reference/contacts/list/) y envía lotes de 100.

### Exportación

[`GET /v2/contacts/export`](/es/docs/api-reference/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](/es/docs/api-reference/contacts/list/) que necesites:

```bash
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

  - [Campos personalizados](/es/docs/contacts/custom-fields/): Define los campos a los que se asignan tus columnas.
  - [Suscriptores](/es/docs/audiences/subscribers/): Gestiona quién está en cada lista de contactos.

---
Fuente: https://emailit.com/es/docs/contacts/import-export/