Mailtrap

oficial

Se integra con la API de correo electrónico de Mailtrap.

GitHub
65
Prueba este MCPPatrocinado

¿Qué puedes hacer con Mailtrap MCP?

  • Enviar correos transaccionales — Pídele a tu asistente que envíe un correo transaccional con contenido inline o una plantilla mediante send-email.
  • Probar correos en sandbox — Envía correos de prueba a una bandeja de entrada sandbox e inspecciona el contenido, las puntuaciones de spam y el análisis HTML.
  • Monitorear registros de entrega — Busca en los registros de correo e inspecciona el historial de eventos para depurar problemas de entrega con list-email-logs.
  • Gestionar plantillas de correo — Crea, lista, actualiza o elimina plantillas usando comandos en lenguaje natural.
  • Analizar estadísticas de envío — Obtén tasas de entrega, rebote, apertura y clics para cualquier rango de fechas con get-sending-stats.
  • Gestionar dominios de envío — Lista, crea y configura dominios de envío con verificación DNS y seguimiento de clics.

Documentación

TypeScript test NPM

Servidor MCP Oficial de Mailtrap

El servidor MCP oficial para Mailtrap — la plataforma de entrega de correo electrónico. Conecta tu cuenta de Mailtrap a Claude, Cursor, VS Code y otros asistentes de IA compatibles con MCP.

Envía correos transaccionales y masivos, prueba mensajes de forma segura en Email Sandbox, gestiona plantillas, contactos, dominios de envío y webhooks, inspecciona registros de correo y estadísticas de entrega, soluciona problemas de entregabilidad y gestiona recursos de la cuenta — todo usando instrucciones en lenguaje natural.

Capacidades

  • Email API y SMTP — Envía correos transaccionales y masivos, incluidos mensajes por lotes y basados en plantillas.
  • Pruebas de correo — Prueba mensajes en Email Sandbox e inspecciona contenido, encabezados, adjuntos, puntuaciones de spam y compatibilidad con clientes HTML.
  • Monitoreo de entrega — Busca registros de correo, inspecciona el historial de eventos y analiza tasas de entrega, rebotes, aperturas, clics y spam.
  • Infraestructura de correo — Gestiona dominios de envío, verificación DNS, webhooks y supresiones.
  • Contactos — Gestiona contactos, listas, campos personalizados y eventos, con importaciones y exportaciones.
  • Gestión de cuenta — Revisa el uso de facturación y gestiona accesos, permisos, tokens de API y subcuentas.

Clientes MCP Compatibles

Funciona con Claude Desktop, Claude Code, Cursor, VS Code y cualquier otro cliente compatible con MCP. Las instrucciones de configuración para cada uno están a continuación.

Requisitos previos

Antes de usar este servidor MCP, necesitas:

  1. Crear una cuenta de Mailtrap
  2. Verificar tu dominio
  3. Obtener tu token de API desde Configuración de API de Mailtrap
  4. Obtener tu ID de cuenta desde Gestión de cuenta de Mailtrap

Variables de entorno requeridas:

  • MAILTRAP_API_TOKEN - Requerida para toda la funcionalidad
  • MAILTRAP_ACCOUNT_ID - Requerida para plantillas, estadísticas, registros de correo, listado/visualización de sandbox, dominios de envío y supresiones. Opcional solo para las herramientas de envío (send-email, send-sandbox-email y las herramientas batch-send-*), las herramientas de campañas de correo, las herramientas de información de empresa y las herramientas de exclusión de seguimiento.

Opcionales (se pueden pasar como parámetros de herramienta en su lugar):

  • DEFAULT_FROM_EMAIL - Correo de remitente predeterminado cuando from no se proporciona a send-email, send-sandbox-email o las herramientas batch-send-* (donde completa base.from). Permite cambiar el remitente por llamada mediante el parámetro from.
  • MAILTRAP_SANDBOX_ID - ID de sandbox predeterminado para herramientas de sandbox cuando sandbox_id no se proporciona. Permite cambiar entre sandboxes por llamada mediante el parámetro sandbox_id.
  • MAILTRAP_TEST_INBOX_ID - ID de bandeja de entrada de prueba predeterminado para herramientas de sandbox cuando test_inbox_id no se proporciona. Permite cambiar entre bandejas de entrada por llamada mediante el parámetro test_inbox_id. Alias heredado de MAILTRAP_SANDBOX_ID, aún se respeta como respaldo.
  • MAILTRAP_ORGANIZATION_ID - Requerida para herramientas de organización (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Token de API con alcance de organización. Requerido para herramientas de organización (separado de MAILTRAP_API_TOKEN).

Instalación rápida

Install in Cursor

Install with Node in VS Code

CLI de Smithery

Smithery es un instalador y gestor de registros para servidores MCP que funciona con todos los clientes de IA.

npx @smithery/cli install mailtrap

Smithery maneja automáticamente la configuración del cliente y proporciona un proceso de configuración interactivo. Es la forma más fácil de comenzar con servidores MCP localmente.

Configuración

Claude Desktop

Usa MCPB para instalar el servidor de Mailtrap. Puedes encontrar esos archivos en Releases.
Descarga el archivo .MCPB y ábrelo. Si tienes Claude Desktop, lo abrirá y sugerirá configurarlo.

Claude Desktop o Cursor

Agrega la siguiente configuración:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Si usas asdf para gestionar Node.js, debes usar la ruta absoluta al ejecutable (ejemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Ubicación del archivo de configuración de Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Ubicación del archivo de configuración de Cursor

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Cambio manual de configuración

Ejecuta en la Paleta de comandos: Preferences: Open User Settings (JSON)

Luego, en el archivo de configuración, agrega la siguiente configuración:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] No olvides reiniciar tu servidor MCP después de cambiar la sección "env".

Paquete MCP (MCPB)

Para una instalación fácil en hosts que admiten paquetes MCP, puedes distribuir un archivo de paquete .mcpb.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

Esto crea mailtrap-mcp.mcpb usando el repositorio manifest.json y artefactos compilados en dist/.

Uso

Una vez configurado, puedes pedirle al agente que envíe correos y gestione plantillas, por ejemplo:

Operaciones de envío de correo:

  • "Envía un correo a john.doe@example.com con el asunto 'Reunión mañana' y un recordatorio amable sobre nuestra próxima reunión."
  • "Envía un correo a sarah@example.com sobre la actualización del proyecto y copia al equipo en team@example.com"
  • "Envía la plantilla de bienvenida (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) a new@example.com con las variables { name: 'Alex' }"
  • "Envía un correo de sandbox a test@example.com con el asunto 'Plantilla de prueba' para previsualizar cómo se ve nuestro correo de bienvenida"

Registros de correo (depuración de entrega):

  • "Lista mis registros de correo enviados recientes"
  • "Muestra los registros de correo de los correos enviados a user@example.com"
  • "Obtén el mensaje del registro de correo para el ID abc-123-uuid para verificar el estado de entrega"

Estadísticas de envío:

  • "Obtén estadísticas de envío para enero de 2025"
  • "Muestra las tasas de entrega desglosadas por dominio del último mes"
  • "¿Cuáles son mis estadísticas de correo por categoría del 2025-01-01 al 2025-01-31?"

Operaciones de sandbox:

  • "Obtén todos los mensajes de mi bandeja de entrada de sandbox"
  • "Muéstrame la primera página de mensajes de sandbox"
  • "Busca mensajes que contengan 'test' en mi bandeja de entrada de sandbox"
  • "Muéstrame los detalles del mensaje de sandbox con ID 5159037506"

Operaciones de plantillas:

  • "Lista todas las plantillas de correo en mi cuenta de Mailtrap"
  • "Crea una nueva plantilla de correo llamada 'Correo de bienvenida' con el asunto '¡Bienvenido a nuestra plataforma!'"
  • "Actualiza la plantilla con ID 12345 para cambiar el asunto a 'Mensaje de bienvenida actualizado'"
  • "Elimina la plantilla con ID 67890"

Dominios de envío:

  • "Lista mis dominios de envío"
  • "Obtén el dominio de envío con ID 3938"
  • "Crea un dominio de envío para example.com"
  • "Activa el seguimiento de clics para el dominio de envío 3938"
  • "Elimina el dominio de envío 3938"
  • "Obtén el dominio de envío 3938 con instrucciones de configuración DNS"
  • "Muestra la información de empresa para el dominio de envío 3938"
  • "Establece la información de empresa para el dominio 3938 como Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
  • "Cambia la ciudad de la información de empresa para el dominio 3938 a Nueva York"

Supresiones:

Exclusiones de seguimiento:

  • "Deja de rastrear aperturas y clics para privacy@example.com en el dominio 3938"
  • "Lista a todos los que optaron por no participar en el seguimiento"

Contactos y listas:

  • "Agrega john.doe@example.com a mi lista de contactos de boletín"
  • "Muéstrame todas mis listas de contactos"
  • "Crea un campo de contacto llamado 'signup_source' para rastrear de dónde provienen los contactos"
  • "Actualiza el contacto john.doe@example.com para establecer su plan como 'pro'"
  • "Importa contactos de este CSV a mi lista de incorporación"
  • "Exporta todos los contactos de mi lista de boletín"
  • "Registra un evento 'trial_started' para el contacto john.doe@example.com"

Webhooks:

  • "Lista todos los webhooks configurados en mi cuenta"
  • "Crea un webhook que apunte a https://example.com/hooks/mailtrap para eventos de rebote y spam"
  • "Actualiza el webhook 4821 para que también envíe eventos de entrega"
  • "Elimina el webhook 4821"

Cuenta y facturación:

  • "¿Cuál es mi uso de facturación actual este mes?"
  • "¿Cuántos correos me quedan en mi plan?"
  • "Lista a todos los que tienen acceso a esta cuenta de Mailtrap"
  • "Muéstrame los recursos de permisos disponibles en mi cuenta"

Tokens de API:

  • "Lista todos los tokens de API en mi cuenta"
  • "Crea un nuevo token de API para el entorno de staging"
  • "Restablece el token de API con ID 1234"
  • "Elimina el token de API no utilizado 1234"

Organización y subcuentas:

  • "Lista todas las subcuentas en mi organización"
  • "Crea una nueva subcuenta para el proyecto del cliente 'Acme Corp'"

Herramientas disponibles

send-email

Envía un correo transaccional a través de Mailtrap. Admite dos modos mutuamente excluyentes: contenido en línea (subject + text/html) o basado en plantillas (template_uuid).

Parámetros:

  • from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo simple en tiempo de ejecución). Si no se proporciona, se usa DEFAULT_FROM_EMAIL.
  • to (opcional): Matriz de destinatarios como objetos { email, name? } (también se aceptan cadenas de correo simples o una sola dirección no matricial en tiempo de ejecución). Opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
  • cc (opcional): Matriz de destinatarios CC como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
  • bcc (opcional): Matriz de destinatarios CCO como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
  • subject (condicional): Línea de asunto del correo. Requerida para envíos en línea; debe omitirse cuando template_uuid está establecido.
  • text (condicional): Texto del cuerpo del correo. Requerido (junto con o en lugar de html) para envíos en línea; debe omitirse cuando template_uuid está establecido.
  • html (condicional): Versión HTML del cuerpo del correo. Requerida (junto con o en lugar de text) para envíos en línea; debe omitirse cuando template_uuid está establecido.
  • category (opcional): Categoría del correo para seguimiento y análisis. Debe omitirse cuando template_uuid está establecido.
  • template_uuid (opcional): Usa una plantilla de correo de Mailtrap en lugar de contenido en línea. Cuando se establece, subject / text / html / category deben omitirse (según la API de Mailtrap).
  • template_variables (opcional): Objeto de variables sustituidas en la plantilla referenciada por template_uuid. Solo se permite junto con template_uuid.

batch-send-transactional-email

Envía un lote de correos transaccionales en una sola llamada a la API de Mailtrap (flujo de envío predeterminado). Los campos compartidos van en base; las anulaciones por destinatario van en requests[]. Cada solicitud debe incluir al menos un destinatario mediante to, cc o bcc. Misma exclusión mutua en línea-vs-plantilla que send-email — verificada después de fusionar la base con cada solicitud.

Parámetros:

  • base (opcional): Objeto con campos compartidos en todo el lote.
    • from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo simple en tiempo de ejecución). Se recurre a DEFAULT_FROM_EMAIL si no se proporciona.
    • reply_to (opcional): Dirección de respuesta (reply-to).
    • subject / text / html / category (opcional, modo inline): Contenido predeterminado para cada solicitud.
    • template_uuid / template_variables (opcional, modo plantilla): Plantilla y variables predeterminadas. Mutuamente excluyentes con los campos inline.
    • custom_variables (opcional): Variables personalizadas predeterminadas (con valores de cadena).
    • headers (opcional): Encabezados personalizados predeterminados.
  • requests (obligatorio): Matriz no vacía de mensajes por destinatario. Cada entrada tiene:
    • to (opcional): Matriz de destinatarios como objetos { email, name? } (también se aceptan cadenas de correo simples o una única dirección no matricial en tiempo de ejecución). Opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
    • cc, bcc, reply_to (opcional).
    • Anulaciones inline (subject/text/html/category) o de plantilla (template_uuid/template_variables); cualquier campo omitido recurre al valor base correspondiente.
    • custom_variables, headers (opcional).

batch-send-bulk-email

Envía un lote de correos masivos a través de la API de flujo masivo (bulk-stream) de Mailtrap. Misma forma base + requests[], validación y reglas inline-vs-plantilla que batch-send-transactional-email — la única diferencia es que esta herramienta enruta la llamada a través del endpoint masivo en lugar del transaccional. Consulta los parámetros anteriores.

list-email-logs

Lista los registros de correos enviados (historial de entrega) con paginación y filtros opcionales. Úsalo para depurar problemas de entrega desde el IDE.

Parámetros:

  • search_after (opcional): Cursor de paginación de la respuesta anterior en next_page_cursor
  • sent_after (opcional): Fecha/hora ISO 8601; solo registros enviados después de esta hora
  • sent_before (opcional): Fecha/hora ISO 8601; solo registros enviados antes de esta hora
  • from_email (opcional): Filtrar por correo del remitente; usar con from_operator (predeterminado: ci_equal)
  • to_email (opcional): Filtrar por correo del destinatario; usar con to_operator (predeterminado: ci_equal)
  • status (opcional): Filtrar por estado de entrega: delivered, not_delivered, enqueued, opted_out; usar con status_operator (predeterminado: equal)
  • subject (opcional): Filtrar por asunto del correo; usar con subject_operator (predeterminado: ci_contain). Usa subject_operator: empty/not_empty para filtrar por presencia de asunto.
  • sending_domain_id (opcional): Filtrar por ID de dominio de envío (número); usar con sending_domain_id_operator (predeterminado: equal)
  • sending_stream (opcional): Filtrar por flujo: transactional o bulk; usar con sending_stream_operator (predeterminado: equal)
  • events (opcional): Filtrar por tipo(s) de evento: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; usar con events_operator (include_event / not_include_event)
  • clicks_count / opens_count (opcional): Filtrar por recuento de clics/aperturas; usar con *_operator: equal, greater_than, less_than
  • client_ip / sending_ip (opcional): Filtrar por IP; usar con *_operator: equal, not_equal, contain, not_contain
  • email_service_provider_response (opcional): Filtrar por texto de respuesta del proveedor; usar con *_operator (ci_contain, etc.)
  • email_service_provider (opcional): Filtrar por proveedor (exacto); usar con *_operator: equal, not_equal
  • recipient_mx (opcional): Filtrar por MX del destinatario; usar con recipient_mx_operator (ci_contain, etc.)
  • category (opcional): Filtrar por categoría de correo; usar con category_operator: equal, not_equal

Todos los parámetros son opcionales.

get-email-log-message

Obtiene un único mensaje de registro de correo por ID (UUID): un resumen legible (de, para, asunto, hora de envío, estado, categoría, flujo, interacción, contexto de entrega) y luego el historial detallado de eventos. Opcionalmente, con include_content: true, también puedes cargar y mostrar el cuerpo del mensaje (HTML y texto plano) cuando Mailtrap expone una URL de mensaje sin procesar.

Parámetros:

  • message_id (obligatorio): UUID del mensaje de registro de correo (de la respuesta de envío o de list-email-logs). Usa list-email-logs para encontrar los ID de mensajes.
  • include_content (opcional): Cuando true, obtiene el EML sin procesar (si raw_message_url está disponible) y añade secciones analizadas del cuerpo HTML y de texto plano, similar a show-sandbox-email-message.

get-sending-stats

Obtén estadísticas de envío de correos (tasas de entrega, rebote, apertura, clics y spam) para un rango de fechas. Opcionalmente, desglosa por dominio, categoría, proveedor de servicios de correo o fecha. Comprueba las tasas de entrega sin salir del editor.

Parámetros:

  • start_date (obligatorio): Fecha de inicio del rango de estadísticas (AAAA-MM-DD)
  • end_date (obligatorio): Fecha de fin del rango de estadísticas (AAAA-MM-DD)
  • breakdown (opcional): Cómo desglosar las estadísticas: aggregated (predeterminado), by_domain, by_category, by_email_service_provider o by_date
  • sending_domain_ids (opcional): Limitar resultados a estos ID de dominio de envío (matriz de enteros)
  • sending_streams (opcional): Limitar a transactional y/o bulk (matriz de cadenas)
  • categories (opcional): Limitar a estas categorías de correo (matriz de cadenas)
  • email_service_providers (opcional): Limitar a estos proveedores, p. ej., Google, Yahoo, Outlook (matriz de cadenas)

create-template

Crea una nueva plantilla de correo en tu cuenta de Mailtrap.

Parámetros:

  • name (obligatorio): Nombre de la plantilla
  • subject (obligatorio): Línea de asunto del correo
  • html (o text es obligatorio): Contenido HTML de la plantilla
  • text (o html es obligatorio): Versión en texto plano de la plantilla
  • category (opcional): Categoría de la plantilla (predeterminado: "General")

list-templates

Lista todas las plantillas de correo en tu cuenta de Mailtrap.

Parámetros:

  • No se requieren parámetros

get-template

Obtén una única plantilla de correo por ID, incluidos asunto, categoría y cuerpo HTML/texto.

Parámetros:

  • template_id (obligatorio): ID de la plantilla a obtener

update-template

Actualiza una plantilla de correo existente.

Parámetros:

  • template_id (obligatorio): ID de la plantilla a actualizar
  • name (opcional): Nuevo nombre para la plantilla
  • subject (opcional): Nueva línea de asunto del correo
  • html (opcional): Nuevo contenido HTML de la plantilla
  • text (opcional): Nueva versión en texto plano de la plantilla
  • category (opcional): Nueva categoría para la plantilla

[!NOTE] Se debe proporcionar al menos un campo actualizable (nombre, asunto, html, texto o categoría) al llamar a update-template para realizar una actualización.

delete-template

Elimina una plantilla de correo existente.

Parámetros:

  • template_id (obligatorio): ID de la plantilla a eliminar

send-sandbox-email

Envía un correo a tu bandeja de entrada de prueba de Mailtrap con fines de desarrollo y pruebas. Es perfecto para probar plantillas de correo sin enviar mensajes a destinatarios reales. Admite los mismos dos modos que send-email — contenido inline o basado en plantilla (template_uuid).

Parámetros:

  • test_inbox_id (opcional): ID de la bandeja de entrada de prueba de Mailtrap. Obligatorio a menos que se establezca MAILTRAP_TEST_INBOX_ID; pásalo en cada llamada para apuntar a una bandeja específica.
  • from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo simple en tiempo de ejecución). Si no se proporciona, se usa DEFAULT_FROM_EMAIL.
  • to (opcional): Matriz de destinatarios como objetos { email, name? } (también se aceptan cadenas de correo simples en la matriz, o una cadena separada por comas de correos simples, en tiempo de ejecución). Opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
  • cc (opcional): Matriz de destinatarios CC como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
  • bcc (opcional): Matriz de destinatarios CCO como objetos { email, name? } (también se aceptan cadenas de correo simples en tiempo de ejecución).
  • subject (condicional): Línea de asunto del correo. Obligatoria para envíos inline; debe omitirse cuando se establece template_uuid.
  • text (condicional): Texto del cuerpo del correo. Obligatorio (junto con html o en su lugar) para envíos inline; debe omitirse cuando se establece template_uuid.
  • html (condicional): Versión HTML del cuerpo del correo. Obligatoria (junto con text o en su lugar) para envíos inline; debe omitirse cuando se establece template_uuid.
  • category (opcional): Categoría del correo para seguimiento. Debe omitirse cuando se establece template_uuid.
  • template_uuid (opcional): Usa una plantilla de correo de Mailtrap en lugar de contenido inline. Cuando se establece, subject / text / html / category deben omitirse.
  • template_variables (opcional): Objeto de variables sustituidas en la plantilla referenciada por template_uuid. Solo se permite junto con template_uuid.

batch-send-sandbox-email

Envía un lote de correos a tu bandeja de entrada de prueba de Mailtrap en una sola llamada a la API, sin entregarlos a destinatarios reales. Misma forma base + requests[], validación y reglas inline-vs-plantilla que batch-send-transactional-email — la diferencia es que esta herramienta enruta la llamada a través del endpoint de sandbox para una única bandeja de prueba.

Parámetros:

  • sandbox_id (opcional): ID del sandbox (bandeja de prueba) de Mailtrap. Obligatorio a menos que se establezca MAILTRAP_SANDBOX_ID; pásalo en cada llamada para apuntar a un sandbox específico.
  • base (opcional), requests (obligatorio): Consulta batch-send-transactional-email anteriormente.

[!NOTE] Para las herramientas de sandbox, proporciona test_inbox_id en la llamada a la herramienta o establece la variable de entorno MAILTRAP_TEST_INBOX_ID. Puedes cambiar entre bandejas por llamada pasando test_inbox_id. Las herramientas que toman sandbox_id usan MAILTRAP_SANDBOX_ID primero.

get-sandbox-messages

Recupera una lista de mensajes de tu bandeja de entrada de prueba de Mailtrap. Útil para comprobar qué correos se han recibido en tu sandbox durante las pruebas.

Parámetros:

  • page (opcional): Número de página para la paginación (mínimo: 1)
  • last_id (opcional): Paginación usando el último ID de mensaje. Devuelve mensajes después del ID de mensaje especificado (mínimo: 1)
  • search (opcional): Consulta de búsqueda para filtrar mensajes

[!NOTE] Todos los parámetros son opcionales. Si no se proporciona ninguno, se devolverá la primera página de mensajes de la bandeja. Usa page para paginación tradicional, last_id para paginación basada en cursor, o search para filtrar mensajes por contenido.

show-sandbox-email-message

Muestra información detallada y contenido de un mensaje de correo específico de tu bandeja de entrada de prueba de Mailtrap, incluido el contenido del cuerpo HTML y de texto.

Parámetros:

  • message_id (obligatorio): ID del mensaje de correo del sandbox a recuperar

[!NOTE] Usa get-sandbox-messages primero para obtener la lista de mensajes y sus ID, y luego usa esta herramienta para ver el contenido completo de un mensaje específico.

get-sandbox-project

Obtén un proyecto de sandbox por ID, incluidas sus bandejas de entrada y recuentos de correos.

Parámetros:

  • project_id (obligatorio): ID del proyecto a obtener

update-sandbox-project

Cambia el nombre de un proyecto de sandbox existente.

Parámetros:

  • project_id (obligatorio): ID del proyecto a actualizar
  • name (obligatorio): Nuevo nombre para el proyecto (2–100 caracteres)

list-sandboxes

Lista todos los sandboxes accesibles con el token de API en todos los proyectos.

Parámetros:

  • No se requieren parámetros

mark-sandbox-as-read

Marca todos los mensajes de un sandbox como leídos.

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox sobre el que actuar

reset-sandbox-credentials

Restablece las credenciales SMTP para un sandbox. Devuelve el nuevo nombre de usuario/contraseña.

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox sobre el que actuar

enable-sandbox-email-address

Habilita la dirección de recepción por correo electrónico para un sandbox (activa la dirección de Mailtrap que entrega mensajes al sandbox mediante SMTP).

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox sobre el que actuar

reset-sandbox-email-address

Genera una nueva dirección de recepción por correo electrónico para un sandbox.

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox sobre el que actuar

forward-sandbox-message

Reenvía un mensaje del sandbox a una dirección de correo electrónico externa. Cuenta para tu cuota mensual de reenvío.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox a reenviar
  • email (obligatorio): Dirección de correo electrónico a la que reenviar el mensaje

update-sandbox-message

Marca un mensaje del sandbox como leído o no leído.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox a actualizar
  • is_read (obligatorio): true marca como leído, false marca como no leído

delete-sandbox-message

Elimina un único mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox a eliminar

get-sandbox-message-spam-score

Obtén el informe de spam de SpamAssassin para un mensaje del sandbox (puntuación, reglas, informe completo). Alternativa independiente a include_spam_report: true en show-sandbox-email-message.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html-analysis

Obtén el informe de análisis HTML para un mensaje del sandbox (puntuaciones de compatibilidad con clientes, elementos problemáticos). Alternativa independiente a include_html_analysis: true en show-sandbox-email-message.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-headers

Obtén las cabeceras de correo analizadas para un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html

Obtén el cuerpo HTML renderizado de un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-text

Obtén el cuerpo de texto plano de un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-raw

Obtén el mensaje sin procesar, con formato MIME (cabeceras + cuerpo) para un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-eml

Obtén el mensaje renderizado como un archivo EML (adecuado para adjuntar a un ticket o importar en otro cliente de correo).

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html-source

Obtén el código fuente HTML sin renderizar de un mensaje del sandbox (HTML antes de cualquier transformación del lado de Mailtrap, como reescrituras de enlaces CID).

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

list-sandbox-attachments

Lista todos los adjuntos de un mensaje del sandbox (nombre de archivo, tipo de contenido, tamaño, ruta de descarga).

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-attachment

Obtén metadatos y URL de descarga para un único adjunto.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Se usa MAILTRAP_SANDBOX_ID como alternativa.
  • message_id (obligatorio): ID del mensaje del sandbox que contiene el adjunto
  • attachment_id (obligatorio): ID del adjunto a obtener

list-sending-domains

Lista los dominios de envío y su estado de verificación DNS.

Parámetros:

  • No se requieren parámetros

get-sending-domain

Obtén un dominio de envío por ID y su estado de verificación (incluidos los registros DNS). Opcionalmente, incluye instrucciones de configuración DNS estableciendo include_setup_instructions a true.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío
  • include_setup_instructions (opcional): Si es true, añade instrucciones de configuración DNS a la respuesta. Valor predeterminado: false

create-sending-domain

Crea un nuevo dominio de envío. Después de la creación, añade registros DNS para verificar el dominio (usa get-sending-domain con include_setup_instructions: true para ver los registros).

Parámetros:

  • domain_name (obligatorio): Nombre del dominio (p. ej., example.com)

update-sending-domain

Actualiza la configuración de seguimiento y de entrada de un dominio de envío.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío
  • open_tracking_enabled (opcional): Rastrear aperturas en correos enviados desde este dominio
  • click_tracking_enabled (opcional): Rastrear clics en enlaces de correos enviados desde este dominio
  • tracking_opt_out_enabled (opcional): Añadir el enlace de exclusión de seguimiento a los correos rastreados. Requiere seguimiento de aperturas o clics
  • auto_unsubscribe_link_enabled (opcional): Añadir automáticamente un enlace de cancelación de suscripción a los correos
  • inbound_enabled (opcional): Permitir que el dominio se adjunte a una bandeja de entrada entrante como captura total

Debe proporcionarse al menos una configuración además de sending_domain_id.

delete-sending-domain

Elimina un dominio de envío.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío a eliminar

send-sending-domain-setup-instructions

Envía por correo electrónico las instrucciones de configuración DNS para un dominio de envío a una dirección determinada. Útil para reenviar registros DNS a un compañero de DevOps.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío
  • email (obligatorio): Dirección de correo electrónico a la que enviar las instrucciones de configuración DNS

get-company-info

Obtén la información de la empresa de un dominio de envío, utilizada para la verificación de cumplimiento del dominio.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío

create-company-info

Establece la información de la empresa de un dominio de envío, requerida para la verificación de cumplimiento del dominio.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío
  • name (obligatorio): Nombre de la empresa o individuo
  • address (obligatorio): Dirección postal
  • city (obligatorio): Ciudad
  • country (obligatorio): País
  • zip_code (obligatorio): Código postal o ZIP
  • website_url (obligatorio): URL del sitio web de la empresa
  • phone (opcional): Número de teléfono
  • privacy_policy_url (opcional): URL de la página de política de privacidad
  • terms_of_service_url (opcional): URL de la página de términos de servicio
  • info_level (opcional): business o individual

update-company-info

Actualiza la información de la empresa de un dominio de envío.

Parámetros:

  • sending_domain_id (obligatorio): ID del dominio de envío
  • Cada campo de create-company-info, todos opcionales. Debe proporcionarse al menos uno; los campos omitidos no se modifican.

list-suppressions

Lista o busca supresiones (rebotes duros, quejas de spam, cancelaciones de suscripción, importaciones manuales). Devuelve hasta 1000 resultados por llamada.

Parámetros:

  • email (opcional): Filtro de correo electrónico. Devuelve solo supresiones que coincidan con esta dirección.

create-suppression

Añade una dirección de correo electrónico a la lista de supresiones de la cuenta, para que Mailtrap deje de entregar mensajes a esa dirección.

Parámetros:

  • email (obligatorio): Dirección de correo electrónico a suprimir
  • domain_id (obligatorio): ID del dominio de envío al que se aplica la supresión
  • sending_stream (obligatorio): transactional o bulk
  • type (opcional): hard bounce, spam complaint, unsubscription o manual import. Valor predeterminado: manual import

delete-suppression

Elimina una supresión por ID. Mailtrap reanudará la entrega a este correo electrónico a menos que se suprima nuevamente.

Parámetros:

  • suppression_id (obligatorio): ID de la supresión a eliminar

list-tracking-opt-outs

Lista las direcciones de correo electrónico excluidas del seguimiento de aperturas y clics. Devuelve hasta 1000 registros por llamada.

Parámetros:

  • email (opcional): Filtro de correo electrónico. Devuelve solo exclusiones que coincidan con esta dirección
  • start_time (opcional): Solo exclusiones creadas en o después de este momento (ISO 8601)
  • end_time (opcional): Solo exclusiones creadas en o antes de este momento (ISO 8601)
  • last_id (opcional): Cursor de paginación: el last_id de la respuesta anterior

create-tracking-opt-out

Excluye una dirección de correo electrónico del seguimiento de aperturas y clics para un dominio de envío.

Parámetros:

  • email (obligatorio): Dirección de correo electrónico para excluir del seguimiento
  • domain_id (obligatorio): ID del dominio de envío al que se aplica la exclusión

delete-tracking-opt-out

Elimina una dirección de correo electrónico de la lista de exclusión de seguimiento, para que el seguimiento de aperturas y clics se aplique nuevamente.

Parámetros:

  • tracking_opt_out_id (obligatorio): ID de la exclusión de seguimiento a eliminar

list-webhooks

Lista todos los webhooks configurados para la cuenta. Devuelve los registros completos de webhooks como JSON.

Parámetros:

  • No se requieren parámetros

get-webhook

Obtén un único webhook por ID. Devuelve el registro completo del webhook como JSON. Nota: signing_secret no se devuelve aquí; solo está disponible en la respuesta de create-webhook.

Parámetros:

  • webhook_id (obligatorio): ID del webhook a obtener

create-webhook

Crea un webhook. La respuesta incluye un signing_secret para verificar las firmas de las cargas útiles del webhook: este secreto se devuelve solo en la creación, así que guárdalo ahora. Si lo pierdes, recrea el webhook.

Parámetros:

  • url (obligatorio): URL a la que Mailtrap enviará los eventos del webhook mediante POST
  • webhook_type (obligatorio): "email_sending", "audit_log" o "inbound_receiving"
  • active (opcional, booleano): valor predeterminado true
  • payload_format (opcional): "json" o "jsonlines". Valor predeterminado: "json"
  • sending_stream (opcional, solo email_sending): "transactional" o "bulk"
  • event_types (opcional, solo email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (opcional, solo email_sending): ID del dominio de envío para limitar este webhook
  • inbound_inbox_id (opcional, solo inbound_receiving): ID de la bandeja de entrada entrante a la que está vinculado el webhook; omítelo para aplicar a todas las bandejas de entrada de la cuenta

update-webhook

Actualiza los campos modificables de un webhook. webhook_type, sending_stream y domain_id no se pueden cambiar después de la creación: recrea el webhook si necesitas cambiar esos campos.

Parámetros:

  • webhook_id (obligatorio): ID del webhook a actualizar
  • url (opcional): Nueva URL del webhook
  • active (opcional, booleano): Habilita o deshabilita el webhook
  • payload_format (opcional): "json" o "jsonlines"
  • event_types (opcional, solo email_sending): matriz de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (opcional, solo inbound_receiving): ID de la bandeja de entrada entrante a la que está vinculado el webhook

delete-webhook

Elimina permanentemente un webhook por ID. Devuelve el registro del webhook eliminado.

Parámetros:

  • webhook_id (obligatorio): ID del webhook a eliminar

get-contact

Obtén un contacto por ID o correo electrónico. Devuelve el registro completo del contacto (membresías de listas, estado, campos personalizados).

Parámetros:

  • contact_identifier (obligatorio): ID del contacto o dirección de correo electrónico

create-contact

Crea un nuevo contacto.

Parámetros:

  • email (obligatorio): Dirección de correo electrónico
  • fields (opcional): Valores de campos personalizados claveados por etiqueta de combinación (p. ej., first_name). Valores de cadena, número o booleano
  • list_ids (opcional): IDs de listas de contactos para suscribir a este contacto
  • unsubscribed (opcional, booleano): Crear el contacto en estado unsubscribed

update-contact

Actualiza un contacto existente identificado por ID o correo electrónico. list_ids reemplaza el conjunto completo de membresías del contacto; list_ids_included/list_ids_excluded agregan/eliminan sin alterar el resto.

Parámetros:

  • contact_identifier (obligatorio): ID del contacto o correo electrónico
  • email (opcional): Nueva dirección de correo electrónico
  • fields (opcional): Valores de campos personalizados claveados por etiqueta de combinación
  • list_ids (opcional): Reemplazar el conjunto de membresías con esta lista exacta
  • list_ids_included (opcional): IDs de listas para agregar (aditivo)
  • list_ids_excluded (opcional): IDs de listas para eliminar
  • unsubscribed (opcional, booleano): Establecer en unsubscribed (verdadero) o subscribed (falso)

delete-contact

Elimina permanentemente un contacto por ID o correo electrónico. Devuelve el registro del contacto eliminado cuando la API responde con uno; de lo contrario, devuelve un payload de confirmación.

Parámetros:

  • contact_identifier (obligatorio): ID del contacto o correo electrónico

create-contact-event

Registra un evento de contacto contra un contacto (por ID o correo electrónico). Se utiliza para activar automatizaciones de listas de contactos.

Parámetros:

  • contact_identifier (obligatorio): ID del contacto o correo electrónico
  • name (obligatorio): Nombre del evento (coincide con los disparadores de automatización)
  • params (obligatorio): Objeto de pares clave/valor arbitrarios. Los valores pueden ser cadena, número, booleano o nulo

list-contact-lists

Lista todas las listas de contactos de la cuenta.

Parámetros:

  • search (opcional): Filtrar listas de contactos por nombre (coincidencia sin distinción de mayúsculas), p. ej., news

get-contact-list

Obtiene una lista de contactos por ID.

Parámetros:

  • list_id (obligatorio): ID de la lista de contactos a obtener

create-contact-list

Crea una nueva lista de contactos.

Parámetros:

  • name (obligatorio): Nombre para la nueva lista

update-contact-list

Renombra una lista de contactos existente.

Parámetros:

  • list_id (obligatorio): ID de la lista de contactos
  • name (obligatorio): Nuevo nombre para la lista

delete-contact-list

Elimina permanentemente una lista de contactos por ID.

Parámetros:

  • list_id (obligatorio): ID de la lista de contactos a eliminar

list-contact-fields

Lista todas las definiciones de campos de contacto de la cuenta.

Parámetros:

  • No se requieren parámetros

get-contact-field

Obtiene una definición de campo de contacto por ID.

Parámetros:

  • field_id (obligatorio): ID del campo de contacto

create-contact-field

Crea una nueva definición de campo de contacto. merge_tag debe ser único dentro de la cuenta y se utiliza como nombre de marcador de posición en las variables de plantilla.

Parámetros:

  • name (obligatorio): Nombre para mostrar (p. ej., "Nombre")
  • merge_tag (obligatorio): Nombre de marcador de posición único (p. ej., first_name)
  • data_type (obligatorio): Uno de text, number, boolean, date

update-contact-field

Actualiza una definición de campo de contacto. Se puede cambiar cualquier combinación de name, merge_tag y data_type.

Parámetros:

  • field_id (obligatorio): ID del campo de contacto
  • name (opcional): Nuevo nombre para mostrar
  • merge_tag (opcional): Nueva etiqueta de combinación (debe permanecer única)
  • data_type (opcional): Uno de text, number, boolean, date

delete-contact-field

Elimina permanentemente una definición de campo de contacto por ID.

Parámetros:

  • field_id (obligatorio): ID del campo de contacto a eliminar

create-contact-import

Importa contactos de forma masiva. Devuelve un registro de trabajo de importación; consulta su estado con get-contact-import.

Parámetros:

  • contacts (obligatorio): Matriz de entradas de contacto. Cada entrada necesita:
    • email (obligatorio): Dirección de correo electrónico del contacto
    • fields (opcional): Valores de campos personalizados claveados por etiqueta de combinación (valores de cadena o número)
    • list_ids_included (opcional): IDs de listas para agregar el contacto
    • list_ids_excluded (opcional): IDs de listas para eliminar el contacto

get-contact-import

Obtiene el estado de un trabajo de importación de contactos (creado/iniciado/finalizado/fallido) con conteos de creados/actualizados/límite superado.

Parámetros:

  • import_id (obligatorio): ID del trabajo de importación de contactos

create-contact-export

Exporta contactos que coinciden con un conjunto de filtros combinados con AND. Devuelve un registro de trabajo de exportación; consulta el estado con get-contact-export para recuperar la URL de descarga una vez que status sea finished.

Parámetros:

  • filters (obligatorio): Matriz de objetos de filtro. Cada uno tiene:
    • name (obligatorio): Campo para filtrar (list_id, subscription_status, email, etc.)
    • operator (obligatorio): Uno de equal, not_equal, contains, not_contains, is_empty, is_not_empty
    • value (obligatorio): Valor de comparación (cadena, número, booleano o matriz)

get-contact-export

Obtiene el estado de un trabajo de exportación de contactos. Una vez que status sea finished, el campo url contiene el enlace de descarga CSV.

Parámetros:

  • export_id (obligatorio): ID del trabajo de exportación de contactos

list-email-campaigns

Lista las campañas de correo electrónico de la cuenta, de más reciente a más antigua, con paginación por token de página. Opcionalmente, filtra por nombre con search.

Parámetros:

  • token (opcional): Número de página a recuperar (paginación por token de página). El valor predeterminado es 1
  • per_page (opcional): Número de campañas por página. El valor predeterminado es 50, máximo 100
  • search (opcional): Filtrar campañas por nombre (coincidencia parcial sin distinción de mayúsculas)

get-email-campaign

Obtiene una campaña de correo electrónico por ID.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico

create-email-campaign

Crea una nueva campaña de correo electrónico. La campaña siempre se crea en el estado draft; la programación y el inicio son herramientas separadas (schedule-email-campaign, start-email-campaign).

Parámetros:

  • name (obligatorio): Nombre de la campaña
  • domain_id (obligatorio): ID del dominio de envío verificado utilizado para la campaña, tal como lo devuelven los endpoints de dominios de envío
  • from_local_part (obligatorio): Parte local (antes de la @) de la dirección del remitente
  • template_attributes (obligatorio): Plantilla de correo electrónico en línea. Tiene:
    • subject (obligatorio): Línea de asunto del correo electrónico (máx. 255 caracteres). Admite etiquetas de combinación, p. ej., Hi {{first_name}}
    • body_html (opcional): Cuerpo HTML (el diseño). Requerido antes de que la campaña pueda programarse o iniciarse. Incluye un enlace de cancelación de suscripción mediante un ancla cuyo href contenga el marcador de posición __unsubscribe_url__
    • body_text (opcional): Alternativa de texto plano del cuerpo del correo electrónico
    • merge_tags (opcional): Nombres simples de las etiquetas de combinación referenciadas en el asunto/cuerpo, p. ej., ["first_name"]
  • from_display_name (opcional): Nombre para mostrar en el encabezado del remitente
  • reply_to (opcional): Partes de la dirección de respuesta (display_name, local_part, domain)
  • delivery_mode (opcional): rapid (enviar lo más rápido posible) o gradual (limitar a delivery_options.emails_per_hour)
  • delivery_options (opcional): Opciones de limitación de entrega (emails_per_hour)
  • contact_list_ids (opcional): IDs de listas de contactos a las que enviar (se tratan como el conjunto completo de listas incluidas)
  • contact_segment_ids (opcional): IDs de segmentos de contactos a los que enviar (se tratan como el conjunto completo de segmentos incluidos)

update-email-campaign

Actualiza una campaña de correo electrónico en estado draft. Solo cambian los campos proporcionados; la plantilla se edita en el lugar. Las campañas en cualquier otro estado no se pueden actualizar.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a actualizar
  • Todos los demás parámetros son opcionales e idénticos a create-email-campaign (name, domain_id, from_local_part, from_display_name, reply_to, template_attributes, delivery_mode, delivery_options, contact_list_ids, contact_segment_ids)

delete-email-campaign

Elimina una campaña de correo electrónico por ID. Solo se puede eliminar una campaña en estado draft.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a eliminar

start-email-campaign

Inicia el envío de una campaña de correo electrónico en estado draft inmediatamente. Solo se pueden iniciar campañas en estado draft; la plantilla debe tener un diseño body_html y la audiencia y el dominio de envío verificado deben estar configurados.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a iniciar

schedule-email-campaign

Programa una campaña de correo electrónico en estado draft para comenzar a enviarse en un momento futuro. Solo se pueden programar campañas en estado draft.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a programar
  • datetime (obligatorio): Cuándo enviar la campaña (ISO 8601). Debe ser en el futuro y no más de 1 mes por delante

cancel-email-campaign

Cancela una campaña de correo electrónico en estado scheduled, devolviéndola a draft. Solo se pueden cancelar campañas en estado scheduled.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a cancelar

terminate-email-campaign

Termina una campaña de correo electrónico que se está enviando actualmente (started, queued o paused), abortando el envío en curso.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a terminar

reset-email-campaign

Restablece una campaña de correo electrónico en estado scheduled de vuelta a draft. Solo se pueden restablecer campañas en estado scheduled.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico a restablecer

get-email-campaign-stats

Obtiene estadísticas de rendimiento agregadas para una campaña de correo electrónico (conteos y tasas de entregas, aperturas, clics, rebotes, quejas de spam y cancelaciones de suscripción).

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico
  • start_date (opcional): Inicio de la ventana de agregación (inclusive), YYYY-MM-DD. El valor predeterminado es el día en que la campaña se inició por última vez
  • end_date (opcional): Fin de la ventana de agregación (inclusive), YYYY-MM-DD. El valor predeterminado es la fecha actual

list-accounts

Lista las cuentas de Mailtrap a las que el token de API actual puede acceder, con los niveles de acceso de cada cuenta.

Parámetros:

  • No se requieren parámetros

get-billing-usage

Obtiene el uso del ciclo de facturación actual de la cuenta: planes de envío y prueba, límites y conteos actuales.

Parámetros:

  • No se requieren parámetros

list-account-accesses

Lista los accesos de cuenta (usuarios, invitaciones, tokens de API) para la cuenta. Los filtros opcionales limitan el resultado a recursos específicos. Requiere permisos de administrador/propietario de la cuenta.

Parámetros:

  • domain_uuids (opcional): Filtrar por UUIDs de dominios de envío (matriz de cadenas)
  • inbox_ids (opcional): Filtrar por IDs de bandejas de entrada de sandbox (matriz de cadenas)
  • project_ids (opcional): Filtrar por IDs de proyectos de sandbox (matriz de cadenas)

remove-account-access

Elimina un acceso de cuenta por ID. Para especificadores de User, esto revoca sus permisos; para especificadores de Invite o ApiToken, elimina el especificador por completo. Requiere administrador/propietario.

Parámetros:

  • account_access_id (obligatorio): ID del registro de acceso a eliminar

get-permission-resources

Obtiene todos los recursos (bandejas de entrada, proyectos, dominios, facturación, cuenta) a los que el token de API tiene acceso de administrador, anidados por jerarquía.

Parámetros:

  • No se requieren parámetros

bulk-update-permissions

Crea, actualiza o elimina permisos en masa para un solo acceso de cuenta. Los pares (resource_type, resource_id) existentes se actualizan; los nuevos se crean. Establece destroy: true en una entrada para eliminarla.

Parámetros:

  • account_access_id (obligatorio): ID del acceso de cuenta de destino
  • permissions (obligatorio): Matriz de entradas de permisos. Cada una tiene:
    • resource_id (obligatorio): ID del recurso (número o cadena)
    • resource_type (obligatorio): Uno de account, project, inbox, domain, billing
    • access_level (opcional): admin/100 o viewer/10
    • destroy (opcional, booleano): Cuando es verdadero, elimina este permiso en lugar de crearlo o actualizarlo

list-api-tokens

Lista todos los tokens de API de la cuenta.

Parámetros:

  • No se requieren parámetros

create-api-token

Crea un nuevo token de API. La respuesta incluye el valor secreto token — esta es la única vez que se devuelve el token completo, así que guárdalo inmediatamente. Si lo pierdes, recrea el token.

Parámetros:

  • name (obligatorio): Nombre visible para el token
  • expires_at (opcional): Expiración del token como fecha-hora ISO 8601. Omítelo para el valor predeterminado del servidor (1 año); pasa un null explícito para un token que nunca expira. Se rechazan valores pasados o valores con más de 5 años de antelación
  • resources (opcional): Matriz de permisos de recursos para limitar el token. Cada entrada tiene:
    • resource_type (obligatorio): Uno de account, project, inbox, domain, billing
    • resource_id (obligatorio): ID del recurso
    • access_level (obligatorio): 100 (administrador) o 10 (visor)

get-api-token

Obtiene un token de API por ID. Devuelve solo metadatos — el valor secreto del token no se devuelve aquí (solo desde create-api-token / reset-api-token).

Parámetros:

  • api_token_id (obligatorio): ID del token de API

reset-api-token

Restablece (rota) un token de API por ID. La respuesta incluye el nuevo valor secreto token — se devuelve solo en esta llamada, así que guárdalo inmediatamente. El token anterior queda invalidado.

Parámetros:

  • api_token_id (obligatorio): ID del token de API a restablecer
  • expires_at (opcional): Expiración del nuevo token como fecha-hora ISO 8601. Omítelo para el valor predeterminado del servidor (1 año); pasa un null explícito para un token que nunca expira. Se rechazan valores pasados o valores con más de 5 años de antelación

delete-api-token

Elimina permanentemente un token de API por ID. El token ya no puede autenticarse después de la eliminación.

Parámetros:

  • api_token_id (obligatorio): ID del token de API a eliminar

list-sub-accounts

Lista las subcuentas de la organización. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos de gestión de subcuentas.

Parámetros:

  • No se requieren parámetros

create-sub-account

Crea una nueva subcuenta bajo la organización. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos de gestión de subcuentas.

Parámetros:

  • name (obligatorio): Nombre visible para la nueva subcuenta

list-inbound-folders

Lista todas las carpetas de entrada de la cuenta. Devuelve un resumen formateado.

Parámetros:

  • No se requieren parámetros

get-inbound-folder

Obtiene una sola carpeta de entrada por ID. Devuelve el registro completo de la carpeta como JSON.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada

create-inbound-folder

Crea una nueva carpeta de entrada.

Parámetros:

  • name (obligatorio): El nombre de la carpeta

update-inbound-folder

Renombra una carpeta de entrada.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada
  • name (obligatorio): El nuevo nombre de la carpeta

delete-inbound-folder

Elimina permanentemente una carpeta de entrada junto con todas sus bandejas de entrada.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada

list-inbound-inboxes

Lista todas las bandejas de entrada en una carpeta de entrada. Devuelve un resumen formateado.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada

get-inbound-inbox

Obtiene una sola bandeja de entrada por ID. Devuelve el registro completo de la bandeja como JSON.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada
  • inbox_id (obligatorio): ID de la bandeja de entrada

create-inbound-inbox

Crea una nueva bandeja de entrada en una carpeta.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada
  • name (obligatorio): El nombre de la bandeja de entrada
  • domain_id (opcional): Adjuntar a un dominio de envío personalizado (bandeja de captura total). Omítelo para una bandeja alojada en Mailtrap

update-inbound-inbox

Renombra una bandeja de entrada.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada
  • inbox_id (obligatorio): ID de la bandeja de entrada
  • name (obligatorio): El nuevo nombre de la bandeja de entrada

delete-inbound-inbox

Elimina permanentemente una bandeja de entrada.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada
  • inbox_id (obligatorio): ID de la bandeja de entrada

list-inbound-messages

Lista los mensajes recibidos en una bandeja de entrada (paginación por cursor). Devuelve un resumen formateado con una pista de página siguiente cuando existen más resultados.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • last_id (opcional): Cursor de paginación del last_id de una respuesta anterior

get-inbound-message

Obtiene un solo mensaje de entrada con su cuerpo completo y las URL de descarga de archivos adjuntos. Devuelve el registro completo del mensaje como JSON.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • message_id (obligatorio): ID del mensaje

delete-inbound-message

Elimina permanentemente un mensaje de entrada.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • message_id (obligatorio): ID del mensaje

reply-to-inbound-message

Responde a un mensaje de entrada (envía al remitente original). Envía un correo real. Las direcciones aceptan una cadena de correo simple o { email, name? }.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • message_id (obligatorio): ID del mensaje al que responder
  • text / html (al menos uno recomendado): Cuerpo de la respuesta
  • from (opcional): Remitente. Se rechaza para bandejas alojadas en Mailtrap; es obligatorio para bandejas con dominio personalizado
  • cc / bcc / reply_to (opcional): Direcciones adicionales
  • category (opcional): Categoría del mensaje
  • attachments (opcional): Matriz de { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (opcional): Objetos de valores de cadena

reply-all-to-inbound-message

Responde a un mensaje de entrada y copia a los otros destinatarios del original. Envía un correo real. Mismos parámetros que reply-to-inbound-message.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • message_id (obligatorio): ID del mensaje al que responder
  • Más los mismos campos de envío opcionales que reply-to-inbound-message

forward-inbound-message

Reenvía un mensaje de entrada a nuevos destinatarios. Envía un correo real.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • message_id (obligatorio): ID del mensaje a reenviar
  • to (obligatorio): Al menos un destinatario (cadena de correo simple o { email, name? }, o una matriz)
  • Más los mismos campos de envío opcionales que reply-to-inbound-message

list-inbound-threads

Lista los hilos de conversación en una bandeja de entrada (paginación por cursor). Devuelve un resumen formateado con una pista de página siguiente cuando existen más resultados.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • last_id (opcional): Cursor de paginación del last_id de una respuesta anterior

get-inbound-thread

Obtiene un solo hilo de entrada con sus mensajes incrustados (del más antiguo al más reciente). Devuelve el registro completo del hilo como JSON.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • thread_id (obligatorio): ID del hilo

delete-inbound-thread

Elimina permanentemente un hilo de entrada.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • thread_id (obligatorio): ID del hilo

Desarrollo

  1. Clona el repositorio:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Instala las dependencias:
npm install

Configuración con Claude Desktop o Cursor

[!TIP] Consulta la ubicación del archivo de configuración en la sección Configuración.

Añade la siguiente configuración:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Si usas asdf para gestionar Node.js, debes usar la ruta absoluta al ejecutable:

(ejemplo para Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Consulta la ubicación del archivo de configuración en la sección Configuración.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Pruebas

Ejecutar herramientas contra Mailtrap real

Hay dos formas de ejercitar una herramienta de extremo a extremo contra una cuenta real de Mailtrap: la interfaz de navegador del Inspector MCP para exploración interactiva, o su modo CLI para llamadas puntuales desde la terminal.

Ambas requieren que el paquete se compile primero:

npm run build

y que MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID estén exportados en tu terminal (el script mcp:cli reenvía ambos al servidor generado).

Interfaz de navegador

npm run dev

El Inspector imprime una URL como http://localhost:6274. Ábrela, cambia a la pestaña Herramientas, elige una herramienta (por ejemplo, get-template), completa los parámetros como JSON y pulsa Ejecutar. La respuesta de Mailtrap aparece en el panel inferior.

CLI

Para llamadas puntuales sin la interfaz, usa npm run mcp:cli. Pasa las banderas CLI del Inspector después de -- para que npm las reenvíe tal cual:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

Ejecutar el servidor MCPB

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Para desarrollo con el Inspector MCP:

npm run dev:mcpb

Manejo de errores

Este servidor usa manejo estructurado de errores alineado con las convenciones de MCP:

  • VALIDATION_ERROR: Fallos de validación de entrada
  • CONFIGURATION_ERROR: Configuración faltante o inválida
  • EXECUTION_ERROR: Errores de ejecución en tiempo de ejecución
  • TIMEOUT: Tiempo de espera agotado de la operación (30 segundos por defecto)

Los errores incluyen mensajes accionables y se registran en forma estructurada.

Seguridad

  • Entrada validada mediante esquemas Zod
  • Variables de entorno manejadas de forma segura
  • Protección de tiempo de espera en operaciones (30 segundos)
  • Detalles sensibles saneados en la salida de errores

Registro

Registros JSON estructurados con niveles: INFO, WARN, ERROR, DEBUG.

Habilita el registro de depuración estableciendo DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Importante: El servidor escribe los registros en stderr para que stdout permanezca reservado para tramas JSON-RPC. Esto evita que los hosts encuentren errores de análisis JSON debido a registros intercalados.

Ejemplo de análisis de registros usando jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

Solución de problemas

Problemas comunes:

  1. Token de API faltante: asegúrate de que MAILTRAP_API_TOKEN esté establecido
  2. Sandbox que no funciona: proporciona test_inbox_id en la llamada a la herramienta o establece la variable de entorno MAILTRAP_TEST_INBOX_ID
  3. Errores de tiempo de espera: verifica la conectividad de red y el estado de la API de Mailtrap
  4. Errores de validación: asegúrate de que todos los campos obligatorios estén proporcionados

Contribuciones

Los informes de errores y las solicitudes de extracción son bienvenidos en GitHub. Este proyecto pretende ser un espacio seguro y acogedor para la colaboración, y se espera que los contribuyentes cumplan con el código de conducta.

Licencia

El paquete está disponible como código abierto bajo los términos de la Licencia MIT.

Código de conducta

Se espera que todos los que interactúan en los repositorios de código, rastreadores de problemas, salas de chat y listas de correo del proyecto Mailtrap sigan el código de conducta.