> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contactos

> Los contactos son tus suscriptores, clientes y prospectos en Notifuse. Cada uno tiene un perfil, campos personalizados y un historial de interacción.

![Página de contactos con la lista de contactos, sus campos y las opciones de datos personalizados](https://www.notifuse.com/docs/assets/screenshots/contacts.png)

## Descripción general

Un contacto guarda el perfil, las preferencias y los datos de interacción de un suscriptor en campos predefinidos y personalizados. Puede pertenecer a varias listas de correo.

## Campos de un contacto

| Campo                                                    | Tipo                 | Descripción                                                                                                                                                                    |
| -------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `email`                                                  | Cadena               | Dirección de correo del contacto y su identificador único (**Obligatorio**)                                                                                                    |
| `external_id`                                            | Cadena               | Referencia opcional al contacto en tu propio sistema. No es único (consulta [Identidad del contacto](#contact-identity-and-upsert-behavior))                                   |
| `first_name`                                             | Cadena               | Nombre del contacto                                                                                                                                                            |
| `last_name`                                              | Cadena               | Apellido del contacto                                                                                                                                                          |
| `phone`                                                  | Cadena               | Número de teléfono                                                                                                                                                             |
| `timezone`                                               | Cadena               | Zona horaria ISO del contacto                                                                                                                                                  |
| `language`                                               | Cadena               | Idioma preferido                                                                                                                                                               |
| `job_title`                                              | Cadena               | Cargo profesional                                                                                                                                                              |
| `address_line_1`                                         | Cadena               | Dirección principal                                                                                                                                                            |
| `address_line_2`                                         | Cadena               | Dirección complementaria (piso, oficina, etc.)                                                                                                                                 |
| `country`                                                | Cadena               | País en formato ISO                                                                                                                                                            |
| `state`                                                  | Cadena               | Estado o provincia                                                                                                                                                             |
| `postcode`                                               | Cadena               | Código postal                                                                                                                                                                  |
| `custom_string_1` a `custom_string_5`                    | Cadena               | Campos de texto personalizados                                                                                                                                                 |
| `custom_number_1` a `custom_number_5`                    | Número               | Campos numéricos personalizados                                                                                                                                                |
| `custom_datetime_1` a `custom_datetime_5`                | Fecha y hora         | Campos de fecha y hora personalizados                                                                                                                                          |
| `custom_json_1` a `custom_json_5`                        | JSON                 | Campos JSON personalizados                                                                                                                                                     |
| `tracking_opens_consent`, `tracking_clicks_consent`      | Cadena               | `granted`, `denied` o `null` (desconocido): lo que el contacto eligió sobre el [seguimiento de aperturas y clics](https://www.notifuse.com/es/docs/features/email-tracking.md) |
| `tracking_consent_updated_at`, `tracking_consent_source` | Fecha y hora, Cadena | Cuándo y desde dónde cambió esa elección por última vez                                                                                                                        |

## La ficha del contacto

Al hacer clic en un contacto de la tabla, su ficha se abre encima de la página. La ficha tiene su propia dirección (la URL de la página con `?contact=` y el correo), que puedes compartir o volver a abrir. Si la abriste desde la tabla, el botón Atrás del navegador la cierra.

![La ficha de un contacto, con sus cifras clave, su cronología de actividad y los campos de su perfil](https://www.notifuse.com/docs/assets/screenshots/contact_profile.png)

- **Recorre la tabla** con las flechas de la parte superior, o con **J** (siguiente) y **K** (anterior). La ficha sigue en orden las filas de la vista desde la que la abriste y carga más cuando llegas a la última.
- **Edita un campo** haciendo clic en su valor. Los campos vacíos quedan plegados bajo un enlace al final de cada panel.
- **Cifras clave**: correos recibidos, tasas de apertura y de clics, la última actividad y, con la analítica web activada, las visitas al sitio.
- **Actividad**: la cronología del contacto, filtrada por tipo (correos, listas y segmentos, cambios de perfil, eventos, visitas web).
- **Mensajes**: los correos enviados al contacto.
- **Visitas web**: las visitas del contacto a tu sitio web, cuando la [analítica web](https://www.notifuse.com/es/docs/web-analytics/identifying-visitors.md#on-the-contact-sheet) está activada.
- **Listas y segmentos**: las suscripciones del contacto, que puedes cambiar, y los segmentos a los que pertenece.

![La parte superior de una ficha de contacto: nombre, correo y fecha de alta, y debajo los correos recibidos, la tasa de apertura, la tasa de clics, la última actividad y las visitas al sitio](https://www.notifuse.com/docs/assets/screenshots/contacts_key_figures.png)

## Gestión de contactos

### Identidad del contacto y comportamiento del upsert

La **dirección de correo es el identificador único de un contacto**: es la clave primaria en la base de datos, y todo upsert (`contacts.upsert`, `contacts.import` y el contacto incluido en `transactional.send`) busca los contactos solo por su dirección de correo:

- **Correos nuevos**: se crea un contacto nuevo
- **Correos existentes**: se actualiza el contacto existente con los campos enviados
- **Valores nulos**: poner un campo a `null` borra ese valor del contacto

`external_id` es una referencia opcional al contacto en tu propio sistema (por ejemplo, el ID de usuario de tu aplicación). Se guarda, se puede buscar y la API lo devuelve, pero **no es una clave única**:

- Nunca se usa para encontrar contactos durante un upsert.
- Notifuse no impide que varios contactos compartan el mismo `external_id`.
- Si varios contactos comparten el mismo `external_id`, `contacts.getByExternalID` devuelve solo uno de ellos (sin que esté definido cuál).

### Cambiar la dirección de correo de un contacto

Como la dirección de correo es la identidad del contacto, hacer un upsert con el mismo `external_id` y una dirección nueva **crea un segundo contacto** y deja sin cambios el correo del contacto existente. Cuando un usuario cambia su dirección de correo en tu sistema:

1. Obtén el contacto antiguo con `contacts.getByEmail` para recuperar su perfil y sus suscripciones a listas con sus estados.
2. Haz un upsert de un contacto con la dirección **nueva** y envía el perfil completo (el upsert fusiona campos, así que incluye todos los que quieras conservar, como `external_id`, los nombres y los campos personalizados).
3. Vuelve a crear las suscripciones a listas en el contacto nuevo con `lists.subscribe`.
4. Elimina el contacto con la dirección **antigua** con `contacts.delete`.

> [!WARNING]
>
> Conserva los estados de baja al volver a crear las suscripciones. Si el contacto antiguo se había dado de baja,
> había rebotado o había presentado una queja en una lista, **no** vuelvas a suscribir la nueva dirección a esa lista:
> el contacto nuevo empieza de cero, y suscribirlo de nuevo sin mirar anula en silencio una
> baja. Eso vulnera el consentimiento (RGPD / CAN-SPAM) y puede dañar tu reputación como remitente.

Ten en cuenta también:

- **El historial de mensajes y la pertenencia a segmentos** están ligados a la dirección de correo. Se quedan con la dirección antigua y no pasan al contacto nuevo.
- **Automatizaciones en curso**: eliminar el contacto antiguo lo saca de cualquier automatización que esté recorriendo, y el contacto nuevo no retoma su posición.

### Eliminar un contacto

Eliminar un contacto con `contacts.delete` elimina también sus suscripciones a listas, incluidos los estados de baja, rebote y queja, así que Notifuse deja de recordar que la dirección se dio de baja. Una importación posterior, un upsert con `subscribe_to_lists` o `lists.subscribe` vuelve a añadir la dirección como un contacto nuevo y suscrito. Para seguir respetando una baja, pon el estado del contacto en la lista como dado de baja en vez de eliminarlo.

Un enlace para darse de baja en un correo enviado antes de la eliminación sigue respondiendo con éxito, pero no guarda nada sobre la dirección.

### Suscripciones a listas

- Un contacto puede suscribirse a una o varias listas de correo
- El estado de suscripción se gestiona por lista
- La pertenencia a listas se registra mediante la relación `contact_lists`

## Motor de segmentación de contactos

![Interfaz de segmentación con filtros sobre las propiedades del contacto y condiciones basadas en la actividad](https://www.notifuse.com/docs/assets/screenshots/segment_form.png)

Notifuse segmenta los contactos según sus propiedades y su forma de interactuar. La pertenencia se calcula en segundo plano, no en tiempo real. Cuando algo llega a la cronología de un contacto (un cambio de perfil, un correo abierto, un evento personalizado), el contacto entra en una cola. Una tarea periódica va procesando esa cola, así que un cambio suele verse en los segmentos del contacto en menos de un minuto. Los segmentos con fechas relativas, como "en los últimos 30 días", también se reconstruyen cada día a las 5 de la mañana en la zona horaria del segmento.

### Crear segmentos

Los segmentos se construyen con los siguientes tipos de condiciones.

#### Condiciones sobre las propiedades del contacto

Filtra los contactos según los datos de su perfil:

- **Campos de texto**: correo, nombres, teléfono, país, idioma, zona horaria, dirección, cargo, consentimiento de seguimiento y su origen, campos de texto personalizados. Operadores: está definido, no está definido, es igual a, no es igual a, contiene (uno o varios valores), no contiene.
- **Campos numéricos**: campos numéricos personalizados. Operadores: está definido, no está definido, es igual a, no es igual a, mayor o menor que (o igual a).
- **Campos de fecha**: fechas de creación y de actualización, fecha del consentimiento de seguimiento, campos de fecha personalizados. Operadores: está definido, no está definido, antes de, después de, entre, no entre, en los últimos N días, no en los últimos N días (que también incluye los contactos cuya fecha nunca se definió).
- **Campos JSON**: campos JSON personalizados, leídos en una ruta de claves e índices de array, como texto, número o fecha. El texto añade "está en el array"; una fecha ofrece antes de, después de, es igual a y los operadores de los últimos N días.

Todos los filtros de una misma condición deben cumplirse. Cada filtro se edita en su sitio, y no se puede confirmar una condición mientras uno de sus filtros esté incompleto.

#### Condiciones sobre objetivos

Crea segmentos RFM (Recencia, Frecuencia, Monetario) con los [eventos personalizados y objetivos](https://www.notifuse.com/es/docs/features/custom-events.md):

- **Monetario**: gasto total, valor medio del pedido
- **Frecuencia**: número de compras, número de eventos
- **Recencia**: actividad dentro de un periodo

Ejemplos de segmentos: clientes VIP (gasto de 1000 $ o más), compradores recurrentes (3 pedidos o más), clientes en riesgo (sin compras en 90 días).

#### Condiciones sobre la actividad

Selecciona contactos según cómo interactúan con tus correos y tu sitio web:

- **Email enviado**: se envió un correo al contacto
- **Correo abierto**: el contacto abrió un correo
- **Clic en el correo**: el contacto hizo clic en un enlace de un correo, opcionalmente uno cuya dirección contiene cierto texto. En los correos enviados a partir de la versión 42.2, el contacto entra en el segmento en cuanto hace clic en ese enlace, aunque no sea el primer enlace que pulsó en el correo
- **Correo rebotado**: el correo rebotó para este contacto
- **Queja del correo**: el contacto marcó un correo como spam
- **Se dio de baja desde un correo**: el contacto se dio de baja a través de un correo
- **Ver la página web**: el contacto vio una página de tu sitio web; se puede filtrar por ruta, tiempo en la página y profundidad de desplazamiento
- **Visitar el sitio web**: el contacto hizo una visita; se puede filtrar por página de entrada y de salida, páginas vistas, duración, canal, campaña, dispositivo y país

Las dos condiciones de sitio web requieren [Analíticas web](https://www.notifuse.com/es/docs/web-analytics/setup.md) y un visitante que haya sido [identificado](https://www.notifuse.com/es/docs/web-analytics/identifying-visitors.md).

Las condiciones de actividad admiten parámetros adicionales:

- **Frecuencia**: al menos, como máximo o exactamente un número de veces
- **Periodo**: en cualquier momento, entre dos fechas, antes o después de una fecha, o en los últimos N días
- **Plantilla y envío masivo** (toda actividad de correo, Email enviado incluido): cuenta solo los correos enviados con una plantilla o por un envío masivo concreto
- **Enlace clicado** (Clic en el correo): cuenta solo los clics en enlaces que contienen cierto texto, como `/pricing`

### Lógica de las condiciones

Los segmentos combinan condiciones con lógica AND u OR:

- **Todas las condiciones siguientes**: el contacto debe cumplir todas las condiciones (lógica AND)
- **Al menos una de las condiciones siguientes**: el contacto debe cumplir una condición o más (lógica OR)

Las condiciones se pueden agrupar, cada grupo con su propio "todas" o "al menos una", y los grupos se pueden anidar.

### Casos de uso

Situaciones habituales:

- **Clientes VIP**: clientes que gastan mucho y compran varias veces (usa condiciones sobre objetivos)
- **Recuperación de la interacción**: vuelve a captar a los suscriptores inactivos que no han abierto correos en 90 días
- **Clientes en riesgo**: compradores antes activos sin compras recientes
- **Segmentación geográfica**: envía campañas regionales según el país o el estado
- **Disparadores de comportamiento**: selecciona a los usuarios que hicieron clic en enlaces de productos concretos

### Detalles técnicos

El motor de segmentación lee la cronología del contacto introducida en la versión 7.0, que registra cada interacción del contacto, incluidos los mensajes, los eventos de webhook y los cambios de perfil. Cada evento de actividad tiene un `kind` (por ejemplo, `email.opened`, `email.clicked`, `web.pageview`) al que pueden apuntar las condiciones. Las marcas de tiempo se guardan en UTC, y las condiciones basadas en fechas pueden evaluarlas en la zona horaria que indiques.

### Permisos de los segmentos

Los segmentos tienen su propio permiso, **Segmentos**: el nivel **Leído** lista los segmentos y abre uno, y el nivel **Escribir** los crea, edita, elimina y reconstruye, y ejecuta, reinicia o elimina sus tareas de construcción en segundo plano.

Previsualizar un segmento mientras lo construyes y listar los contactos que coinciden con él en ese momento también requieren el permiso de lectura de **Contactos**, porque ambas cosas responden a preguntas sobre tus contactos y no sobre la definición del segmento. Un miembro que solo tiene lectura en Segmentos puede trabajar con las definiciones de los segmentos, pero no puede ver quién está en ellos.

La previsualización acepta cualquier definición, no solo un segmento guardado, así que alguien con lectura en Segmentos y en Contactos puede hacer preguntas de recuento sobre cualquier atributo de contacto, pertenencia a listas, evento personalizado o entrada de la cronología, un recuento cada vez.

## Importar contactos desde un CSV

![Importación de CSV: cada columna del archivo con sus valores de ejemplo y el campo de contacto al que se importa](https://www.notifuse.com/docs/assets/screenshots/import_csv.png)

La importación se hace en tres pasos: suelta un archivo CSV, asigna sus columnas y sigue la importación.

### Asignar las columnas

La primera fila del archivo contiene los nombres de las columnas, y una columna debe contener direcciones de correo. Cada columna aparece con valores de ejemplo de las primeras filas. Una columna con el nombre de un campo de contacto, por clave (`first_name`) o por etiqueta (`First Name`), se asigna sola; puedes asignar cualquier columna a un campo estándar o personalizado, o dejarla en **No importar**. Cada campo admite una sola columna, y la importación sigue desactivada hasta que una columna esté asignada al correo.

Las columnas de consentimiento admiten `granted` o `denied`, y los campos JSON personalizados admiten JSON válido. Un contacto que ya existe en el espacio de trabajo se encuentra por su correo y se actualiza: cada campo que trae la fila sobrescribe el valor guardado.

### Añadir a listas

Cada contacto importado se suscribe a las listas que elijas, una o varias.

### Seguir la importación

Las filas se envían en lotes de 100, y la importación cuenta los contactos creados, actualizados y fallidos. Cada fila fallida aparece con su línea en tu archivo y el motivo; **Descargar las filas con error** te da esas filas con una columna `error`, para que las corrijas y las vuelvas a importar.

La importación se ejecuta en tu navegador. Puedes pausarla o detenerla, y cerrar el panel o la pestaña también la detiene. Su progreso se guarda en este navegador durante 7 días: el paso Archivo lista las importaciones sin terminar, y si vuelves a soltar el mismo archivo te ofrece retomarla desde la fila donde se detuvo, con la misma asignación de columnas y las mismas listas.

### Permisos de la importación

Importar requiere el permiso de escritura de **Contactos**. Elegir una o varias listas de correo durante la importación requiere también escritura en **Listas**.

Cada campo que trae una fila sobrescribe el valor guardado en el contacto correspondiente, así que una sola importación puede reescribir toda tu base de contactos. Ten esto en cuenta al conceder escritura en Contactos.

## Actualización masiva desde un CSV

**Actualización masiva (CSV)**, en el menú ⋯ de la página Contactos, aplica una acción a cada contacto cuya dirección está en una columna de un CSV:

- **Dar de baja de una lista** pone en dado de baja la suscripción de los contactos a esa lista. Siguen en el espacio de trabajo y pueden volver a suscribirse. Un contacto que no está en la lista se omite.
- **Eliminar contactos** elimina los contactos y su historial del espacio de trabajo. No se puede deshacer.

![Actualización masiva desde un CSV: Dar de baja de una lista elegido con la lista Newsletter, el archivo y su columna de correo, las primeras direcciones y un resumen de 49 filas, 2 duplicados eliminados y 1 sin correo válido, lo que deja 46 contactos](https://www.notifuse.com/docs/assets/screenshots/bulk_update_csv.png)

Se elige por ti la columna cuyo nombre contiene "mail", y puedes escoger otra. Las direcciones se pasan a minúsculas y cada una se procesa una sola vez. Antes de empezar, el resumen cuenta las filas del archivo, los duplicados eliminados y las filas sin una dirección válida.

La actualización se ejecuta en tu navegador, un contacto cada vez. Cada dirección aparece como hecha, omitida o fallida; puedes descargar los resultados en CSV y reintentar los fallos. Una actualización detenida se puede retomar con el mismo archivo.

Dar de baja requiere el permiso de escritura de **Listas** además del de **Contactos**; eliminar requiere escritura en **Contactos**.

## Permisos

Los datos de contacto dependen del permiso **Contactos**:

- **Leído** cubre los registros de contacto y sus perfiles completos, la cronología del contacto y los eventos personalizados registrados en los contactos. Junto con el permiso correspondiente de Listas o Segmentos, también es necesario para listar las direcciones de una lista o de un segmento. Hace falta asimismo para indicar `cc` o `bcc` en un envío transaccional.
- **Escribir** cubre crear y actualizar contactos, **eliminarlos** de forma definitiva, **sobrescribirlos en bloque** con una importación por CSV o por la API, y registrar eventos personalizados. Cambiar el estado de suscripción de un contacto en una lista requiere también escritura en Listas.

En la ficha del contacto, cada parte necesita su propio permiso: **Mensajes** necesita lectura en Historial de mensajes, **Visitas web** necesita lectura en Analítica web (con la analítica web activada), y los paneles de listas y segmentos necesitan lectura en Listas y en Segmentos. Sin escritura en Contactos, sus campos no se pueden editar.

Tres permisos llegan a los datos de contacto sin escritura en Contactos. Revísalos antes de conceder cualquiera de ellos:

- **Escritura en Listas**, por sí sola, crea o sobrescribe el registro completo de un contacto: `/api/lists.subscribe` escribe cada campo que trae la petición y puede suscribir a alguien a una lista que no es pública.
- **Escritura en Automatizaciones** envía el registro completo del contacto a cualquier URL que indique un nodo webhook, y nada comprueba los permisos mientras se ejecuta una automatización.
- **Escritura en Transaccional** crea el contacto destinatario como parte del envío. Sin escritura en Contactos, solo se guarda la dirección de correo y nunca se modifica un contacto existente (consulta [API transaccional](https://www.notifuse.com/es/docs/features/transactional-api.md#permissions)).

## Funciones principales

- Los campos predefinidos cubren la mayoría de las necesidades, y los campos personalizados cubren el resto.
- El upsert busca por la dirección de correo, así que una misma dirección nunca crea dos contactos.
- Un contacto puede pertenecer a varias listas de correo.
- Poner un campo a `null` lo borra.
