API
API de NewsletterSoft: documentación de la API REST v1
Conecta tu web, tu CRM o tu tienda con NewsletterSoft: contactos, listas, segmentos, campañas de email, automatizaciones, plantillas de SMS y WhatsApp y pop-ups, con la misma clave que usan los agentes de IA por MCP.
La API de NewsletterSoft en un vistazo
La API REST v1 de NewsletterSoft te deja hacer desde tu propio código casi todo lo que haces en el panel: contactos, listas, etiquetas y segmentos; documentos, plantillas y campañas de email; automatizaciones; plantillas de SMS y de WhatsApp y remitentes de SMS; pop-ups y sus leads; y también la galería, las exportaciones, las carpetas, las oportunidades y los datos de tu tienda Shopify.
| Dirección base | La de tu servidor MCP, que está en la sección MCP del panel, cambiando el final /mcp por /v1. |
|---|---|
| Autenticación | Tu clave API en la cabecera Authorization: Bearer. |
| Formato | JSON. Los nombres de los campos son estables, y muchos van en español porque son los mismos objetos que devuelve el MCP. |
| Límite | 60 llamadas por minuto por clave, compartidas con el MCP. Hasta 10 claves activas. |
| Especificación | OpenAPI 3.1, pública, en /v1/openapi.json. |
En esta página:
Autenticación
Cada llamada lleva tu clave en la cabecera: Authorization: Bearer TU_CLAVE. La única que no la necesita es la especificación OpenAPI.
Las claves se crean y se revocan en el panel, en Perfil → API y agentes de IA (MCP). La clave completa solo se ve una vez, al crearla: guárdala en un gestor de secretos o en una variable de entorno, nunca en el código que se ejecuta en el navegador ni en un repositorio.
Crea una clave por integración (tu CRM, tu tienda, un script) para poder revocar una sin tocar las demás. Al revocarla, el acceso se corta en menos de un minuto.
Es la misma clave que usan los agentes de IA por MCP, y da acceso completo a tu cuenta. Trátala como una contraseña.
Primeros pasos con curl y PowerShell
Los ejemplos usan curl, que tienes en macOS, en Linux y en Git Bash para Windows. Guarda antes la dirección base y tu clave en dos variables:
BASE="https://tu-direccion-de-api" # la de la sección MCP del panel, sin el /mcp final
CLAVE="TU_CLAVE"1. Busca contactos
Lista tus contactos con un texto de búsqueda y pide el total exacto del filtro:
curl -s "$BASE/v1/contacts?q=lucia&count=exact" \
-H "Authorization: Bearer $CLAVE"La respuesta trae los contactos y filtered_total. También puedes filtrar por origen (source) y por consentimiento (consent).
2. Crea una lista y mete en ella a un contacto
curl -s "$BASE/v1/lists" \
-H "Authorization: Bearer $CLAVE" \
-H "content-type: application/json" \
-d '{"name": "Clientes VIP", "description": "Más de tres compras"}'
curl -s -X POST "$BASE/v1/contacts/ID_DEL_CONTACTO/lists/ID_DE_LA_LISTA" \
-H "Authorization: Bearer $CLAVE"Si el contacto ya estaba en la lista, la respuesta lo dice con already_member: true y no se duplica. La entrada en la lista cuenta como un evento, así que puede poner en marcha tus automatizaciones.
3. Crea un pop-up en borrador y publícalo
Un pop-up se crea a partir de un brief: el objetivo, el incentivo, los campos, el formato y cuándo aparece. El formato completo lo devuelve GET /v1/brief-schema.
curl -s "$BASE/v1/popups" \
-H "Authorization: Bearer $CLAVE" \
-H "content-type: application/json" \
-d '{
"name": "Novedades otoño",
"brief": {
"objetivo": "captar_emails",
"incentivo": "Envío gratis en tu primer pedido",
"campos": [{"tipo": "email", "verify": "email"}],
"formato": "slidein",
"trigger": {"tipo": "scroll", "valor": 50},
"idioma": "es"
},
"copy": {"title": "¿Te avisamos de las novedades?", "cta": "Quiero el envío gratis"}
}'
curl -s -X POST "$BASE/v1/popups/ID_DEL_POPUP/publish" \
-H "Authorization: Bearer $CLAVE"La primera respuesta trae el id del pop-up y un editor_url para revisarlo en el editor. Hasta la segunda llamada no aparece en tu web.
Lo mismo en PowerShell (Windows)
$BASE = "https://tu-direccion-de-api"
$H = @{ Authorization = "Bearer TU_CLAVE" }
Invoke-RestMethod -Uri "$BASE/v1/contacts?q=lucia&count=exact" -Headers $H
$body = '{"name": "Clientes VIP", "description": "Más de tres compras"}'
Invoke-RestMethod -Uri "$BASE/v1/lists" -Method Post -Headers $H -ContentType "application/json; charset=utf-8" -Body $bodyCómo enviar una campaña de email por la API
Una campaña de email no sale hasta que pasa su lista de comprobación. Este es el recorrido completo por la API:
- Prepara el contenido. Crea un documento de email desde tu HTML con
POST /v1/email-documents, o parte de una plantilla conPOST /v1/email-templates/{id}/use. El HTML tiene que llevar la variable de baja: sin ella, el documento no se guarda. - Crea la campaña en borrador con
POST /v1/campaigns. - Complétala con
PATCH /v1/campaigns/{id}: asunto, remitente, documento y audiencia (todos tus contactos, unas listas o un segmento), con exclusiones si las necesitas. - Revisa lo que falta.
GET /v1/campaigns/{id}devuelve la lista de comprobación. Envíate una prueba real conPOST /v1/campaigns/{id}/test: la prueba también cuenta en esa lista. - Envíala o prográmala con
POST /v1/campaigns/{id}/send. Sin cuerpo sale ya; con{"when": "2026-11-20T09:30:00+01:00"}se programa, y con"lock_send_time": trueesa hora queda fija. Si falta algo de la lista, la respuesta es 409 y no sale nada.
Después puedes pausarla, reanudarla o cancelarla (/pause, /resume y /cancel), y duplicarla como borrador para repetirla.
Referencia de endpoints
Todos los endpoints de la versión 1, agrupados por áreas. {id} es el identificador del recurso, y «·» separa las variantes de una misma ruta (por ejemplo, /archive · /restore). Los campos exactos de cada petición y de cada respuesta están en la especificación OpenAPI.
Contactos y etiquetas · Listas · Segmentos · Documentos y plantillas de email · Campañas de email · Automatizaciones · SMS: plantillas y remitentes · Plantillas de WhatsApp · Pop-ups · Galería, exportaciones y carpetas · Oportunidades, tienda Shopify y cuenta
Contactos y etiquetas
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET | /v1/contacts | Lista tus contactos. Filtra por texto (q), origen (source) y consentimiento (consent); con count=exact devuelve el total del filtro. |
| POST | /v1/contacts | Da de alta un contacto a mano. Su consentimiento queda sin confirmar: la API nunca lo da por hecho. |
| GET | /v1/contacts/{id} | La ficha: sus identidades (email, teléfono), sus listas, su actividad y si está suprimido. |
| PATCH | /v1/contacts/{id} | Cambia el nombre y los atributos. El email, el teléfono, las etiquetas y el RFM no se editan aquí. |
| DELETE | /v1/contacts/{id} | Borra el contacto por completo: sale al momento de contactos, listas, segmentos y exportaciones, y el resto de sus datos se borra en segundo plano. |
| GET | /v1/contacts/overview | Resumen de tu audiencia: total, estado general y por canal, con la evolución diaria de los últimos 180 días. |
| GET | /v1/contacts/export | El listado en CSV, con los mismos filtros (texto, origen, consentimiento, etiqueta o lista). |
| GET | /v1/contacts/{id}/commerce | Sus compras: totales y últimos pedidos con sus productos, por páginas. |
| GET | /v1/contacts/{id}/predictions | Sus predicciones: puntuaciones, siguiente acción recomendada y productos recomendados, marcando los que ya compró. |
| POST | /v1/contacts/{id}/tags | Le pone una etiqueta por su nombre. |
| DELETE | /v1/contacts/{id}/tags/{tagId} | Le quita una etiqueta. |
| GET | /v1/tags | Las etiquetas de tu cuenta. |
Listas
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/lists | Tus listas activas (con ?archived=1, las archivadas) o crear una: nombre y, si quieres, descripción, canal y si es la principal. |
| GET PATCH DELETE | /v1/lists/{id} | Detalle con sus cifras de contactabilidad, cambiar sus datos o borrarla. Si cambias el canal, deja de ser la principal; si la usa algo, no se borra (409). |
| GET | /v1/lists/{id}/members | Sus miembros, con búsqueda, paginación y el estado de consentimiento de cada uno. |
| POST DELETE | /v1/contacts/{id}/lists/{listId} | Mete o saca a un contacto de la lista. |
| POST | /v1/lists/{id}/archive · /restore | Archivarla (409 si está en uso) o restaurarla. |
| POST | /v1/lists/{id}/duplicate | Copiarla con sus miembros, en segundo plano. La copia nunca es la principal. |
| POST | /v1/lists/{id}/primary | Marcarla o desmarcarla como principal de su canal. |
| GET | /v1/lists/{id}/export · /usage | Sus miembros en CSV, o qué campañas y automatizaciones la usan. |
Segmentos
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/segments | Tus segmentos, con su estado y su tamaño, o crear uno con su nombre y sus condiciones. Los que propone una IA nacen como propuesta. |
| GET | /v1/segments/attributes · /events | Los datos y los eventos (con sus propiedades) por los que puedes segmentar. |
| POST | /v1/segments/preview | Calcula unas condiciones sin guardar nada: cuántos entran, cuántos se pueden contactar por canal, una muestra y avisos. |
| POST | /v1/segments/preview/breakdown | Desglosa ese cálculo por grupo y por condición (hasta 10 grupos y 20 condiciones). |
| GET PATCH DELETE | /v1/segments/{id} | Detalle, cambiar el nombre o las condiciones, o borrarlo (409 si está en uso). |
| POST | /v1/segments/{id}/publish · /refresh | Publicarlo y calcular sus miembros, o volver a calcularlos. Va en segundo plano. |
| POST | /v1/segments/{id}/archive · /restore · /duplicate | Archivarlo, restaurarlo (vuelve como borrador) o duplicarlo como borrador. |
| POST | /v1/segments/{id}/snapshot | Crea una lista con quienes cumplen el segmento en ese momento. |
| GET | /v1/segments/{id}/export · /usage | Sus miembros en CSV, o qué campañas y automatizaciones lo usan. |
| GET | /v1/audiences/fields | Los campos de una lista, de un segmento o de toda tu audiencia que puedes usar para personalizar SMS y WhatsApp. |
Documentos y plantillas de email
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/email-documents | Tus documentos de email, con la última campaña que usó cada uno, o crear uno desde HTML (y MJML). Tiene que llevar la variable de baja. |
| PATCH | /v1/email-documents/{id} | Habilitarlo o deshabilitarlo. Lo que ya lo usa no cambia. |
| POST | /v1/email-documents/{id}/duplicate | Copiarlo. |
| GET | /v1/email-templates | Las plantillas de serie y las tuyas. |
| GET PATCH | /v1/email-templates/{id} | Una plantilla con su HTML y su MJML, o habilitarla y deshabilitarla. Si es tuya, también cambias su nombre o su contenido; las de serie no se editan, se duplican. |
| POST | /v1/email-templates/{id}/use | Crea un documento editable a partir de la plantilla. |
Campañas de email
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/campaigns | Tus campañas, o crear una en borrador. |
| GET PATCH | /v1/campaigns/{id} | Detalle, métricas y lista de comprobación, o cambiar asunto, remitente, documento, audiencia y exclusiones. |
| POST | /v1/campaigns/{id}/test | Envía una prueba real. |
| POST | /v1/campaigns/{id}/send | La envía ya o a una hora (when). Responde 409 si falta algo de la lista. |
| POST | /v1/campaigns/{id}/pause · /resume · /cancel | Pausarla, reanudarla o cancelarla. |
| POST | /v1/campaigns/{id}/duplicate | Copiarla como borrador, sin estado, programación ni métricas. Si su remitente ha dejado de estar autorizado, la copia lleva el predeterminado y te avisa. |
Automatizaciones
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET | /v1/workflows | Tus automatizaciones. |
| GET | /v1/workflows/{id} | Su estructura y sus contadores. |
| POST | /v1/workflows/{id}/publish | La publica y la activa. Antes comprueba que el flujo es válido y que cada email lleva la baja; si no, responde 409. |
| POST | /v1/workflows/{id}/pause · /resume | Pausarla sin perder a los contactos que están dentro, o reanudarla (409 si no tiene una versión publicada). |
| GET | /v1/workflows/{id}/instances | Por dónde ha pasado cada contacto. |
SMS: plantillas y remitentes
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/sms/templates | Tus plantillas, con cuántos SMS ocupa cada una y su juego de caracteres, o crear una. El texto se mide como en un envío; con el acortador activo, cada enlace cuenta como uno corto de 17 caracteres, con un máximo de 5 por SMS. |
| GET PATCH DELETE | /v1/sms/templates/{id} | Verla, editarla o borrarla. |
| PATCH | /v1/sms/templates/{id}/enabled | Habilitarla o deshabilitarla. |
| POST | /v1/sms/templates/{id}/duplicate | Duplicarla. |
| POST | /v1/sms/templates/delete | Borrar varias de una vez, con dry_run para probar antes. |
| POST | /v1/sms/templates/{id}/use | Prepara un envío de SMS en borrador con esa plantilla. No envía nada. |
| GET POST | /v1/sms/senders | Tus remitentes y el estado de cada solicitud, o pedir uno nuevo en borrador: alias, tipo (alfanumérico o numérico), país y modo. |
| GET | /v1/sms/senders/{id} | Detalle de una solicitud. |
| POST | /v1/sms/senders/{id}/submit | La envía a revisión. Tiene que llevar todos los datos del modo elegido y, en el modo delegado, la carta firmada que subes en el panel. |
Plantillas de WhatsApp
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/whatsapp/templates | Tus plantillas, con su categoría, su idioma y su estado, o crear una por bloques (marketing, utilidad o autenticación). El mensaje se valida con tu proveedor de WhatsApp. |
| GET PATCH DELETE | /v1/whatsapp/templates/{id} | Verla, editarla o borrarla. Los envíos que ya salieron conservan su copia. |
| PATCH | /v1/whatsapp/templates/{id}/enabled | Habilitarla o deshabilitarla. |
| POST | /v1/whatsapp/templates/{id}/duplicate | Duplicarla. |
| POST | /v1/whatsapp/templates/delete | Borrar varias de una vez, con dry_run para probar antes. |
| POST | /v1/whatsapp/templates/{id}/use | Prepara un envío de WhatsApp en borrador con esa plantilla. No envía nada. |
Pop-ups
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET | /v1/brief-schema | El formato del brief con el que se crea un pop-up. |
| GET | /v1/sites · /v1/templates · /v1/palettes | Tus webs, las plantillas de pop-up y las paletas de color. |
| GET POST | /v1/popups | Tus pop-ups (hasta 50, primero los recientes, filtrables por estado), o crear uno en borrador a partir de un brief y tus textos. |
| GET PATCH | /v1/popups/{id} | Su estado y su brief, con el origen de cada campo, o cambiar el brief y recomponer el diseño. Lo que cambiaste a mano no se toca; si estaba publicado, se vuelve a publicar. |
| POST | /v1/popups/{id}/publish | Lo publica en tu web. |
| GET | /v1/popups/{id}/leads | Sus leads, primero los recientes, y el total. |
Galería, exportaciones y carpetas
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/media | Tus imágenes, vídeos y documentos con su dirección pública, o subir uno: imágenes JPEG, PNG, WebP o GIF de hasta 5 MB, y vídeo, audio o PDF de hasta 16 MB. |
| POST | /v1/media/import | Trae un fichero desde una URL https pública (hasta 16 MB). |
| GET | /v1/media/usage | Cuánto ocupas y los límites de tu plan. |
| GET PATCH DELETE | /v1/media/{id} | Ver dónde se usa, cambiar su nombre, su carpeta o sus etiquetas, o borrarlo (409 si lo usa algo activo). |
| POST | /v1/media/delete | Borra varios de una vez. |
| GET POST | /v1/exports | Tus últimas 50 exportaciones, o crear una en segundo plano: hasta 250.000 filas y 3 a la vez. |
| GET | /v1/exports/{id} | El estado de una exportación. |
| GET | /v1/exports/{id}/download | Descarga el CSV (409 si no está lista, 410 si caducó). |
| GET POST | /v1/folders | Las carpetas de cada pantalla (pop-ups, formularios, campañas, documentos, plantillas, audiencias, envíos, automatizaciones y oportunidades), con hasta 7 niveles, o crear una. |
| PATCH DELETE | /v1/folders/{id} | Renombrar o mover una carpeta, o borrarla: lo que tenía sube un nivel. |
| POST | /v1/folders/move-items | Mueve hasta 200 elementos a una carpeta. |
Oportunidades, tienda Shopify y cuenta
| Método | Ruta | Para qué sirve |
|---|---|---|
| GET POST | /v1/opportunities | Tus oportunidades, con su etapa (nueva, contactado, propuesta, ganada o perdida) y su contacto, o crear una: nombre, importe en euros, etapa, email del contacto y notas. |
| PATCH DELETE | /v1/opportunities/{id} | Editarla o cambiarla de etapa, o borrarla. |
| GET | /v1/shopify/products | El catálogo de tu tienda conectada, con imagen, precio, dirección y si está activo. |
| GET | /v1/commerce/best-sellers | Los productos más vendidos en un periodo (90 días, si no dices otro). |
| GET | /v1/ml/fallback-products | Los productos que se recomiendan cuando no hay una predicción para el contacto. |
| POST | /v1/shopify/customers/sync | Trae tus clientes de Shopify como contactos. |
| GET | /v1/shopify/customers/status | Cómo va esa sincronización. |
| GET | /v1/shopify/webhooks/status | El estado de los avisos que llegan de tu tienda. |
| GET | /v1/home/summary | El resumen de la pantalla de inicio: captación, última campaña de cada canal, automatizaciones y oportunidades. |
| GET | /v1/forms/{id}/preview | Una vista previa de un formulario, con el envío desactivado. |
| GET | /v1/openapi.json | La especificación completa. Es pública. |
Errores
Cuando algo falla, la respuesta trae el código HTTP que corresponde y un cuerpo como {"error": {"code": "…", "message": "…"}}. El message explica qué corregir.
| HTTP | Código | Qué pasa |
|---|---|---|
| 400 | bad_request, bad_site, bad_template, bad_palette, nothing_to_update, no_project | A la petición le falta algo o tiene un valor que no vale. |
| 401 | unauthorized | No hay clave, no es válida o está revocada. |
| 402 | La galería ha llegado al límite de tu plan. | |
| 404 | not_found | El recurso no existe o no es de tu cuenta. |
| 405 | method_not_allowed | Método HTTP equivocado. La cabecera Allow dice cuáles valen. |
| 409 | limit_popups y otros | Choca con el estado actual: falta algo de la lista de comprobación, el recurso está en uso o archivado, ya hay uno igual o has llegado al cupo de pop-ups de tu plan. |
| 410 | La exportación ha caducado. | |
| 413 | payload_too_large | El cuerpo de la petición es demasiado grande. |
| 415 | Ese tipo de fichero no se admite en la galería. | |
| 422 | Demasiados niveles de carpetas. | |
| 429 | rate_limited | Más de 60 llamadas por minuto con la misma clave, o más de 3 exportaciones a la vez. |
| 500 | store_failed, internal | Fallo nuestro: vuelve a intentarlo. |
| 503 | Un dato no está disponible en ese momento: vuelve a intentarlo. |
Límites y garantías
- 60 llamadas por minuto por clave, compartidas entre la API y el MCP, porque la clave es la misma. Puedes tener hasta 10 claves activas.
- Nada sale solo. Los pop-ups, las campañas y los envíos de SMS y WhatsApp se crean en borrador. Publicar o enviar es siempre una llamada aparte, y una campaña no sale sin completar su lista de comprobación.
- El consentimiento no se inventa. El alta manual de un contacto no lo da por hecho, y las campañas y los flujos pasan las mismas comprobaciones de consentimiento que en el panel.
- Cada email lleva la baja. Un documento sin la variable de baja no se guarda, y una automatización con un email sin baja no se publica.
- Tus cambios mandan. Al editar un pop-up por la API no se tocan los campos que fijó una persona, y la respuesta dice cuáles ha respetado (
campos_protegidos_no_tocados). Ojo: al recomponer el diseño se pierden los ajustes visuales que hiciste a mano en el editor. - Los cupos de tu plan (envíos, pop-ups, leads, galería) se aplican igual que en el panel. Componer un pop-up no gasta asistencias de IA.
- Exportaciones: hasta 250.000 filas y 3 a la vez. El fichero caduca a los 7 días, el permiso se comprueba en cada descarga y, si se borra un contacto, las exportaciones que lo incluían dejan de servir.
Versiones y especificación OpenAPI
El prefijo /v1 es estable. Los cambios compatibles, como campos o recursos nuevos, no rompen tu integración; un cambio incompatible llegaría como /v2.
La especificación completa, en OpenAPI 3.1, está publicada sin autenticación en /v1/openapi.json de tu dirección base. Impórtala en Postman o en Insomnia (Importar, desde URL) o genera con ella un cliente para tu lenguaje. Esta página resume la versión 1.2.0 de la especificación, consultada el 29-10-2026.
¿Prefieres un agente de IA? Conéctalo por MCP
Si prefieres que sea un asistente de IA quien trabaje con tu cuenta, en lugar de programar la integración, conéctalo por MCP. ChatGPT, Claude, Claude Code, Cursor o n8n usan las mismas operaciones que esta API: consultan tus contactos y tus resultados y preparan campañas en borrador. Te lo explicamos en campañas MCP, y en qué es MCP si el protocolo es nuevo para ti.
Preguntas frecuentes sobre la API
¿La clave de la API es la misma que la del MCP?
Sí. Una clave sirve para las dos y el límite de 60 llamadas por minuto es conjunto. Se crea y se revoca en Perfil → API y agentes de IA (MCP).
¿Puedo enviar SMS o WhatsApp desde la API?
La API crea y edita las plantillas y deja preparado el envío en borrador. Ese envío lo confirmas en el panel. Las campañas de email sí se envían por la API, cuando su lista de comprobación está completa.
Los contactos que doy de alta por la API, ¿reciben mis campañas?
El alta manual no registra consentimiento, así que no los recibirán hasta que lo den, por ejemplo con un formulario o un pop-up. Es la misma regla que en el panel.
¿Hay webhooks?
Para los leads de los pop-ups, todavía no: consúltalos con GET /v1/popups/{id}/leads o mándalos a tu herramienta con las integraciones del panel. Dentro de una automatización, el bloque Webhook envía los datos del contacto a otra herramienta.
¿Por qué hay campos con nombres en español?
Porque la API devuelve los mismos objetos que las herramientas del MCP. Los nombres son estables y están en la especificación OpenAPI.
¿Vas a integrar NewsletterSoft?
Te ayudamos a conectar tu CRM, tu tienda o tu web con la API.