API SMS de Mailpro™ : Referencia

POST /token

Obtener token de acceso (redirección 307 a /v3/token)

Obtiene un token JWT Bearer utilizando las credenciales de cliente de Mailpro. Pase el access_token devuelto como Authorization: Bearer <token> en todas las solicitudes posteriores. El mismo token también es válido en la API CRM v3 y en la API Email v2.

> ⚙ Detalle de implementación — POST /sms/token es una redirección > temporal 307 a POST /v3/token (configurada en la capa de reescritura > del web.config de IIS). HTTP 307 conserva tanto el método (POST) > como el cuerpo de la solicitud, por lo que cualquier cliente HTTP conforme > a la norma sigue la redirección de forma transparente — usted sigue haciendo POST a /sms/token > y recibe un JWT válido. No hay lógica de emisión de tokens duplicada; la API > SMS nunca emite tokens por sí misma.

Tipos de grant admitidos

Duración del token

• Token de acceso: 30 días
• Refresh token: 90 días

Utilice grant_type=refresh_token para renovar el token de acceso sin volver a autenticarse. Almacene los tokens en el lado del servidor (Vault, variables de entorno); nunca los incruste en JS de navegador ni en binarios de aplicaciones móviles. Consulte la nota de seguridad completa en la documentación de /token de la API CRM v3.

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "userName": "12345",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "application": null
}

Ejemplo 400

{
  "error": "invalid_grant",
  "error_description": "The username or password is incorrect."
}

GET /account/limits.{format}

Obtener la cuota mensual de la API

Devuelve la cuota mensual de solicitudes de la API para el cliente autenticado.

Cálculo de la cuota: el límite se calibra a partir de los créditos de la suscripción de correo electrónico (normalmente subscription_credits × 5). Para un plan de 10 000 correos electrónicos al mes, esto da un presupuesto mensual de 50 000 solicitudes. Se restablece en la fecha de aniversario de la suscripción (no el día 1 del mes natural).

Qué consume créditos:

• Cada solicitud autenticada a la API en los endpoints v2, v3 o sms.
• Cada evento de webhook enviado a un endpoint suscrito.

Qué es GRATIS (no consume créditos):

• Los endpoints /health.
• Las solicitudes que fallan con 401, 403 o 429.
• Los eventos de webhook para clientes sin una suscripción correspondiente.

La cuota se comparte entre las 3 APIs de Mailpro (v2, v3, sms) — un cliente = un presupuesto mensual para toda la plataforma. Los envíos SMS consumen adicionalmente el saldo dedicado de créditos SMS (GET /credit/get.{format}).

Scope OAuth : account:read

Parámetros

Respuestas

Ejemplo 200

{
  "monthlyLimit": 50000,
  "remaining": 32847,
  "used": 17153,
  "isFree": false,
  "remainedSendsForFree": null
}

POST /send/add.{format}

Enviar SMS masivos a una lista de contactos

Envía un mensaje SMS a todos los números de teléfono de una lista de contactos. Admite la programación: establezca scheduled_time en una fecha futura para enviar más tarde, o omítalo para enviar de inmediato.

Consumo de créditos: los créditos se descuentan en el momento del envío. Los mensajes largos (>160 caracteres GSM-7) se dividen en varias partes, cada una con un coste adicional en créditos.

La respuesta devuelve { "Error": "Insufficient Credit", "Code": 202 } si la cuenta no tiene créditos suficientes.

Scope OAuth : sms:send

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Id": 6001,
  "Message": "Flash sale today only — 30% off all orders. Shop now at mailpro.com/shop",
  "ScheduledTime": "2026-04-20T10:00:00",
  "To": [
    "42"
  ]
}

Ejemplo 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Ejemplo 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/add_single.{format}

Enviar un único SMS (GET)

Envía un único SMS a un destinatario mediante una solicitud GET. Útil para integraciones sencillas donde POST no esté disponible. Las credenciales y el mensaje se pasan como parámetros de consulta.

Nota: evite usar GET para mensajes sensibles — los parámetros de consulta aparecen en los registros del servidor. Utilice preferentemente POST /send/add_single.

Scope OAuth : sms:send

Parámetros

Respuestas

Ejemplo 200

{
  "Id": 5001,
  "Message": "Your appointment is confirmed for tomorrow at 10:00.",
  "ScheduledTime": "2026-04-15T09:00:00",
  "To": "0041791234567",
  "Charge": "1"
}

POST /send/add_single.{format}

Enviar un único SMS

Envía un único mensaje SMS a un número de teléfono destinatario. Admite programación mediante scheduled_time.

Consumo de créditos: los créditos se descuentan en el momento del envío. El campo Charge de la respuesta muestra cuántos créditos se consumieron.

La respuesta devuelve { "Error": "Insufficient Credit", "Code": 202 } si la cuenta no tiene créditos suficientes.

Scope OAuth : sms:send

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Id": 5001,
  "Message": "Your verification code is 8472. Valid for 10 minutes.",
  "ScheduledTime": "2026-04-15T14:30:00",
  "To": "0041791234567",
  "Charge": "1"
}

Ejemplo 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Ejemplo 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/list.{format}

Listar las campañas SMS

Devuelve la lista de campañas SMS (envíos masivos) de la cuenta. Paginación mediante las cabeceras NumberOfRecords y PageNumber.

Utilice type_to para filtrar por tipo de envío:

• 0 (por defecto) — envíos masivos a listas
• 1 — envíos individuales únicos

Scope OAuth : sms:send

Parámetros

Respuestas

Ejemplo 200

[
  {
    "Id": 5001,
    "Message": "Your verification code is 8472",
    "ScheduledTime": "2026-04-15T09:00:00",
    "To": "41791234567"
  }
]

POST /send/del.{format}

Cancelar o eliminar un envío de SMS

Cancela un envío SMS programado pendiente, o elimina uno completado del historial. Solo se pueden cancelar los envíos programados para el futuro. Los envíos en curso no se pueden detener.

Scope OAuth : sms:send

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Result": "OK"
}

Ejemplo 500

{
  "Error": "Delete failed",
  "Code": 500
}

GET /send/scheduled.{format}

Listar mis envíos SMS programados

Devuelve los envíos SMS (únicos o de campaña) programados para una fecha futura que aún no se han despachado. Útil antes de llamar a /cancel o /reschedule.

Los registros se ordenan por scheduled_time ascendente.

Scope OAuth : sms:send

Parámetros

Respuestas

Ejemplo 200

[
  {
    "Id": 9001,
    "Message": "Black Friday: 30% off until midnight.",
    "ScheduledTime": "2026-11-27T12:00:00",
    "To": "+33671234567"
  }
]

POST /send/{id_send}/cancel.{format}

Cancelar un envío SMS programado

Cancela un SMS programado que aún no se ha despachado. Si el envío ya se ha procesado (o no existe / pertenece a otro cliente), devuelve 409 Conflict.

Scope OAuth : sms:send

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Result": "OK",
  "Cancelled": 9001
}

Ejemplo 409

{
  "error": "conflict",
  "message": "Send not found, not owned by client, or already dispatched."
}

PATCH /send/{id_send}/reschedule.{format}

Reprogramar un envío SMS programado

Actualiza la fecha prevista de un SMS programado que aún no se ha despachado. La nueva fecha debe ser futura y dentro de los 90 días.

Nombre del campo de fecha: la API acepta scheduled_time (principal) así como los alias heredados PlanDate, date_planned y DatePlanned. Proporcione cualquiera de ellos — se utiliza el primero que no sea nulo.

Scope OAuth : sms:send

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Result": "OK",
  "Id": 9001,
  "NewScheduledTime": "2026-12-31T14:30:00"
}

Ejemplo 409

{
  "error": "conflict",
  "message": "Reschedule failed — send not found, already dispatched, or new date out of range."
}

GET /list/list.{format}

Listar las listas de contactos telefónicos

Devuelve todas las listas de contactos SMS de la cuenta. Utilice los valores Id devueltos al enviar campañas SMS masivas o al añadir números de teléfono.

Scope OAuth : sms:contacts:read

Parámetros

Respuestas

Ejemplo 200

{
  "Items": [
    {
      "AddressBookId": 42,
      "Name": "Newsletter subscribers",
      "TotalNumberPhones": 1547
    },
    {
      "AddressBookId": 43,
      "Name": "Loyalty program",
      "TotalNumberPhones": 823
    }
  ]
}

POST /list/add.{format}

Crear una lista de contactos

Crea una nueva lista de contactos SMS con el nombre indicado. La lista comienza vacía — añada números de teléfono con POST /phone/add. Máximo 1000 listas por cuenta (mismo límite en las tres API de Mailpro y en la app). Devuelve HTTP 422 si se alcanza el límite.

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Id": 44,
  "Name": "Spring campaign 2026",
  "NumberPhones": 0
}

Ejemplo 400

{
  "Error": "Malformed Input",
  "Code": 103
}

POST /list/edit.{format}

Renombrar una lista de contactos

Actualiza el nombre visible de una lista de contactos SMS existente. Los números de teléfono de la lista no se ven afectados.

Scope OAuth : sms:contacts:write

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

POST /list/del.{format}

Eliminar una lista de contactos

Elimina de forma permanente una lista de contactos SMS y todos los números de teléfono que contiene. Esta acción no se puede deshacer.

Scope OAuth : sms:contacts:write

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

GET /phone/list.{format}

Listar los números de teléfono de una lista de contactos

Devuelve una lista paginada de los números de teléfono de una lista de contactos concreta. Utilice address_book_id para especificar qué lista desea recuperar. Paginación: NumberOfRecords y PageNumber (5000 por página por defecto, página 1).

Scope OAuth : sms:contacts:read

Parámetros

Respuestas

Ejemplo 200

{
  "Items": [
    {
      "Id": 1001,
      "Number": "41791234567",
      "FirstName": "Alice",
      "LastName": "Dupont"
    },
    {
      "Id": 1002,
      "Number": "33612345678",
      "FirstName": "Bob",
      "LastName": "Martin"
    }
  ]
}

POST /phone/add.{format}

Añadir uno o varios números de teléfono a una lista

Añade uno o varios números de teléfono a una lista de contactos.

Número único: utilice el campo number.

Importación masiva: utilice el campo phone_list con los números separados por punto y coma: +41791234567;+33612345678;0049301234567

Los números de teléfono aceptan los formatos +, 00 o simple — consulte la Formato del número de teléfono en la descripción de la API para ver la lista completa de entradas aceptadas y rechazadas. Los números duplicados se omiten silenciosamente salvo que se establezca force=1.

Scope OAuth : sms:contacts:write

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

Ejemplo 200

{
  "Id": 1003,
  "Number": "0041791234567",
  "FirstName": "Alice",
  "LastName": "Dupont"
}

POST /phone/edit.{format}

Actualizar una entrada de número de teléfono

Actualiza el número de teléfono o los datos de contacto de una entrada existente. Utilice number_id (de /phone/list) para identificar la entrada que se va a actualizar. Solo se actualizan los campos proporcionados en la solicitud.

Scope OAuth : sms:contacts:write

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

POST /phone/del.{format}

Eliminar un número de teléfono de una lista

Elimina permanentemente una entrada de número de teléfono concreta de su lista de contactos. Utilice number_id (de /phone/list) para identificar la entrada.

Scope OAuth : sms:contacts:write

Parámetros

Cuerpo de la solicitud (application/x-www-form-urlencoded)

Respuestas

GET /credit/get.{format}

Obtener el saldo de créditos SMS

Devuelve el saldo actual de créditos SMS de su cuenta. Los créditos SMS se consumen en el momento del envío. Un SMS estándar (≤160 caracteres GSM-7) cuesta 1 crédito. Los mensajes más largos o los que contengan caracteres especiales pueden costar más.

> Nota: esto devuelve su saldo de créditos de envío de SMS, no su cuota de solicitudes de la API. > Para la cuota de la API consulte GET /account/limits.{format}.

Scope OAuth : sms:read

Parámetros

Respuestas

Ejemplo 200

{
  "TotalCredits": 5000
}

GET /history/list.{format}

Listar el historial de envíos de SMS

Devuelve un registro paginado de todas las campañas SMS pasadas enviadas desde esta cuenta. Los resultados se ordenan por fecha descendente (los más recientes primero). Paginación: NumberOfRecords y PageNumber (cabeceras o query, 5000 por página por defecto).

Scope OAuth : sms:read

Parámetros

Respuestas

Ejemplo 200

{
  "Items": [
    {
      "Id": 583294,
      "DateSent": "2026-07-17T18:56:39.813",
      "Message": "Your verification code is 8472",
      "Charge": 3,
      "Parts": 1
    }
  ]
}

POST /import/upload.{format}

Cargar un archivo de números de teléfono (CSV / XLSX) para importación masiva

Cargue un archivo CSV o XLSX para importar números de teléfono a una lista de contactos. El archivo se almacena y se pone en cola para procesarse de manera asíncrona — el endpoint devuelve inmediatamente un ImportJobId.

Tipo de solicitud: multipart/form-data

Campos de formulario obligatorios:

• id_client (entero) — su ID de cliente de Mailpro
• api_key (cadena) — su clave de API
• id_list (entero) — ID de la lista de contactos de destino
• file (binario) — el archivo CSV o XLSX que se va a cargar

Opcional:

• webhook_url (cadena) — URL HTTPS llamada cuando finaliza el procesamiento. Recibe una carga útil JSON con el estado final (success / failed) y los recuentos de filas importadas / omitidas / no válidas.

Formato del archivo:

• Codificado en UTF-8
• Primera fila = cabeceras (una debe ser Phone o PhoneNumber — sin distinción entre mayúsculas y minúsculas)
• Números en formato internacional (E.164), p. ej., +41791234567
• Tamaño máximo del archivo: 50 MB

Scope OAuth : sms:contacts:write

Parámetros

Cuerpo de la solicitud (multipart/form-data)

Respuestas

Ejemplo 200

{
  "Result": "OK",
  "ImportJobId": 15,
  "InternalName": "230575-20260420142616-phones.csv"
}

GET /webhooks

Listar webhooks

Devuelve todos los webhooks configurados en la cuenta autenticada.

Respuestas

Ejemplo 200

{
  "items": [
    {
      "id": 14,
      "url": "https://example.com/hooks/mailpro",
      "description": "Integración con Slack",
      "is_active": true,
      "created_at": "2026-07-01T21:09:52.43",
      "updated_at": "2026-07-21T18:56:08.02",
      "last_delivery_at": "2026-07-21T18:56:07.653",
      "last_delivery_status": 200,
      "consecutive_failures": 0,
      "events": [
        "sms.delivered",
        "sms.failed"
      ]
    }
  ],
  "total": 1
}

POST /webhooks

Crear un webhook

Crea una nueva suscripción de webhook. La respuesta contiene un secret que se muestra una sola vez — almacénelo inmediatamente en el lado del servidor. Utilícelo para verificar la firma HMAC de cada carga útil entrante.

Límites: máx. 20 webhooks por cuenta, máx. 50 eventos por webhook.

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Integración con Slack"
}

Respuestas

Ejemplo 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Integración con Slack",
  "isActive": true,
  "consecutiveFailures": 0,
  "autoDisabledAt": null,
  "autoDisabledReason": null,
  "createdAt": "2026-05-25T10:00:00Z",
  "updatedAt": "2026-05-25T10:00:00Z",
  "secret": "whsec_AbcD1234EfgH5678IjkL9012MnoP3456QrsT"
}

GET /webhooks/{id}

Obtener un webhook

Parámetros

Respuestas

PUT /webhooks/{id}

Actualizar un webhook

Actualización parcial — solo se modifican los campos enviados.

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

DELETE /webhooks/{id}

Eliminar un webhook

Elimina permanentemente el webhook y todo su historial de entregas.

Parámetros

Respuestas

POST /webhooks/{id}/test

Enviar un evento de prueba

Pone en cola un evento ping inmediato (o cualquier otro tipo de evento mediante el campo eventType del cuerpo) hacia su endpoint. Útil para comprobar la accesibilidad y la verificación de firma antes de depender de eventos reales.

Parámetros

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "eventType": "ping"
}

Respuestas

Ejemplo 202

{
  "deliveryId": 1234,
  "eventId": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
  "eventType": "ping"
}

POST /webhooks/{id}/rotate-secret

Rotar el secreto HMAC

Genera un nuevo secreto HMAC e invalida el anterior de inmediato. El nuevo secreto se devuelve una sola vez en la respuesta — almacénelo. Cada entrega a partir de ese momento se firmará con el nuevo secreto.

Utilícelo si sospecha que su secreto se ha visto comprometido.

Parámetros

Respuestas

Ejemplo 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /webhooks/{id}/deliveries

Listar los intentos de entrega

Devuelve el historial de intentos de despacho de este webhook (retención de 30 días). Útil para la depuración — qué eventos se enviaron, los códigos de estado recibidos, los recuentos de reintentos y los mensajes de error.

Parámetros

Respuestas

POST /webhooks/{id}/deliveries/{deliveryId}/replay

Reproducir una entrega

Pone en cola un nuevo intento de entrega con la misma carga útil que la original. Útil para volver a activar una entrega fallida tras corregir su endpoint. Se crea una NUEVA fila Webhook_Delivery (la original se conserva para auditoría). La reproducción sigue la política de reintentos estándar (mismo calendario de backoff, misma regla de desactivación automática tras 10 fallos).

Parámetros

Respuestas