Mailpro™ CRM API v3 : Referencia

POST /token

Obtener un token de acceso

Obtiene un token JWT Bearer mediante credenciales de cliente. Envía el access_token devuelto como Authorization: Bearer <token> en todas las solicitudes posteriores.

Tipos de concesión admitidos

Duración del token

• Token de acceso: 30 días
• Token de actualización: 90 días

Usa grant_type=refresh_token para obtener un token de acceso nuevo sin volver a autenticarte: tu SDK debería hacerlo automáticamente cuando al token de acceso le quede poco tiempo de validez (estrategia típica: actualizar cuando queden menos de 24 h).

Almacenamiento seguro de tokens

Incluso con una vigencia de 30 días, cualquier persona que obtenga un access_token puede suplantar a tu cuenta hasta que caduque. Almacena los tokens en un almacén de secretos del servidor (Vault, AWS Secrets Manager, Azure Key Vault, variables de entorno en un host bastionado). Nunca incrustes un token en:

• JavaScript del lado del cliente ni en cualquier paquete del navegador
• aplicaciones móviles distribuidas a los usuarios finales (el binario puede inspeccionarse)
• repositorios Git públicos ni registros de compilación de CI

Si se filtra un token, revócalo desde la configuración de tu cuenta de Mailpro y solicita uno nuevo.

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/Me

Obtener detalles de la cuenta

Devuelve los detalles del perfil y la configuración de la cuenta de Mailpro autenticada.

Respuestas

GET /Account/Credits

Obtener el saldo de créditos

Devuelve el saldo de créditos restantes de correo electrónico y SMS de la cuenta.

Respuestas

Ejemplo 200

{
  "email_credits": 48500,
  "sms_credits": 1200
}

GET /Account/SubscriptionEndDate

Obtener la fecha de fin de la suscripción

Devuelve la fecha de caducidad de la suscripción actual de Mailpro.

Respuestas

GET /Account/Limits

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, créditos_de_suscripción × 5). Para un plan de 10 000 correos/mes, esto genera un presupuesto mensual de 50 000 solicitudes. La correspondencia exacta la establece el proceso de facturación en el alta de la suscripción y 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 de v2, v3 o sms (cada llamada = 1 crédito, sea cual sea el resultado: tanto los 2xx como la mayoría de los errores de negocio 4xx cuentan).
• Cada evento de webhook enviado a un endpoint suscrito (p. ej. contact.created enviado a tu webhook suscrito = 1 crédito además de la llamada a la API que lo desencadenó).

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

• Los endpoints /health (monitorización).
• Las solicitudes que fallan con 401 (fallo de autenticación), 403 (prohibido) o 429 (limitadas por tasa).
• Los eventos de webhook para clientes sin suscripción coincidente (cortocircuito en caché: sin impacto en la cuota).

Respuestas

POST /Contact

Crear un contacto

Crea un nuevo contacto del CRM con campos personalizados, asignaciones de listas y etiquetas opcionales.

Obligatorio:

• email: debe ser único en la cuenta
• lists: al menos una asignación de lista es obligatoria

Los números de teléfono aceptan +41…, 0041… o 41… con o sin separadores (máx. 12 dígitos en Contact; consulta Formato del número de teléfono en la descripción de la API).

Los campos personalizados se identifican por su id (de GET /Field). Los valores se validan según el tipo del campo.

Scope OAuth : contacts:write

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "email": "[email protected]",
  "phone_number": "+41791234567",
  "lists": [
    {
      "id": 101
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ]
}

Respuestas

Ejemplo 406

{
  "Message": "Contact cannot be created. A contact already exist with the same Email"
}

POST /Contact/Multiple

Importar contactos (en masa)

Crea hasta 1000 contactos en una sola solicitud para una importación masiva eficiente. La respuesta incluye una lista de los contactos creados correctamente y una lista de errores correspondientes a los contactos que no se pudieron crear (p. ej. correo electrónico duplicado, datos no válidos).

Nota: las listas y etiquetas utilizadas en importaciones masivas no deben estar vinculadas a flujos de trabajo de automatización activos. Si lo están, toda la importación se rechaza con HTTP 406.

Scope OAuth : contacts:write

Cuerpo de la solicitud (application/json)

Ejemplo

[
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Alice"
      }
    ]
  },
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Bob"
      }
    ]
  }
]

Respuestas

Ejemplo 200

{
  "Added": [
    {
      "Email": "[email protected]",
      "Id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "Email": "[email protected]",
      "Id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "Errors": []
}

GET /Contact/{id}

Obtener un contacto

Devuelve los detalles de un contacto específico. Usa includeTags=true para devolver también las etiquetas asignadas al contacto. Usa includeLists=true para devolver también las listas a las que pertenece el contacto.

Scope OAuth : contacts:read

Parámetros

Respuestas

Ejemplo 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone_number": "41791234567",
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "lists": [
    {
      "id": 101
    }
  ]
}

PUT /Contact/{id}

Actualizar un contacto

Actualiza el correo electrónico, el número de teléfono, los campos personalizados, las asignaciones de listas y las etiquetas de un contacto. El cuerpo de la solicitud reemplaza los datos actuales del contacto: incluye todas las listas y etiquetas a las que quieras que el contacto siga estando asignado.

Obligatorio en el cuerpo: email y al menos una entrada lists.

Scope OAuth : contacts:write

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

Ejemplo 200

{
  "Result": "Successful operation"
}

DELETE /Contact/{id}

Eliminar un contacto

Elimina un contacto del CRM de forma permanente.

Scope OAuth : contacts:write

Parámetros

Respuestas

GET /Contact/{id}/Activity

Actividad de un contacto en 90 días

Correos recibidos, abiertos y con clics, cliente de correo preferido y últimas campañas del contacto.

Scope OAuth : contacts:read

Parámetros

Respuestas

Ejemplo 200

{
  "period_days": 90,
  "email_received": 12,
  "email_opened": 7,
  "email_clicked": 2,
  "favorite_email_client": "Gmail",
  "last_campaigns": [
    {
      "id": 5001,
      "name": "Spring Sale 2026",
      "date": "2026-10-01T09:00:00"
    }
  ]
}

PUT /Contact/{id}/Tag/{tagid}

Añadir etiqueta a contacto

Asigna una etiqueta a un contacto. Si la etiqueta ya está asignada, la operación no produce ningún efecto.

Scope OAuth : contacts:write

Parámetros

Respuestas

DELETE /Contact/{id}/Tag/{tagid}

Eliminar etiqueta de contacto

Elimina la asignación de una etiqueta de un contacto.

Scope OAuth : contacts:write

Parámetros

Respuestas

PUT /Contact/{id}/List/{listid}

Añadir contacto a lista

Añade un contacto a una lista concreta. Devuelve HTTP 404 si el contacto había cancelado previamente la suscripción a esta lista.

Scope OAuth : contacts:write

Parámetros

Respuestas

DELETE /Contact/{id}/List/{listid}

Eliminar contacto de una lista

Elimina un contacto de una lista concreta. El contacto en sí no se elimina.

Scope OAuth : contacts:write

Parámetros

Respuestas

GET /List

Listar las listas de contactos

Devuelve todas las listas de contactos de la cuenta. Filtra por nombre o fecha de creación. Ordena alfabéticamente con sortByName=true. Incluye el número total de contactos por lista con includeTotalContacts=true.

Scope OAuth : contacts:read

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 101,
    "name": "Newsletter subscribers",
    "total_contacts": 4521,
    "date_creation": "2025-01-15T10:30:00"
  }
]

POST /List

Crear una lista de contactos

Crea una nueva lista de contactos. Máximo 1000 listas por cuenta.

Scope OAuth : contacts:write

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "name": "Spring Campaign 2026"
}

Respuestas

Ejemplo 200

{
  "id": 102,
  "name": "Spring Campaign 2026",
  "date_creation": "2026-04-14T12:00:00"
}

GET /List/{id}

Obtener una lista de contactos

Devuelve los detalles de una lista de contactos concreta.

Scope OAuth : contacts:read

Parámetros

Respuestas

PUT /List/{id}

Actualizar una lista de contactos

Renombra una lista de contactos existente.

Scope OAuth : contacts:write

Parámetros

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "name": "Newsletter subscribers — Europe"
}

Respuestas

DELETE /List/{id}

Eliminar una lista de contactos

Elimina una lista de contactos de forma permanente. Los contactos en sí no se eliminan: solo se elimina su pertenencia a esta lista. Las listas utilizadas por flujos de trabajo de automatización activos no pueden eliminarse.

Scope OAuth : contacts:write

Parámetros

Respuestas

GET /List/{id}/Contact

Listar contactos de una lista

Devuelve los contactos que pertenecen a una lista concreta. Filtra por correo electrónico o fecha de adición. Incluye etiquetas y pertenencias a listas con los indicadores correspondientes.

Scope OAuth : contacts:read

Parámetros

Respuestas

GET /List/{listId}/Unsubscribers

Listar los que han cancelado la suscripción

Devuelve los contactos que han cancelado la suscripción a una lista concreta.

Scope OAuth : contacts:read

Parámetros

Respuestas

GET /Tag

Listar etiquetas

Devuelve todas las etiquetas de la cuenta.

Scope OAuth : contacts:read

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 5,
    "name": "VIP customers"
  },
  {
    "id": 6,
    "name": "Newsletter openers"
  }
]

POST /Tag

Crear una etiqueta

Crea una nueva etiqueta. Máximo 1000 etiquetas por cuenta.

Scope OAuth : contacts:write

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "name": "VIP customers"
}

Respuestas

GET /Tag/{id}

Obtener una etiqueta

Devuelve una etiqueta concreta por su ID.

Scope OAuth : contacts:read

Parámetros

Respuestas

PUT /Tag/{id}

Actualizar una etiqueta

Renombra una etiqueta existente.

Scope OAuth : contacts:write

Parámetros

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "name": "VIP customers — updated"
}

Respuestas

DELETE /Tag/{id}

Eliminar una etiqueta

Elimina una etiqueta de forma permanente. La etiqueta se elimina de todos los contactos. Las etiquetas utilizadas por flujos de trabajo de automatización activos no pueden eliminarse.

Scope OAuth : contacts:write

Parámetros

Respuestas

GET /Tag/{id}/Contact

Listar contactos con una etiqueta

Devuelve los contactos a los que se les ha asignado una etiqueta concreta.

Scope OAuth : contacts:read

Parámetros

Respuestas

GET /Field

Listar campos personalizados

Devuelve todos los campos personalizados de contacto definidos para la cuenta. Usa los valores id devueltos al crear o actualizar contactos.

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 1,
    "name": "first_name",
    "personalisation_key": "first_name",
    "field_type": "text"
  },
  {
    "id": 2,
    "name": "last_name",
    "personalisation_key": "last_name",
    "field_type": "text"
  }
]

POST /Field

Crear un campo personalizado

Crea un nuevo campo personalizado de contacto. Máximo 50 campos por cuenta. Usa el id devuelto al asignar valores a los contactos.

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "name": "First name",
  "id_field_type": 1,
  "personalize_key": "first_name"
}

Respuestas

GET /Field/Types

Listar los tipos de campo

Devuelve los identificadores de tipo de campo disponibles para usar al crear un campo personalizado. Tipos habituales: 1 = texto, 2 = número, 3 = fecha.

Respuestas

GET /Field/{id}

Obtener un campo personalizado

Devuelve la definición y los metadatos de un campo personalizado concreto.

Parámetros

Respuestas

PUT /Field/{id}

Actualizar un campo personalizado

Actualiza el nombre o la clave de personalización de un campo personalizado.

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

DELETE /Field/{id}

Eliminar un campo personalizado

Elimina un campo personalizado de forma permanente y borra su valor de todos los contactos. Esta acción no se puede deshacer.

Parámetros

Respuestas

GET /Campaign

Listar campañas

Devuelve una lista paginada de las campañas de correo electrónico de la cuenta.

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 8001,
    "title": "Spring Newsletter April 2026",
    "date_planned": "2026-04-20T09:00:01",
    "count_open": 1823,
    "count_sent": 4521,
    "count_click": 342,
    "count_badmail": 12,
    "count_unsubscription": 8,
    "count_clicking_users": 289,
    "count_complaints": 1,
    "spam_trap": 0,
    "deliverability_score": 98
  }
]

GET /Campaign/{id}

Obtener una campaña

Devuelve la configuración y el resumen de estadísticas de una campaña concreta.

Parámetros

Respuestas

PUT /Campaign/{id}

Actualizar una campaña

Actualiza el título o la fecha de envío de una campaña programada. Las campañas solo pueden modificarse hasta 5 minutos antes de la hora de envío programada.

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

DELETE /Campaign/{id}

Eliminar una campaña

Cancela y elimina permanentemente una campaña por su identificador.

Parámetros

Respuestas

GET /Campaign/Scheduled

Listar mis campañas programadas

Devuelve las campañas con date_planned en el futuro que aún no han sido enviadas. Ordenadas por date_planned de forma ascendente.

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 5001,
    "id_client": 12345,
    "subject": "Spring Sale 2026",
    "date_planned": "2026-05-01T09:00:00",
    "title": "Spring Sale",
    "id_campaign": 7001,
    "id_list": 101,
    "id_segment": null,
    "number_email": 1250
  }
]

POST /Campaign/{id}/Cancel

Cancelar una campaña programada

Cancela una campaña programada en el futuro. Devuelve 409 Conflict si la campaña ya se ha enviado o no existe.

Parámetros

Respuestas

Ejemplo 200

{
  "result": "ok",
  "cancelled": 5001
}

PATCH /Campaign/{id}/Reschedule

Reprogramar una campaña programada

Actualiza la fecha de envío prevista de una campaña programada. La nueva fecha debe estar en el futuro y dentro de los 90 días.

Nombre del campo en el cuerpo: la API acepta date_planned (snake_case, principal) así como los alias heredados PlanDate y scheduled_time. Proporciona uno cualquiera de ellos: se utiliza el primero que no sea nulo.

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

Ejemplo 200

{
  "result": "ok",
  "id": 5001,
  "date_planned": "2026-12-31T14:30:00"
}

GET /Campaign/{id}/ByHour

Estadísticas por hora

Devuelve el desglose por hora de aperturas y clics de la campaña.

Parámetros

Respuestas

GET /Campaign/{id}/ByDay

Estadísticas por día

Devuelve el desglose diario de aperturas y clics de la campaña.

Parámetros

Respuestas

GET /Campaign/{id}/Openings

Listar las aperturas de correo electrónico

Devuelve una lista paginada de los contactos que han abierto el correo electrónico de la campaña.

Parámetros

Respuestas

GET /Campaign/{id}/Clicks

Listar los clics en enlaces

Devuelve una lista paginada de los contactos que han hecho clic en un enlace de la campaña.

Parámetros

Respuestas

GET /Campaign/{id}/HardBounces

Listar los rebotes definitivos

Devuelve las direcciones de correo electrónico que han generado un rebote definitivo durante esta campaña.

Parámetros

Respuestas

GET /Campaign/{id}/Links

Listar los enlaces rastreados

Devuelve los datos de rendimiento de clics de cada enlace rastreado de la campaña.

Parámetros

Respuestas

GET /Campaign/{id}/OS

Estadísticas por SO / dispositivo

Devuelve el desglose de aperturas y clics por sistema operativo y tipo de dispositivo.

Parámetros

Respuestas

GET /Campaign/{id}/EmailClients

Estadísticas por cliente de correo electrónico

Devuelve el desglose de aperturas por cliente de correo electrónico (Gmail, Outlook, Apple Mail…).

Parámetros

Respuestas

GET /Campaign/{id}/Countries

Estadísticas por país

Devuelve la distribución geográfica de aperturas y clics.

Parámetros

Respuestas

POST /Send/Mail

Enviar correo electrónico transaccional

Envía un correo electrónico transaccional puntual a un único destinatario.

Destinatario: proporciona email (dirección en línea) O id_contact (contacto del CRM), no ambos. Usar id_contact habilita la personalización automática con los valores de los campos personalizados del contacto.

Contenido: proporciona body_html (HTML en línea) O id_message (plantilla guardada), no ambos. Si se proporcionan ambos, id_message tiene prioridad.

Obligatorio: id_sender_email, subject y uno de (email o id_contact), y uno de (body_html o id_message).

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "id_sender_email": 201,
  "email": "[email protected]",
  "subject": "Your order #12345 has shipped",
  "body_html": "<p>Hello {{first_name}}, your order is on its way!</p>",
  "reply_to": "[email protected]",
  "fields": [
    {
      "id": 1,
      "value": "Alice"
    }
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJVBERi0xLjQK..."
    }
  ]
}

Respuestas

Ejemplo 200

{
  "message": "Successful operation",
  "id_single_send": 8001
}

Ejemplo 404

{
  "Message": "Not enough credit available"
}

GET /Send/{id}/Status

Obtener el estado de entrega de un correo transaccional

Devuelve el estado de entrega actual de un correo transaccional enviado con POST /Send/Mail. Pase el id_single_send que devolvió esa llamada.

Valores posibles: delivered (aceptado por el servidor del destinatario, véase diag_code), bounced (rechazado — bounce_type: hard dirección no válida o rechazo definitivo, soft rechazo tras nuevos intentos), sent (entregado al servidor de correo, aún sin respuesta), scheduled (aún no enviado, date_planned en el futuro) y queued (en espera de envío). delivered y bounced son finales: deje de consultar. Cada email tiene un estado final como máximo 48 horas después del envío; consulte cada 15 minutos como máximo (cada llamada cuenta en su cuota de la API) o utilice los webhooks email.delivered / email.bounced. Solo el cliente que envió el email puede leer su estado — cualquier otro id devuelve 404.

Parámetros

Respuestas

Ejemplo 200

{
  "id_single_send": 8001,
  "email": "[email protected]",
  "status": "delivered",
  "date_planned": "2026-04-15T14:30:00",
  "status_date": "2026-04-15T14:30:07",
  "diag_code": "2.0.0 (success)",
  "bounce_type": null
}

POST /Send/Campaign

Enviar campaña de correo electrónico

Envía una campaña masiva de correo electrónico a una o varias listas de contactos.

Obligatorio:

• id_message: la plantilla que se va a enviar (de GET /Message)
• id_sender_email: la dirección del remitente (de GET /SenderEmail)
• lists: al menos una lista de contactos destinataria
• campaign_title: etiqueta para el seguimiento de estadísticas

Segmento: filtra opcionalmente a los destinatarios mediante un segmento guardado (id_segment). El segmento filtra los contactos dentro de las listas especificadas.

Programación: establece date_planned en una fecha/hora ISO 8601 futura. Las campañas pueden editarse o cancelarse hasta 5 minutos antes de la hora programada.

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "id_message": 501,
  "id_sender_email": 201,
  "lists": [
    {
      "id": 101
    }
  ],
  "campaign_title": "Spring Newsletter April 2026",
  "date_planned": "2026-04-20T09:00:00"
}

Respuestas

Ejemplo 200

{
  "Message": "Successful operation. Campaigns can be edited or deleted until 5 minutes prior to send.",
  "IdCampaign": 8001
}

GET /Send

Listar envíos programados

Devuelve la lista de campañas de correo electrónico pendientes de envío (programadas, aún no procesadas).

Parámetros

Respuestas

DELETE /Send/{id}

Cancelar un envío programado

Cancela y elimina un envío de correo electrónico programado que aún no se haya procesado. No se pueden cancelar envíos que se estén procesando en ese momento.

Parámetros

Respuestas

GET /Send/Mail/Scheduled

Listar los correos individuales programados

Devuelve los correos individuales enviados con POST /Send/Mail y una fecha futura que aún no han salido. Las campañas se listan con GET /Campaign/Scheduled.

Scope OAuth : email:send

Respuestas

Ejemplo 200

[
  {
    "id_single_send": 880123,
    "email": "[email protected]",
    "subject": "Your invoice",
    "date_planned": "2026-12-01T09:00:00"
  }
]

POST /Send/Mail/{id}/Cancel

Cancelar un correo individual programado

Cancela el correo mientras no haya salido.

Scope OAuth : email:send

Parámetros

Respuestas

Ejemplo 200

{
  "result": "ok",
  "cancelled": 880123
}

PATCH /Send/Mail/{id}/Reschedule

Reprogramar un correo individual programado

Cambia la fecha de envío. La nueva fecha debe ser futura y estar dentro de 90 días. También se acepta POST.

Scope OAuth : email:send

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

Ejemplo 200

{
  "result": "ok",
  "id": 880123,
  "date_planned": "2026-12-15T09:00:00"
}

GET /SenderEmail

Listar direcciones de remitente

Devuelve las direcciones de remitente validadas configuradas para la cuenta.

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 201,
    "email": "[email protected]",
    "sender_name": "Your Company Newsletter",
    "is_validated": true
  }
]

POST /SenderEmail

Añadir una dirección de remitente

Añade la dirección con los mismos controles que la aplicación y le envía un correo de validación. Se puede utilizar una vez que se haga clic en el enlace de ese correo. Una cuenta puede tener hasta 25 remitentes, validados o pendientes.

Scope OAuth : email:templates:write

Cuerpo de la solicitud (application/json)

Respuestas

Ejemplo 200

{
  "result": "ok",
  "confirmation_sent": true,
  "domain_has_mx": true
}

POST /SenderEmail/{id}/ResendValidation

Enviar de nuevo el correo de validación

Para una dirección que aún espera la validación.

Scope OAuth : email:templates:write

Parámetros

Respuestas

Ejemplo 200

{
  "result": "ok",
  "confirmation_sent": true
}

GET /SenderEmail/{id}/Authentication

Comprobar el dominio de un remitente (SPF, DKIM, DMARC, MX)

Comprueba el dominio en directo en el DNS y devuelve los registros que hay que publicar. Solo lectura. El DKIM se activa en la aplicación: dkim_settings_url abre la pantalla correcta.

Scope OAuth : email:templates:read

Parámetros

Respuestas

Ejemplo 200

{
  "domain": "example.com",
  "spf": {
    "valid": true,
    "record": "v=spf1 include:spf.mailpro.com -all",
    "recommended_record": "v=spf1 include:spf.mailpro.com -all",
    "change_needed": false
  },
  "dkim": {
    "valid": true,
    "records": [
      {
        "host": "key._domainkey.example.com",
        "value": "v=DKIM1;k=rsa;p=MIIBIjANBgkq...",
        "validated": true
      }
    ]
  },
  "dmarc": {
    "valid": true,
    "record": "v=DMARC1; p=quarantine"
  },
  "mx": {
    "valid": true,
    "record": "mail.example.com"
  },
  "dkim_settings_url": "https://app.mailpro.com/dkim/list?d=example.com"
}

GET /History/Email

Listar el historial de envíos de correo electrónico

Devuelve el registro de envíos de correo electrónico pasados de la cuenta.

Parámetros

Respuestas

GET /History/SMS

Listar el historial de envíos de SMS

Devuelve el registro de envíos de SMS pasados de la cuenta.

Parámetros

Respuestas

GET /Segment

Listar segmentos

Devuelve todos los segmentos dinámicos guardados de la cuenta.

Scope OAuth : contacts:read

Parámetros

Respuestas

GET /Segment/{id}/Contact

Listar los contactos de un segmento

Con id_list, devuelve solo los contactos de esa lista que entran en el segmento: los que alcanzaría una campaña lista + segmento. El total está en la cabecera X-Total-Count.

Scope OAuth : contacts:read

Parámetros

Respuestas

GET /Segment/{id}/Count

Contar los contactos de un segmento

Solo el número, para conocer de antemano el tamaño de un envío. Con id_list, cuenta solo los contactos de esa lista que entran en el segmento.

Scope OAuth : contacts:read

Parámetros

Respuestas

Ejemplo 200

{
  "total": 1250
}

GET /Segment/{id}/contact/{contactId}/check

Comprobar si un contacto coincide con un segmento

Comprueba si un contacto concreto (por GUID) coincide actualmente con las reglas de un segmento dado. Útil para activar lógica de automatización bajo demanda.

Scope OAuth : contacts:read

Parámetros

Respuestas

POST /Sms/SingleSMS

Enviar un único SMS

Envía un único SMS a un número de teléfono directamente. Útil para mensajes transaccionales (OTP, confirmaciones de pedido, alertas). El número de teléfono acepta +41…, 0041… o 41… con o sin separadores; consulta Formato del número de teléfono en la descripción de la API para ver las entradas aceptadas/rechazadas.

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "phone_number": "+41791234567",
  "message": "Your verification code is 9473. Valid for 10 minutes."
}

Respuestas

POST /Sms/Campaign

Enviar campaña de SMS

Envía un mensaje SMS al campo phone_number de todos los contactos de una o varias listas. Los contactos sin número de teléfono se omiten.

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "lists": [
    {
      "id": 101
    }
  ],
  "message": "Flash sale today — 20% off. Shop at mailpro.com",
  "date_planned": "2026-04-20T10:00:00"
}

Respuestas

GET /Sms

Listar el historial de SMS

Devuelve el registro de envíos de SMS (tanto individuales como de campaña) de la cuenta.

Parámetros

Respuestas

DELETE /Sms/{id}

Cancelar un SMS programado

Cancela un envío de SMS programado pendiente.

Parámetros

Respuestas

GET /Sms/Scheduled

Listar envíos de SMS programados

Devuelve los envíos de SMS con un date_planned futuro (aún no enviados), ordenados por fecha de forma ascendente.

Parámetros

Respuestas

POST /Sms/{id}/Cancel

Cancelar un SMS programado

Cancela un envío de SMS programado solo si aún no ha sido enviado.

Parámetros

Respuestas

PATCH /Sms/{id}/Reschedule

Reprogramar un SMS programado

Actualiza la fecha de envío prevista de un SMS programado. La nueva fecha debe estar en el futuro y dentro de los 90 días. Falla si el SMS ya ha sido enviado.

Nombre del campo en el cuerpo: la API acepta date_planned (snake_case, principal) así como los alias heredados PlanDate y scheduled_time. Proporciona uno cualquiera de ellos.

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

GET /FolderList

Listar las carpetas de listas

Devuelve las carpetas utilizadas para organizar las listas de contactos.

Parámetros

Respuestas

GET /FolderList/{id}

Obtener una carpeta de listas

Devuelve los detalles de una carpeta de listas por su ID.

Parámetros

Respuestas

GET /FolderMessage

Listar carpetas de mensajes

Devuelve las carpetas utilizadas para organizar las plantillas de mensajes de correo electrónico.

Parámetros

Respuestas

POST /Import/Upload

Subir un archivo de contactos (CSV / XLSX) para una importación masiva

Sube un archivo CSV o XLSX para importar contactos a una lista. El archivo se almacena y se pone en cola para su procesamiento asíncrono: el endpoint devuelve un import_job_id de inmediato.

Tipo de solicitud: multipart/form-data

Campos de formulario obligatorios:

• id_list (entero): ID de la lista de destino
• file (binario): el archivo CSV o XLSX que se va a subir
• json_match_fields (cadena, JSON): qué columna del archivo va a qué campo del contacto. email_position = columna del e-mail, numerada desde 0 (obligatorio), phone_position = columna del número de móvil o -1, fields = ID de los demás campos (ver GET /Field), fields_position = columna de cada uno de ellos, update_fields = actualizar los contactos existentes. Correspondencia ausente o no válida: respuesta 400, no se crea ninguna importación.

Opcional:

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

Formato de archivo:

• Codificado en UTF-8
• La primera fila puede contener los encabezados (detección automática: una primera fila sin ninguna dirección de e-mail se omite)
• Las columnas se asignan a los campos mediante json_match_fields
• Tamaño máximo de archivo: 50 MB

Cuerpo de la solicitud (multipart/form-data)

Respuestas

Ejemplo 200

{
  "result": "OK",
  "import_job_id": 14,
  "internal_name": "230575-20260420142615-contacts.csv"
}

GET /Webhook

Listar webhooks

Devuelve todos los webhooks configurados en la cuenta autenticada.

Respuestas

POST /Webhook

Crear un webhook

Crea una nueva suscripción a webhook. La respuesta contiene un secret que solo se muestra una vez: guárdalo de inmediato en el servidor. Úsalo para verificar la firma HMAC de todas las cargas útiles entrantes.

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

Cuerpo de la solicitud (application/json)

Ejemplo

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Integración con Slack"
}

Respuestas

Ejemplo 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "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 /Webhook/{id}

Obtener un webhook

Parámetros

Respuestas

PUT /Webhook/{id}

Actualizar un webhook

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

Parámetros

Cuerpo de la solicitud (application/json)

Respuestas

DELETE /Webhook/{id}

Eliminar un webhook

Elimina permanentemente el webhook y todo su historial de entregas.

Parámetros

Respuestas

POST /Webhook/{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) a tu punto de conexión. Útil para verificar 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 /Webhook/{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: guárdalo. Todas las entregas a partir de ese momento se firmarán con el nuevo secreto.

Utiliza esta opción si sospechas que tu secreto ha sido comprometido.

Parámetros

Respuestas

Ejemplo 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /Webhook/{id}/deliveries

Listar intentos de entrega

Devuelve el historial de intentos de envío de este webhook (retención de 30 días). Útil para depuración: qué eventos se enviaron, qué códigos de estado se recibieron, recuentos de reintentos, mensajes de error.

Parámetros

Respuestas

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

Reproducir una entrega

Pone en cola un nuevo intento de entrega con la misma carga útil que el original. Útil para volver a desencadenar una entrega fallida tras corregir tu punto de conexión. Se crea una NUEVA fila Webhook_Delivery (el original se conserva con fines de auditoría). La reproducción sigue la política de reintentos estándar (10s → 1min → 5min → 30min → 2h → 6h → 24h, después se abandona).

Parámetros

Respuestas

GET /Suppression/Bounces

Listar los rebotes de la cuenta

Los más recientes primero. El total está en la cabecera X-Total-Count.

Scope OAuth : email:read

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 5521,
    "source": "contact",
    "type": "hard",
    "email": "[email protected]",
    "date": "2026-10-12T08:30:00",
    "diag_code": "550 5.1.1 User unknown",
    "id_list": 101
  }
]

DELETE /Suppression/Bounces/{id}

Eliminar un rebote

source y type son obligatorios, tal como los devuelve GET /Suppression/Bounces: un id por sí solo no es único.

Scope OAuth : contacts:write

Parámetros

Respuestas

Ejemplo 200

{
  "result": "ok",
  "id": 5521,
  "restored": false
}

POST /Suppression/Bounces/{id}/Restore

Volver a poner en sus listas un contacto con rebote duro

Solo para un rebote duro con el origen contact.

Scope OAuth : contacts:write

Parámetros

Respuestas

Ejemplo 200

{
  "result": "ok",
  "id": 5521,
  "restored": true
}

GET /Suppression/Unsubscribers

Listar las bajas de la cuenta

Los más recientes primero. El total está en la cabecera X-Total-Count.

Scope OAuth : contacts:read

Parámetros

Respuestas

Ejemplo 200

[
  {
    "id": 9012,
    "source": "api3",
    "email": "[email protected]",
    "date": "2026-10-20T16:05:00",
    "list_name": null,
    "comment": "Asked by phone"
  }
]

POST /Suppression/Unsubscribers

Añadir una baja

Sin id_list, la dirección se da de baja de toda la cuenta. Con id_list, solo de esa lista de bajas.

Scope OAuth : contacts:write

Cuerpo de la solicitud (application/json)

Respuestas

Ejemplo 200

{
  "result": "ok",
  "already_unsubscribed": false
}

DELETE /Suppression/Unsubscribers/{id}

Eliminar una baja

source es obligatorio, tal como lo devuelve GET /Suppression/Unsubscribers: un id por sí solo no es único.

Scope OAuth : contacts:write

Parámetros

Respuestas

Ejemplo 200

{
  "result": "ok",
  "removed": 9012
}