Crear un suscriptor
Crea un suscriptor con identidad, propiedades y consentimiento explícito por canal.
POST /v1/subscribers
Requiere el permiso subscribers:write o full. Los permisos se comprueban en el servidor. Las claves test se rechazan con 403 test_mode_unavailable; no existe un sandbox aislado.
Crea un suscriptor. Debe tener email, phone o ambos.
No existe un modo de crear o actualizar en una sola llamada. Si el email ya existe en esta marca, se devuelve 409 resource_already_exists. Localiza el registro con filter[email] y actualízalo. La guía de sincronización explica el patrón.
Cuerpo de la petición
Se rechazan los campos desconocidos con 400 invalid_param.
| Campo | Tipo | Descripción |
|---|---|---|
email | string | Hasta 255 caracteres; se convierte a minúsculas y se recortan espacios. Obligatorio si no hay phone. Único en la marca. |
phone | string | Entre 3 y 32 caracteres; preferentemente E.164, por ejemplo +34600000000. Obligatorio si no hay email. |
first_name | string o null | Nombre, hasta 100 caracteres. |
last_name | string o null | Apellidos, hasta 100 caracteres. |
external_id | string o null | Identificador estable en tu sistema, hasta 255 caracteres. |
properties | object | Propiedades JSON. Las claves que empiezan por __ están reservadas y se rechazan. |
consent | object | Consentimiento inicial de email, sms y whatsapp; admite subscribed, unsubscribed y never_subscribed. |
lists y tags no se pueden asignar al crear; se gestionan desde el panel.
Consentimiento inicial
- Email: solo
subscribedexplícito registra el alta. Omitirconsent.emailo indicarnever_subscribedcrea el estado internopendingy devuelveconsent.email: never_subscribed.unsubscribedconserva la baja. - SMS: con teléfono,
subscribedregistra el alta yunsubscribedconserva la baja. Sin consentimiento explícito quedanever_subscribed. - WhatsApp: el alta explícita se admite al crear y exige un teléfono E.164. Se registra con origen
api. Omitir el canal o indicarnever_subscribedno inventa un alta;unsubscribedconserva la baja.
Registra únicamente consentimiento que hayas obtenido. Guardar un teléfono no autoriza mensajes.
Idempotencia
Reutiliza una misma Idempotency-Key para la misma operación y cuerpo durante 24 horas. Si hay una respuesta completada, se devuelve con Idempotency-Replayed: true. Si una operación ya reservada tiene un 5xx o resultado incierto, la clave permanece reservada durante 24 horas: no se reejecuta automáticamente la escritura. Consulta idempotencia.
Un 503 idempotency_unavailable indica que no se inició la operación; no garantiza una reserva creada. Reintenta la misma operación con la misma clave, sin generar otra para eludir la protección.
Respuesta
El objeto creado con 201 Created.
Ejemplo
curl -X POST https://fluyio.com/api/v1/subscribers \
-H "Authorization: Bearer $FLUYIO_API_KEY" \
-H "Fluyio-Version: 2026-05-15" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7b1b1f1b-3a59-4d20-9e2a-7c5d6f0e1234" \
-d '{
"email": "[email protected]",
"phone": "+34600000000",
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": { "email": "subscribed", "sms": "subscribed" },
"properties": {
"company": "Analytical Engines",
"plan": "pro",
"country": "ES"
}
}'Respuesta
{
"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": [],
"tags": [],
"created_at": "2026-05-11T12:34:56.000Z",
"updated_at": "2026-05-11T12:34:56.000Z",
"last_active_at": null
}Errores
| HTTP | code | Descripción |
|---|---|---|
| 401 | missing_api_key / invalid_api_key | Falta la clave, no es válida, ha caducado o está revocada. |
| 403 | missing_scope | La clave no permite esta operación. |
| 403 | test_mode_unavailable | El modo de pruebas no está disponible. |
| 400 | invalid_param | Identificador de contacto ausente, tipo o longitud incorrectos, email no válido, consentimiento inválido, propiedad reservada o campo desconocido. param identifica el campo cuando se conoce. |
| 400 | invalid_idempotency_key | La clave no tiene entre 8 y 128 caracteres permitidos: A-Z a-z 0-9 _ -. |
| 403 | profile_limit | Se superaría el límite aplicable de perfiles. |
| 409 | resource_already_exists | El email ya existe en la marca. |
| 409 | idempotency_key_reuse | La clave de idempotencia ya se utilizó para otro cuerpo. |