Suscriptores
Identidad, consentimiento por canal, propiedades y pertenencia a listas de tu audiencia.
Un suscriptor representa a una persona en la marca asociada a la clave API. Incluye email, teléfono, ID externo, consentimiento por canal, propiedades y listas/etiquetas de solo lectura.
Los registros están separados por marca. El mismo email en marcas distintas corresponde a registros distintos. Al crear, el email debe ser único dentro de la marca.
Endpoints
| Método | Ruta | Operación |
|---|---|---|
| GET | /v1/subscribers | Listar |
| GET | /v1/subscribers/:id | Consultar |
| POST | /v1/subscribers | Crear |
| PATCH | /v1/subscribers/:id | Actualizar |
| DELETE | /v1/subscribers/:id | Eliminar |
| POST | /v1/subscribers/:id/subscribe | Registrar un alta |
| POST | /v1/subscribers/:id/unsubscribe | Registrar una baja |
GET requiere subscribers:read; las demás operaciones, subscribers:write. full permite ambas. Las claves test se rechazan con 403 test_mode_unavailable.
Objeto del suscriptor
{
"id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"object": "subscriber",
"email": "[email protected]",
"phone": "+34600000000",
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": {
"email": "subscribed",
"sms": "subscribed",
"whatsapp": "never_subscribed"
},
"properties": {
"company": "Analytical Engines",
"plan": "pro",
"country": "ES"
},
"lists": ["lst_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"],
"tags": ["beta", "vip"],
"created_at": "2026-05-11T12:34:56.000Z",
"updated_at": "2026-05-11T12:34:56.000Z",
"last_active_at": "2026-05-11T15:00:00.000Z"
}| Campo | Tipo | Descripción |
|---|---|---|
id | string | Prefijo sub_ seguido de 32 caracteres hexadecimales. |
object | string | Siempre subscriber. |
email | string o null | Dirección principal, recortada y en minúsculas al escribir. |
phone | string o null | Teléfono; necesario para SMS y WhatsApp. WhatsApp requiere E.164. |
first_name, last_name | string o null | Nombre y apellidos, hasta 100 caracteres cada uno. |
external_id | string o null | ID estable en tu sistema, hasta 255 caracteres; admite filter[external_id]. |
consent | object | Estado de email, SMS y WhatsApp. |
properties | object | Datos propios de segmentación y personalización. El prefijo __ está reservado. |
lists | string[] | IDs lst_… de listas; solo lectura desde la API. |
tags | string[] | Nombres de etiquetas; solo lectura desde la API. |
created_at | string | Creación en ISO 8601 UTC con precisión de milisegundos. |
updated_at | string | Última modificación. |
last_active_at | string o null | Última apertura o clic de email registrado. |
Estados de consentimiento
| Valor | Significado |
|---|---|
subscribed | Hay consentimiento registrado para el canal; su uso también depende de la disponibilidad y las restricciones aplicables. |
unsubscribed | Hay una baja o una supresión por rebote, queja o bloqueo. |
never_subscribed | No hay consentimiento registrado para la identidad actual o falta esa identidad. |
Crear un email sin alta explícita conserva el estado interno pending y devuelve never_subscribed. SMS distingue las bajas con unsubscribed. WhatsApp admite consentimiento inicial explícito con número E.164.
Los endpoints subscribe y unsubscribe registran cambios por canal. Actualizar email o teléfono no transfiere un alta anterior; las bajas y supresiones no se borran al cambiar identidad. Un alta tampoco elimina un rebote, una queja o un bloqueo.
Identificadores
Las rutas aceptan sub_… o el UUID original, con o sin guiones. Otros formatos devuelven 400 invalid_param.
Para buscar por email o por tu ID, utiliza el listado con filter[email] o filter[external_id] y limit=1. No hay búsqueda por email en la ruta del detalle. Guarda siempre external_id al sincronizar para no depender del email como identificador estable.