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 baseLa de tu servidor MCP, que está en la sección MCP del panel, cambiando el final /mcp por /v1.
AutenticaciónTu clave API en la cabecera Authorization: Bearer.
FormatoJSON. Los nombres de los campos son estables, y muchos van en español porque son los mismos objetos que devuelve el MCP.
Límite60 llamadas por minuto por clave, compartidas con el MCP. Hasta 10 claves activas.
EspecificaciónOpenAPI 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 $body

Có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:

  1. Prepara el contenido. Crea un documento de email desde tu HTML con POST /v1/email-documents, o parte de una plantilla con POST /v1/email-templates/{id}/use. El HTML tiene que llevar la variable de baja: sin ella, el documento no se guarda.
  2. Crea la campaña en borrador con POST /v1/campaigns.
  3. 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.
  4. Revisa lo que falta. GET /v1/campaigns/{id} devuelve la lista de comprobación. Envíate una prueba real con POST /v1/campaigns/{id}/test: la prueba también cuenta en esa lista.
  5. 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": true esa 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étodoRutaPara qué sirve
GET/v1/contactsLista tus contactos. Filtra por texto (q), origen (source) y consentimiento (consent); con count=exact devuelve el total del filtro.
POST/v1/contactsDa 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/overviewResumen de tu audiencia: total, estado general y por canal, con la evolución diaria de los últimos 180 días.
GET/v1/contacts/exportEl listado en CSV, con los mismos filtros (texto, origen, consentimiento, etiqueta o lista).
GET/v1/contacts/{id}/commerceSus compras: totales y últimos pedidos con sus productos, por páginas.
GET/v1/contacts/{id}/predictionsSus predicciones: puntuaciones, siguiente acción recomendada y productos recomendados, marcando los que ya compró.
POST/v1/contacts/{id}/tagsLe pone una etiqueta por su nombre.
DELETE/v1/contacts/{id}/tags/{tagId}Le quita una etiqueta.
GET/v1/tagsLas etiquetas de tu cuenta.

Listas

MétodoRutaPara qué sirve
GET POST/v1/listsTus 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}/membersSus 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 · /restoreArchivarla (409 si está en uso) o restaurarla.
POST/v1/lists/{id}/duplicateCopiarla con sus miembros, en segundo plano. La copia nunca es la principal.
POST/v1/lists/{id}/primaryMarcarla o desmarcarla como principal de su canal.
GET/v1/lists/{id}/export · /usageSus miembros en CSV, o qué campañas y automatizaciones la usan.

Segmentos

MétodoRutaPara qué sirve
GET POST/v1/segmentsTus 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 · /eventsLos datos y los eventos (con sus propiedades) por los que puedes segmentar.
POST/v1/segments/previewCalcula unas condiciones sin guardar nada: cuántos entran, cuántos se pueden contactar por canal, una muestra y avisos.
POST/v1/segments/preview/breakdownDesglosa 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 · /refreshPublicarlo y calcular sus miembros, o volver a calcularlos. Va en segundo plano.
POST/v1/segments/{id}/archive · /restore · /duplicateArchivarlo, restaurarlo (vuelve como borrador) o duplicarlo como borrador.
POST/v1/segments/{id}/snapshotCrea una lista con quienes cumplen el segmento en ese momento.
GET/v1/segments/{id}/export · /usageSus miembros en CSV, o qué campañas y automatizaciones lo usan.
GET/v1/audiences/fieldsLos 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étodoRutaPara qué sirve
GET POST/v1/email-documentsTus 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}/duplicateCopiarlo.
GET/v1/email-templatesLas 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}/useCrea un documento editable a partir de la plantilla.

Campañas de email

MétodoRutaPara qué sirve
GET POST/v1/campaignsTus 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}/testEnvía una prueba real.
POST/v1/campaigns/{id}/sendLa envía ya o a una hora (when). Responde 409 si falta algo de la lista.
POST/v1/campaigns/{id}/pause · /resume · /cancelPausarla, reanudarla o cancelarla.
POST/v1/campaigns/{id}/duplicateCopiarla 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étodoRutaPara qué sirve
GET/v1/workflowsTus automatizaciones.
GET/v1/workflows/{id}Su estructura y sus contadores.
POST/v1/workflows/{id}/publishLa 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 · /resumePausarla sin perder a los contactos que están dentro, o reanudarla (409 si no tiene una versión publicada).
GET/v1/workflows/{id}/instancesPor dónde ha pasado cada contacto.

SMS: plantillas y remitentes

MétodoRutaPara qué sirve
GET POST/v1/sms/templatesTus 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}/enabledHabilitarla o deshabilitarla.
POST/v1/sms/templates/{id}/duplicateDuplicarla.
POST/v1/sms/templates/deleteBorrar varias de una vez, con dry_run para probar antes.
POST/v1/sms/templates/{id}/usePrepara un envío de SMS en borrador con esa plantilla. No envía nada.
GET POST/v1/sms/sendersTus 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}/submitLa 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étodoRutaPara qué sirve
GET POST/v1/whatsapp/templatesTus 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}/enabledHabilitarla o deshabilitarla.
POST/v1/whatsapp/templates/{id}/duplicateDuplicarla.
POST/v1/whatsapp/templates/deleteBorrar varias de una vez, con dry_run para probar antes.
POST/v1/whatsapp/templates/{id}/usePrepara un envío de WhatsApp en borrador con esa plantilla. No envía nada.

Pop-ups

MétodoRutaPara qué sirve
GET/v1/brief-schemaEl formato del brief con el que se crea un pop-up.
GET/v1/sites · /v1/templates · /v1/palettesTus webs, las plantillas de pop-up y las paletas de color.
GET POST/v1/popupsTus 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}/publishLo publica en tu web.
GET/v1/popups/{id}/leadsSus leads, primero los recientes, y el total.

Galería, exportaciones y carpetas

MétodoRutaPara qué sirve
GET POST/v1/mediaTus 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/importTrae un fichero desde una URL https pública (hasta 16 MB).
GET/v1/media/usageCuá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/deleteBorra varios de una vez.
GET POST/v1/exportsTus ú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}/downloadDescarga el CSV (409 si no está lista, 410 si caducó).
GET POST/v1/foldersLas 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-itemsMueve hasta 200 elementos a una carpeta.

Oportunidades, tienda Shopify y cuenta

MétodoRutaPara qué sirve
GET POST/v1/opportunitiesTus 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/productsEl catálogo de tu tienda conectada, con imagen, precio, dirección y si está activo.
GET/v1/commerce/best-sellersLos productos más vendidos en un periodo (90 días, si no dices otro).
GET/v1/ml/fallback-productsLos productos que se recomiendan cuando no hay una predicción para el contacto.
POST/v1/shopify/customers/syncTrae tus clientes de Shopify como contactos.
GET/v1/shopify/customers/statusCómo va esa sincronización.
GET/v1/shopify/webhooks/statusEl estado de los avisos que llegan de tu tienda.
GET/v1/home/summaryEl resumen de la pantalla de inicio: captación, última campaña de cada canal, automatizaciones y oportunidades.
GET/v1/forms/{id}/previewUna vista previa de un formulario, con el envío desactivado.
GET/v1/openapi.jsonLa 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.

HTTPCódigoQué pasa
400bad_request, bad_site, bad_template, bad_palette, nothing_to_update, no_projectA la petición le falta algo o tiene un valor que no vale.
401unauthorizedNo hay clave, no es válida o está revocada.
402La galería ha llegado al límite de tu plan.
404not_foundEl recurso no existe o no es de tu cuenta.
405method_not_allowedMétodo HTTP equivocado. La cabecera Allow dice cuáles valen.
409limit_popups y otrosChoca 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.
410La exportación ha caducado.
413payload_too_largeEl cuerpo de la petición es demasiado grande.
415Ese tipo de fichero no se admite en la galería.
422Demasiados niveles de carpetas.
429rate_limitedMás de 60 llamadas por minuto con la misma clave, o más de 3 exportaciones a la vez.
500store_failed, internalFallo nuestro: vuelve a intentarlo.
503Un 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

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

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.

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.

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.

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.