Referencia de la API REST de NetSendo

Visión general

La API forma parte de todas las instalaciones de NetSendo, tanto SILVER como GOLD. Se ejecuta en tu propio servidor en https://your-domain.com/api/v1, usa JSON y actúa sobre la cuenta a la que pertenece la clave API. El servidor MCP y el nodo de n8n usan los mismos endpoints. Las pocas llamadas de funciones GOLD, como los tests A/B, responden 402 sin una licencia GOLD activa.

Envía en cada solicitud Authorization: Bearer con tu clave y Accept: application/json para que los errores de validación lleguen como JSON, y además Content-Type: application/json cuando la solicitud lleve cuerpo.

Comprueba tu clave

GET /api/v1/account devuelve la cuenta asociada a la clave y la versión de NetSendo. Las integraciones lo usan para probar la conexión.

curl https://your-domain.com/api/v1/account \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Accept: application/json"

# 200 OK
{
  "data": {
    "id": 1,
    "name": "Anna Admin",
    "email": "admin@example.com",
    "version": "2.7.0"
  }
}

Autenticación y claves API

Crea las claves en el panel de NetSendo, en Configuración → Claves API. Ponle un nombre a cada clave, elige sus scopes y, si quieres, una fecha de caducidad. La clave se muestra una sola vez, al crearla; NetSendo solo guarda su hash SHA-256 y registra cuándo se usó por última vez.

Las claves tienen la forma ns_live_ seguido de 32 caracteres aleatorios. Pasa la clave en el encabezado Authorization como token Bearer. No se aceptan claves en los parámetros de la URL.

Authorization: Bearer ns_live_YOUR_KEY

Marca en la clave la opción Clave MCP para que la prueba de conexión MCP integrada pueda usarla. Para conectar asistentes de IA, consulta la documentación del servidor MCP.

Cuando falla la autenticación

La API responde 401 con uno de estos mensajes:

• Missing or invalid Authorization header. Use: Bearer <api_key>
• Invalid API key format. Key should start with ns_live_
• Invalid API key
• API key has expired

Scopes

Cada clave tiene un conjunto de scopes. Un endpoint que requiere un scope que la clave no tiene responde 403 Forbidden.

• Un scope de escritura incluye el scope de lectura del mismo recurso: una clave con lists:write también puede llamar a endpoints que requieren lists:read.
• Una clave creada sin seleccionar ningún scope recibe los 16 scopes.
• Los endpoints marcados como cualquier clave válida en las tablas de abajo solo comprueban que la clave sea válida y no haya caducado. Entre ellos están listar y leer suscriptores, listas, etiquetas, campos personalizados, campañas, embudos, tests A/B y webhooks. Cada endpoint devuelve solo los datos de la cuenta a la que pertenece la clave.

Límites de solicitudes

La API admite 3.000 solicitudes por minuto por clave API. Las rutas sin clave (los endpoints de suscripción a listas y la descarga firmada de exportaciones) se cuentan por dirección IP con el mismo límite.

Las respuestas incluyen X-RateLimit-Limit y X-RateLimit-Remaining. Si se supera el límite, la API responde 429 Too Many Requests con un encabezado Retry-After en segundos.

Para trabajos grandes, usa los endpoints por lotes en lugar de muchas llamadas individuales: hasta 1.000 suscriptores por POST /subscribers/batch, 5.000 filas por importación y 5.000 contactos por operación de membresía.

Errores

Los errores son objetos JSON con una etiqueta breve error y un message legible:

{
  "error": "Forbidden",
  "message": "API key does not have subscribers:write permission"
}

Los errores de validación usan el formato estándar de Laravel: un message y un objeto errors con un array de mensajes por campo. Envía Accept: application/json; sin él, una validación fallida puede responder con una redirección en lugar de JSON.

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Desde NetSendo 2.4.0, las llamadas de funciones GOLD responden 402 Payment Required sin una licencia GOLD activa (sin clave, SILVER o GOLD caducada). La respuesta indica qué función se rechazó; message está en el idioma predeterminado de la instancia (APP_LOCALE):

{
  "error": "Payment Required",
  "code": "gold_required",
  "message": "“A/B tests” requires the GOLD licence. Upgrade on the Licence page to use it.",
  "feature": "ab_tests",
  "required_plan": "GOLD",
  "upgrade_url": "https://your-domain.com/license"
}

Paginación

Los endpoints que devuelven colecciones entregan por defecto páginas de 25 elementos (etiquetas: 50). Cambia el tamaño con per_page y avanza con page. La respuesta trae los elementos en data, los enlaces de página en links y contadores como current_page, per_page y total en meta. La exportación de listas en la propia respuesta pagina con un cursor: pasa limit (como máximo 5.000) y, mientras has_more sea true, el next_cursor devuelto.

Endpoints

Todas las rutas de abajo son relativas a tu instancia, por ejemplo https://your-domain.com/api/v1/subscribers. Sustituye las partes entre llaves por IDs de tu cuenta. Las filas marcadas GOLD necesitan una licencia GOLD activa y sin ella responden 402; las descripciones de los grupos indican las llamadas que necesitan GOLD solo para algunos valores.

• Cuenta y prueba de conexión
• Suscriptores
• Listas de contactos
• Importación y exportación
• Higiene de listas
• Membresía de listas (masiva)
• Actividad e interacción
• Lista de supresión
• Etiquetas y campos personalizados
• Envío de emails
• Envío de SMS
• Campañas (messages)
• Tests A/B
• Embudos
• Reglas de automatización
• Webhooks
• Plantillas y bloques guardados
• Emails y páginas del sistema
• Formularios de suscripción
• Notificaciones
• Endpoints auxiliares para integraciones
• NetSendo Brain
• Endpoints de suscripción a listas

Ejemplos

curl -X POST https://your-domain.com/api/v1/subscribers \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "anna@example.com",
    "contact_list_id": 5,
    "first_name": "Anna",
    "tags": [1, 3],
    "custom_fields": { "city": "Berlin" }
  }'

# 201 Created (200 when the address already existed)
{
  "data": {
    "id": 456,
    "email": "anna@example.com",
    "first_name": "Anna",
    "status": "active",
    "contact_list_id": 5,
    "contact_list_ids": [5],
    "source": "api",
    "tags": [{ "id": 1, "name": "VIP", ... }, { "id": 3, "name": "Newsletter", ... }],
    "custom_fields": { "email": "anna@example.com", "fname": "Anna", ..., "city": "Berlin" },
    "subscribed_at": "2026-11-07T10:30:00.000000Z",
    "created_at": "2026-11-07T10:30:00.000000Z",
    ...
  }
}

curl -X POST https://your-domain.com/api/v1/email/send \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "anna@example.com",
    "subject": "Your order is on its way",
    "content": "<p>Hi [[fname]], your order has shipped.</p>",
    "subscriber_id": 456,
    "mailbox_id": 1
  }'

# 202 Accepted
{
  "data": {
    "id": 123,
    "email": "anna@example.com",
    "subject": "Your order is on its way",
    "status": "queued",
    "mailbox": "Main mailbox",
    "scheduled_at": null
  },
  "message": "Email queued successfully"
}

# 1. Create a draft email campaign for list 5
curl -X POST https://your-domain.com/api/v1/messages \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subject": "November news",
    "channel": "email",
    "type": "broadcast",
    "content": "<h1>Hello [[fname]]</h1>",
    "contact_list_ids": [5],
    "mailbox_id": 1
  }'

# 2a. Send it now (42 = the id returned in step 1)
curl -X POST https://your-domain.com/api/v1/messages/42/send \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Accept: application/json"

# 2b. Or schedule it in a given time zone
curl -X POST https://your-domain.com/api/v1/messages/42/schedule \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "scheduled_at": "2026-11-20 09:00", "timezone": "Europe/Warsaw" }'

const res = await fetch(
  "https://your-domain.com/api/v1/subscribers?status=active&per_page=50",
  {
    headers: {
      Authorization: `Bearer ${process.env.NETSENDO_API_KEY}`,
      Accept: "application/json",
    },
  }
)

if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After") ?? 60)
  // try again after `wait` seconds
}

const { data, meta } = await res.json()
console.log(meta.total, data.map((s) => s.email))

curl -X POST https://your-domain.com/api/v1/lists/5/subscribe \
  -H "Authorization: Bearer YOUR_LIST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "email": "anna@example.com", "first_name": "Anna" }'

# 201 Created
{
  "success": true,
  "message": "Successfully subscribed",
  "subscriber_id": 456,
  "status": "new"
}

Especificación OpenAPI en tu instancia

Cada instalación de NetSendo genera también una descripción OpenAPI de su API. Inicia sesión en el panel y abre https://your-domain.com/docs/api para la referencia interactiva, o /docs/api.json para la especificación sin procesar. Ambas solo son visibles para usuarios con sesión iniciada.

Preguntas frecuentes

Documentación relacionada

• Webhooks: eventos, payloads y verificación de firmas
• Servidor MCP: la misma API para Claude, Cursor y VS Code
• Inicio rápido: instala NetSendo con Docker