Mailtrap

oficial

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

¿Qué puedes hacer con Mailtrap MCP?

  • Enviar correos electrónicos transaccionales — Pide al asistente que envíe un correo electrónico con un asunto y un cuerpo de texto o HTML, opcionalmente usando una plantilla y variables.
  • Probar en Email Sandbox — Envía mensajes a un entorno aislado e inspecciona su contenido, encabezados y archivos adjuntos sin que lleguen a destinatarios reales.
  • Depurar la entrega con registros — Enumera y filtra los registros de correos enviados y, luego, abre un mensaje específico para revisar su historial de eventos y el estado de entrega.
  • Analizar las estadísticas de envío — Obtén las tasas de entrega, rebote, apertura, clics y spam para un intervalo de fechas, desglosadas por dominio, categoría o fecha.
  • Administrar plantillas — Crea, enumera, actualiza y elimina plantillas de correo electrónico almacenadas en tu cuenta de Mailtrap.
  • Administrar dominios y supresiones — Enumera dominios, obtén instrucciones de configuración de DNS y revisa o elimina direcciones suprimidas.

Documentación

TypeScript test NPM

Servidor MCP oficial de Mailtrap

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

Envía correos electrónicos transaccionales y masivos, prueba mensajes de forma segura en Email Sandbox, administra plantillas, contactos, dominios y webhooks, consulta registros de correo y estadísticas de entrega, soluciona problemas de entregabilidad y administra recursos de la cuenta, todo mediante instrucciones en lenguaje natural.

Funcionalidades

  • API de correo electrónico y SMTP — Envía correos electrónicos transaccionales y masivos, incluidos mensajes por lotes y basados en plantillas.
  • Pruebas de correo electrónico — Prueba mensajes en Email Sandbox y consulta el contenido, los encabezados, los archivos adjuntos, las puntuaciones de spam y la compatibilidad con clientes de correo HTML.
  • Supervisión de entregas — Busca registros de correo, consulta el historial de eventos y analiza las tasas de entrega, rebotes, aperturas, clics y spam.
  • Infraestructura de correo electrónico — Administra dominios, verificación de DNS, webhooks y supresiones.
  • Contactos — Administra contactos, listas, campos personalizados y eventos, con funciones de importación y exportación.
  • Administración de cuentas — Consulta el uso de facturación y administra el acceso, los permisos, los tokens de API y las subcuentas.

Clientes MCP compatibles

Funciona con Claude Desktop, Claude Code, Cursor, VS Code y cualquier otro cliente compatible con MCP. A continuación encontrarás las instrucciones de configuración para cada uno.

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 en la configuración de la API de Mailtrap
  4. Obtener tu ID de cuenta en la administración de cuentas de Mailtrap
  5. Instalar Node.js 22 o posterior, a menos que ejecutes la imagen de Docker

Variables de entorno obligatorias:

  • MAILTRAP_API_TOKEN - Obligatoria para todas las funciones
  • MAILTRAP_ACCOUNT_ID - Obligatoria para plantillas, get-sending-stats, registros de correo, lista y consulta de sandbox, dominios y supresiones. Solo es opcional para las herramientas de envío (send-email, send-sandbox-email y las herramientas batch-send-*), las herramientas de campañas de correo electrónico, get-marketing-stats, las herramientas de información de la empresa, las herramientas de exclusión del seguimiento y list-accounts.

Opcionales (también se pueden pasar como parámetros de las herramientas):

  • DEFAULT_FROM_EMAIL - Correo electrónico del remitente predeterminado cuando no se proporciona from a send-email, send-sandbox-email o las herramientas batch-send-* (donde completa base.from). Permite cambiar el remitente en cada llamada mediante el parámetro from.
  • MAILTRAP_SANDBOX_ID - ID de sandbox predeterminado cuando no se proporciona sandbox_id a una herramienta (también se acepta el test_inbox_id heredado en las herramientas de envío, lista y consulta de mensajes de sandbox). Permite cambiar de sandbox en cada llamada mediante parámetros.
  • MAILTRAP_TEST_INBOX_ID - Alias obsoleto de MAILTRAP_SANDBOX_ID; se sigue leyendo como alternativa para las configuraciones existentes y, cuando se usa, se registra una advertencia de obsolescencia en stderr.
  • MAILTRAP_ORGANIZATION_ID - Obligatoria para las herramientas de organización (list-sub-accounts, create-sub-account, delete-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Token de API con ámbito de organización. Obligatorio para las herramientas de organización (independiente de MAILTRAP_API_TOKEN).

Instalación rápida

Install in Cursor

Install with Node in VS Code

Docker

Ejecuta el servidor mediante stdio con la imagen del catálogo MCP de Docker:

docker run --rm -i \
  -e MAILTRAP_API_TOKEN="${MAILTRAP_API_TOKEN}" \
  -e MAILTRAP_ACCOUNT_ID="${MAILTRAP_ACCOUNT_ID}" \
  -e DEFAULT_FROM_EMAIL="${DEFAULT_FROM_EMAIL}" \
  -e MAILTRAP_SANDBOX_ID="${MAILTRAP_SANDBOX_ID}" \
  -e MAILTRAP_ORGANIZATION_ID="${MAILTRAP_ORGANIZATION_ID}" \
  -e MAILTRAP_ORGANIZATION_API_TOKEN="${MAILTRAP_ORGANIZATION_API_TOKEN}" \
  mcp/mailtrap

Consulta los requisitos previos para ver las variables de entorno obligatorias y opcionales.

Para compilar desde este repositorio: docker build -t mcp/mailtrap .

CLI de Smithery

Smithery es un registro e instalador de servidores MCP compatible con clientes de IA.

Instala el servidor publicado (mailtrap/mailtrap-mcp) en un cliente local (cambia el nombre del cliente según sea necesario):

npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude

Consulta la documentación de la CLI de Smithery para ver otros clientes (cursor, windsurf, etc.) y cómo publicar actualizaciones.

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, se abrirá y te sugerirá configurarlo.

Claude Desktop o Cursor

Añade 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_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Si usas asdf para administrar 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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_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

Cambiar la configuración manualmente

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

Luego, añade la siguiente configuración al archivo de ajustes:

{
  "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_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

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

Paquete MCP (MCPB)

Para facilitar la instalación en hosts compatibles con 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. El script copia dist/, manifest.json, icon.png y la licencia en mcpb-build/, instala allí las dependencias de producción y empaqueta solo ese directorio. No ejecutes mcpb pack . desde la raíz del repositorio.

Uso

Una vez configurado, puedes pedirle al agente que envíe correos electrónicos y administre plantillas. Por ejemplo:

Operaciones de envío de correo electrónico:

  • "Envía un correo electrónico a john.doe@example.com con el asunto 'Meeting Tomorrow' y un recordatorio cordial sobre nuestra próxima reunión."
  • "Envía un correo a sarah@example.com sobre la actualización del proyecto y pon en 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 'Test Template' para previsualizar cómo se ve nuestro correo de bienvenida"

Registros de correo (depuración de entregas):

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

Estadísticas:

  • "Obtén las estadísticas de envío de enero de 2025"
  • "Muestra las tasas de entrega desglosadas por dominio del mes pasado"
  • "¿Cuáles son mis estadísticas de correo por categoría del 2025-01-01 al 2025-01-31?"
  • "¿Qué resultados tuvo mi marketing por correo electrónico el mes pasado? Compara las campañas con las automatizaciones"

Operaciones de sandbox:

  • "Obtén todos los mensajes de mi sandbox"
  • "Muéstrame la primera página de mensajes de sandbox"
  • "Busca mensajes que contengan 'test' en mi sandbox"
  • "Crea un sandbox llamado 'QA' en el proyecto 42 y dame sus credenciales SMTP"
  • "Elimina todos los mensajes del sandbox 1234"
  • "Muéstrame los detalles del mensaje de sandbox con ID 5159037506"

Operaciones con plantillas:

  • "Enumera todas las plantillas de correo electrónico de mi cuenta de Mailtrap"
  • "Crea una plantilla de correo electrónico llamada 'Welcome Email' con el asunto 'Welcome to our platform!'"
  • "Actualiza la plantilla con ID 12345 para cambiar el asunto a 'Updated Welcome Message'"
  • "Elimina la plantilla con ID 67890"

Dominios:

  • "Enumera mis dominios"
  • "Obtén el dominio con ID 3938"
  • "Crea un dominio para example.com"
  • "Activa el seguimiento de clics para el dominio 3938"
  • "Elimina el dominio 3938"
  • "Obtén el dominio 3938 con instrucciones de configuración de DNS"
  • "Muestra la información de la empresa para el dominio 3938"
  • "Establece la información de la 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 la empresa para el dominio 3938 a New York"

Supresiones:

Exclusiones del seguimiento:

  • "Deja de hacer seguimiento de aperturas y clics para privacy@example.com en el dominio 3938"
  • "Enumera a todas las personas que excluyeron el seguimiento"

Contactos y listas:

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

Webhooks:

  • "Enumera 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 electrónicos me quedan en mi plan?"
  • "Enumera a todas las personas que tienen acceso a esta cuenta de Mailtrap"
  • "Muéstrame los recursos de permisos disponibles en mi cuenta"

Tokens de API:

  • "Enumera todos los tokens de API de mi cuenta"
  • "Crea un token de API para el entorno de staging"
  • "Restablece el token de API con ID 1234"
  • "Elimina el token de API sin usar 1234"

Organización y subcuentas:

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

Herramientas renombradas

Mailtrap ahora llama sandboxes a las bandejas de prueba y dominios a los dominios de envío, y las herramientas siguen esa nomenclatura. Los nombres antiguos ya no aparecen en la lista de herramientas, pero las llamadas a ellos siguen funcionando y registran una advertencia de obsolescencia en stderr. Se eliminarán en una futura versión principal.

Los clientes MCP y los marcos de agentes comparan las listas de permitidos, denegados y filtros con el nombre anunciado de la herramienta, así que cambia las entradas por herramienta a los nombres nuevos: una entrada de denegación para delete-sending-domain ya no bloquea delete-domain.

Nombre anteriorNombre nuevo
create-sandbox-inboxcreate-sandbox
get-sandbox-inboxget-sandbox
update-sandbox-inboxupdate-sandbox
delete-sandbox-inboxdelete-sandbox
clean-sandbox-inboxclean-sandbox
list-sending-domainslist-domains
get-sending-domainget-domain
create-sending-domaincreate-domain
update-sending-domainupdate-domain
delete-sending-domaindelete-domain
send-sending-domain-setup-instructionssend-domain-setup-instructions
sending_domain_id parámetro de las herramientas de dominio e información de la empresadomain_id
MAILTRAP_TEST_INBOX_ID variable de entornoMAILTRAP_SANDBOX_ID

Los filtros que reflejan un campo de la API conservan sus nombres: sending_domain_id en list-email-logs y sending_domain_ids en las herramientas de estadísticas.

Herramientas disponibles

send-email

Envía un correo electrónico 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 electrónico sin formato 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 electrónico sin formato o una única dirección que no sea una matriz en tiempo de ejecución). Es opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
  • cc (opcional): Matriz de destinatarios en copia (CC) como objetos { email, name? } (también se aceptan cadenas de correo electrónico sin formato en tiempo de ejecución).
  • bcc (opcional): Matriz de destinatarios en copia oculta (BCC) como objetos { email, name? } (también se aceptan cadenas de correo electrónico sin formato en tiempo de ejecución).
  • subject (condicional): Asunto del correo electrónico. Obligatorio para los envíos en línea; debe omitirse cuando se establece template_uuid.
  • text (condicional): Texto del cuerpo del correo electrónico. Obligatorio (junto con html o en su lugar) para los envíos en línea; debe omitirse cuando se establece template_uuid.
  • html (condicional): Versión HTML del cuerpo del correo electrónico. Obligatoria (junto con text o en su lugar) para los envíos en línea; debe omitirse cuando se establece template_uuid.
  • category (opcional): Categoría del correo electrónico para seguimiento y análisis. Debe omitirse cuando se establece template_uuid.
  • template_uuid (opcional): Usa una plantilla de correo electrónico de Mailtrap en lugar de contenido en línea. Cuando se establece, deben omitirse subject / text / html / category (según la API de Mailtrap).
  • template_variables (opcional): Objeto de variables sustituidas en la plantilla a la que hace referencia template_uuid. Solo se permite junto con template_uuid.

batch-send-transactional-email

Envía un lote de correos electrónicos transaccionales en una sola llamada a la API de Mailtrap (flujo de envío predeterminado). Los campos compartidos se incluyen en base; las anulaciones por destinatario se incluyen en requests[]. Cada solicitud debe incluir al menos un destinatario mediante to, cc o bcc. Se aplican las mismas reglas de exclusión mutua entre contenido en línea y plantilla que en send-email; se comprueban después de combinar la base con cada solicitud.

Parámetros:

  • base (opcional): Objeto con campos compartidos por todo el lote.
    • from (opcional): Remitente como { email, name? } (también se acepta una cadena de correo electrónico sin formato en tiempo de ejecución). Se usa DEFAULT_FROM_EMAIL como alternativa.
    • reply_to (opcional): Dirección de respuesta.
    • subject / text / html / category (opcional, modo en línea): Contenido predeterminado para cada solicitud.
    • template_uuid / template_variables (opcional, modo de plantilla): Plantilla y variables predeterminadas. Son mutuamente excluyentes con los campos en línea.
    • 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 electrónico sin formato o una única dirección que no sea una matriz en tiempo de ejecución). Es opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
    • cc, bcc, reply_to (opcional).
    • Anulaciones en línea (subject/text/html/category) o de plantilla (template_uuid/template_variables); cualquier campo omitido usa el valor correspondiente de base.
    • custom_variables, headers (opcional).

batch-send-bulk-email

Envía un lote de correos electrónicos masivos mediante la API de flujo masivo de Mailtrap. Tiene la misma estructura base + requests[], validación y reglas de contenido en línea frente a plantilla que batch-send-transactional-email; la única diferencia es que esta herramienta dirige la llamada al endpoint masivo en lugar del transaccional. Consulta los parámetros anteriores.

list-email-logs

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

Todos los parámetros son opcionales.

get-email-log-message

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

Parámetros:

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

get-sending-stats

Obtiene estadísticas de envío de correo electrónico (tasas de entrega, rebote, apertura, clics y spam) para un intervalo de fechas. Opcionalmente, desglosa los datos por dominio, categoría, proveedor de servicios de correo electrónico o fecha. Consulta las tasas de entrega sin salir del editor.

Parámetros:

  • start_date (obligatorio): Fecha de inicio del intervalo de estadísticas (YYYY-MM-DD)
  • end_date (obligatorio): Fecha de finalización del intervalo de estadísticas (YYYY-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): Limita los resultados a estos ID de dominio (matriz de enteros)
  • sending_streams (opcional): Limita a transactional y/o bulk (matriz de cadenas)
  • categories (opcional): Limita a estas categorías de correo electrónico (matriz de cadenas)
  • email_service_providers (opcional): Limita a estos proveedores, por ejemplo, Google, Yahoo, Outlook (matriz de cadenas)

get-marketing-stats

Obtiene estadísticas agregadas de Email Marketing de campañas y automatizaciones para un intervalo de fechas: cantidades y tasas de envíos, entregas, rebotes, aperturas, clics, spam y bajas. delivery_rate y bounce_rate son proporciones de sent_count; las demás tasas son proporciones de delivery_count.

Parámetros:

  • start_date (obligatorio): Inicio del intervalo de fechas (inclusive), YYYY-MM-DD
  • end_date (obligatorio): Fin del intervalo de fechas (inclusive), YYYY-MM-DD
  • sending_domain_ids (opcional): Limita los resultados a estos ID de dominio (matriz de enteros)
  • sources (opcional): campaigns o automations limita las estadísticas a esa fuente; omítelo o pasa ambos para incluir todo el tráfico de Email Marketing (matriz de cadenas)
  • email_service_providers (opcional): Limita a estos proveedores, por ejemplo, Google, Yahoo, Outlook (matriz de cadenas)

create-template

Crea una nueva plantilla de correo electrónico en tu cuenta de Mailtrap.

Parámetros:

  • name (obligatorio): Nombre de la plantilla
  • subject (obligatorio): Asunto del correo electrónico
  • html (o text es obligatorio): Contenido HTML de la plantilla
  • text (o html es obligatorio): Versión de texto sin formato de la plantilla
  • category (opcional): Categoría de la plantilla (el valor predeterminado es "General")

list-templates

Muestra las plantillas de correo electrónico de tu cuenta de Mailtrap con paginación mediante tokens de página. Si hay más plantillas, el resultado indica el token de la página siguiente. Las páginas son desplazamientos en la lista ordenada de más reciente a más antigua; por eso, después de eliminar plantillas, vuelve a listar desde token 1 en lugar de continuar con el siguiente token. Una página vacía indica la última página que aún contiene plantillas.

Parámetros:

  • token (opcional): Número de página que se recuperará (paginación mediante tokens de página). El valor predeterminado es 1
  • per_page (opcional): Número de plantillas por página. El valor predeterminado es 50; el máximo es 100. Pasa el mismo valor en cada página

get-template

Obtiene una plantilla de correo electrónico por ID, incluidos el asunto, la categoría y el cuerpo HTML/texto.

Parámetros:

  • template_id (obligatorio): ID de la plantilla que se obtendrá

update-template

Actualiza una plantilla de correo electrónico existente.

Parámetros:

  • template_id (obligatorio): ID de la plantilla que se actualizará
  • name (opcional): Nuevo nombre de la plantilla
  • subject (opcional): Nuevo asunto del correo electrónico
  • html (opcional): Nuevo contenido HTML de la plantilla
  • text (opcional): Nueva versión de texto sin formato de la plantilla
  • category (opcional): Nueva categoría de la plantilla

[!NOTE] Al llamar a update-template para realizar una actualización, se debe proporcionar al menos un campo actualizable (name, subject, html, text o category).

delete-template

Elimina una plantilla de correo electrónico existente.

Parámetros:

  • template_id (obligatorio): ID de la plantilla que se eliminará

send-sandbox-email

Envía un correo electrónico a tu sandbox de Mailtrap con fines de desarrollo y pruebas. Es ideal para probar plantillas de correo electrónico sin enviar mensajes a destinatarios reales. Admite los mismos dos modos que send-email: contenido en línea o basado en plantilla (template_uuid).

Parámetros:

  • sandbox_id (opcional): Preferido. ID del sandbox de Mailtrap. Obligatorio a menos que se establezca MAILTRAP_SANDBOX_ID.
  • test_inbox_id (opcional): Alias heredado de sandbox_id cuando se omite sandbox_id.
  • from (opcional): Remitente como { email, name? } (también se acepta en tiempo de ejecución una cadena de correo electrónico sin formato). Si no se proporciona, se usa DEFAULT_FROM_EMAIL.
  • to (opcional): Matriz de destinatarios como objetos { email, name? } (también se aceptan en tiempo de ejecución cadenas de correo electrónico sin formato en la matriz o una cadena de correos electrónicos simples separados por comas). Es opcional si se proporciona cc o bcc; al menos uno de to / cc / bcc debe contener un destinatario.
  • cc (opcional): Matriz de destinatarios en copia (CC) como objetos { email, name? } (también se aceptan en tiempo de ejecución cadenas de correo electrónico sin formato).
  • bcc (opcional): Matriz de destinatarios en copia oculta (BCC) como objetos { email, name? } (también se aceptan en tiempo de ejecución cadenas de correo electrónico sin formato).
  • subject (condicional): Asunto del correo electrónico. Obligatorio para los envíos en línea; debe omitirse cuando se establece template_uuid.
  • text (condicional): Texto del cuerpo del correo electrónico. Obligatorio (junto con html o en su lugar) para los envíos en línea; debe omitirse cuando se establece template_uuid.
  • html (condicional): Versión HTML del cuerpo del correo electrónico. Obligatoria (junto con text o en su lugar) para los envíos en línea; debe omitirse cuando se establece template_uuid.
  • category (opcional): Categoría del correo electrónico para el seguimiento. Debe omitirse cuando se establece template_uuid.
  • template_uuid (opcional): Usa una plantilla de correo electrónico de Mailtrap en lugar de contenido en línea. Cuando se establece, deben omitirse subject / text / html / category.
  • template_variables (opcional): Objeto de variables que se sustituyen en la plantilla a la que hace referencia template_uuid. Solo se permite junto con template_uuid.

batch-send-sandbox-email

Envía un lote de correos electrónicos a tu sandbox de Mailtrap en una sola llamada a la API, sin entregarlos a destinatarios reales. Tiene la misma estructura de base + requests[], las mismas reglas de validación y las mismas reglas para contenido en línea frente a plantillas que batch-send-transactional-email; la diferencia es que esta herramienta dirige la llamada al endpoint del sandbox para un único sandbox.

Parámetros:

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

[!NOTE] La mayoría de las herramientas de sandbox usan sandbox_id (o recurren a MAILTRAP_SANDBOX_ID; la variable de entorno obsoleta MAILTRAP_TEST_INBOX_ID sigue funcionando). send-sandbox-email, get-sandbox-messages y show-sandbox-email-message también aceptan el valor heredado test_inbox_id. get-sandbox, update-sandbox, delete-sandbox y clean-sandbox usan sandbox_id con el valor heredado inbox_id (el mismo ID; inbox_id no se usa en las herramientas de mensajes). Las herramientas de correo entrante usan inbox_id para un producto diferente (correo recibido), no para el sandbox.

get-sandbox-messages

Recupera una lista de mensajes de tu sandbox de Mailtrap. Es útil para comprobar qué correos electrónicos se han recibido en el sandbox durante las pruebas.

Parámetros:

  • sandbox_id (opcional): Preferido. ID del sandbox, a menos que se establezca MAILTRAP_SANDBOX_ID.
  • test_inbox_id (opcional): Alias heredado de sandbox_id.
  • page (opcional): Número de página para la paginación (mínimo: 1)
  • last_id (opcional): Paginación mediante el ID del último mensaje. Devuelve los mensajes posteriores al ID de mensaje especificado (mínimo: 1)
  • search (opcional): Consulta de búsqueda para filtrar mensajes

[!NOTE] Los parámetros del ID del sandbox son opcionales cuando se establece MAILTRAP_SANDBOX_ID. Si no se proporciona ninguno de sandbox_id, test_inbox_id o la variable de entorno, la llamada falla. Paginación: usa page, last_id o search según sea necesario.

show-sandbox-email-message

Muestra información detallada y el contenido de un mensaje de correo electrónico específico de tu sandbox de Mailtrap, incluido el contenido del cuerpo en HTML y texto.

Parámetros:

  • sandbox_id (opcional): Preferido. ID del sandbox, a menos que se establezca MAILTRAP_SANDBOX_ID.
  • test_inbox_id (opcional): Alias heredado de sandbox_id.
  • message_id (obligatorio): ID del mensaje de correo electrónico del sandbox que se va a recuperar

[!NOTE] Usa primero get-sandbox-messages para obtener los ID de los mensajes y, después, esta herramienta para consultar el contenido completo.

list-sandbox-projects

Enumera todos los proyectos de sandbox y sus sandboxes.

Parámetros:

  • No se requieren parámetros

create-sandbox-project

Crea un nuevo proyecto de sandbox para agrupar sandboxes.

Parámetros:

  • name (obligatorio): Nombre del proyecto (de 2 a 100 caracteres)

get-sandbox-project

Obtiene un proyecto de sandbox por ID, incluidos sus sandboxes y el recuento de correos electrónicos.

Parámetros:

  • project_id (obligatorio): ID del proyecto que se va a obtener

update-sandbox-project

Cambia el nombre de un proyecto de sandbox existente.

Parámetros:

  • project_id (obligatorio): ID del proyecto que se va a actualizar
  • name (obligatorio): Nuevo nombre del proyecto (de 2 a 100 caracteres)

delete-sandbox-project

Elimina un proyecto de sandbox y todos sus sandboxes.

Parámetros:

  • project_id (obligatorio): ID del proyecto que se va a eliminar

create-sandbox

Crea un nuevo sandbox dentro de un proyecto. Devuelve las nuevas credenciales SMTP del sandbox.

Parámetros:

  • project_id (obligatorio): ID del proyecto en el que se va a crear el sandbox
  • name (obligatorio): Nombre del sandbox

get-sandbox

Obtiene los detalles del sandbox, incluidas las credenciales SMTP, el recuento de correos electrónicos y el estado.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Obligatorio a menos que se establezca MAILTRAP_SANDBOX_ID.
  • inbox_id (opcional): Alias heredado de sandbox_id.

update-sandbox

Actualiza el nombre o el nombre de usuario de correo electrónico de un sandbox.

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox (alias heredado: inbox_id)
  • name (opcional): Nuevo nombre del sandbox
  • email_username (opcional): Nuevo nombre de usuario de correo electrónico del sandbox

Debe proporcionarse al menos uno de name o email_username.

delete-sandbox

Elimina un sandbox y todos sus mensajes.

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox (alias heredado: inbox_id)

clean-sandbox

Elimina todos los mensajes de un sandbox sin eliminar el sandbox.

Parámetros:

  • sandbox_id (obligatorio): ID del sandbox (alias heredado: inbox_id)

list-sandboxes

Enumera todos los sandboxes a los que puede acceder el token de API en todos los proyectos.

Parámetros:

  • No se requieren parámetros

mark-sandbox-as-read

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

Parámetros:

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

reset-sandbox-credentials

Restablece las credenciales SMTP de un sandbox. Devuelve el nuevo nombre de usuario y la nueva contraseña.

Parámetros:

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

enable-sandbox-email-address

Activa la dirección de recepción de correo electrónico de un sandbox (habilita la dirección de Mailtrap que entrega mensajes al sandbox mediante SMTP).

Parámetros:

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

reset-sandbox-email-address

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

Parámetros:

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

forward-sandbox-message

Reenvía un mensaje del sandbox a una dirección de correo electrónico externa. Se descuenta de tu cuota mensual de reenvíos.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox que se va a reenviar
  • email (obligatorio): Dirección de correo electrónico a la que se 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. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox que se va a actualizar
  • is_read (obligatorio): true lo marca como leído; false lo marca como no leído

delete-sandbox-message

Elimina un único mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox que se va a eliminar

get-sandbox-message-spam-score

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

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html-analysis

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

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-headers

Obtiene los encabezados de correo analizados de un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html

Obtiene el cuerpo HTML renderizado de un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-text

Obtiene el cuerpo de texto sin formato de un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-raw

Obtiene el mensaje sin procesar, con formato MIME (encabezados + cuerpo), de un mensaje del sandbox.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-eml

Obtiene el mensaje renderizado como contenido de un archivo EML (apto para adjuntarlo a un ticket o importarlo en otro cliente de correo).

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-message-html-source

Obtiene el código fuente HTML sin renderizar de un mensaje del sandbox (HTML antes de cualquier transformación de Mailtrap, como la reescritura de enlaces CID).

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

list-sandbox-attachments

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

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox

get-sandbox-attachment

Obtiene los metadatos y la URL de descarga de un único archivo adjunto.

Parámetros:

  • sandbox_id (opcional): ID del sandbox. Si no se especifica, se usa MAILTRAP_SANDBOX_ID.
  • message_id (obligatorio): ID del mensaje del sandbox que contiene el archivo adjunto
  • attachment_id (obligatorio): ID del archivo adjunto que se va a obtener

list-domains

Enumera los dominios y el estado de verificación de sus DNS.

Parámetros:

  • No se requieren parámetros

get-domain

Obtiene un dominio por ID y su estado de verificación (incluidos los registros DNS). Opcionalmente, incluye instrucciones de configuración de DNS estableciendo include_setup_instructions en true.

Parámetros:

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

create-domain

Crea un dominio nuevo. Después de crearlo, añade registros DNS para verificar el dominio (usa get-domain con include_setup_instructions: true para ver los registros).

Parámetros:

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

update-domain

Actualiza la configuración de seguimiento y recepción de un dominio.

Parámetros:

  • domain_id (obligatorio): ID del dominio (alias heredado: sending_domain_id)
  • open_tracking_enabled (opcional): Habilitar el seguimiento de aperturas de los correos enviados desde este dominio
  • click_tracking_enabled (opcional): Habilitar el seguimiento de clics en los enlaces de los correos enviados desde este dominio
  • tracking_opt_out_enabled (opcional): Añadir el enlace para excluirse del seguimiento a los correos con seguimiento habilitado. Requiere el seguimiento de aperturas o clics
  • auto_unsubscribe_link_enabled (opcional): Añadir automáticamente un enlace para cancelar la suscripción a los correos
  • inbound_enabled (opcional): Permitir que el dominio se asocie a una bandeja de entrada para recibir todos los mensajes

Se debe proporcionar al menos una configuración además de domain_id.

delete-domain

Eliminar un dominio.

Parámetros:

  • domain_id (obligatorio): ID del dominio que se eliminará (alias heredado: sending_domain_id)

send-domain-setup-instructions

Enviar por correo electrónico las instrucciones de configuración de DNS de un dominio a una dirección determinada. Es útil para reenviar los registros DNS a un compañero del equipo de DevOps.

Parámetros:

  • domain_id (obligatorio): ID del dominio (alias heredado: sending_domain_id)
  • email (obligatorio): Dirección de correo electrónico a la que se enviarán las instrucciones de configuración de DNS

get-company-info

Obtener la información de la empresa de un dominio, utilizada para verificar el cumplimiento del dominio.

Parámetros:

  • domain_id (obligatorio): ID del dominio (alias heredado: sending_domain_id)

create-company-info

Establecer la información de la empresa de un dominio, necesaria para verificar el cumplimiento del dominio.

Parámetros:

  • domain_id (obligatorio): ID del dominio (alias heredado: sending_domain_id)
  • name (obligatorio): Nombre de la empresa o de la persona
  • address (obligatorio): Dirección
  • city (obligatorio): Ciudad
  • country (obligatorio): País
  • zip_code (obligatorio): Código postal
  • 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 la política de privacidad
  • terms_of_service_url (opcional): URL de la página de los términos del servicio
  • info_level (opcional): business o individual

update-company-info

Actualizar la información de la empresa de un dominio.

Parámetros:

  • domain_id (obligatorio): ID del dominio (alias heredado: sending_domain_id)
  • Todos los campos de create-company-info son opcionales. Se debe proporcionar al menos uno; los campos omitidos no se modifican.

list-suppressions

Enumerar o buscar las supresiones (rebotes permanentes, quejas por spam, cancelaciones de suscripción e importaciones manuales). Devuelve hasta 1000 resultados por llamada.

Parámetros:

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

create-suppression

Añadir una dirección de correo electrónico a la lista de supresión de la cuenta para que Mailtrap deje de enviarle mensajes.

Parámetros:

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

delete-suppression

Eliminar una supresión por ID. Mailtrap reanudará el envío a esta dirección, a menos que vuelva a suprimirse.

Parámetros:

  • suppression_id (obligatorio): ID de la supresión que se eliminará

list-tracking-opt-outs

Enumerar 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 las exclusiones que coincidan con esta dirección
  • start_time (opcional): Solo las exclusiones creadas en este momento o después (ISO 8601)
  • end_time (opcional): Solo las exclusiones creadas en este momento o antes (ISO 8601)
  • last_id (opcional): Cursor de paginación: el last_id de la respuesta anterior

create-tracking-opt-out

Excluir una dirección de correo electrónico del seguimiento de aperturas y clics de un dominio.

Parámetros:

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

delete-tracking-opt-out

Eliminar una dirección de correo electrónico de la lista de exclusión del seguimiento para volver a aplicar el seguimiento de aperturas y clics.

Parámetros:

  • tracking_opt_out_id (obligatorio): ID de la exclusión del seguimiento que se eliminará

list-webhooks

Enumerar todos los webhooks configurados para la cuenta. Devuelve los registros completos de los webhooks en formato JSON.

Parámetros:

  • No se requieren parámetros

get-webhook

Obtener un webhook por ID. Devuelve el registro completo del webhook en formato 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 que se obtendrá

create-webhook

Crear un webhook. La respuesta incluye un signing_secret para verificar las firmas de las cargas útiles del webhook. Este secreto se devuelve solo al crearlo, así que guárdalo ahora. Si lo pierdes, vuelve a crear el webhook.

Parámetros:

  • url (obligatorio): URL a la que Mailtrap enviará eventos del webhook mediante POST
  • webhook_type (obligatorio): "email_sending", "audit_log" o "inbound_receiving"
  • active (opcional, booleano): el valor predeterminado es true
  • payload_format (opcional): "json" o "jsonlines". El valor predeterminado es "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 al que se limitará este webhook
  • inbound_inbox_id (opcional, solo inbound_receiving): ID de la bandeja de entrada a la que está vinculado el webhook; omítelo para aplicarlo a todas las bandejas de entrada de la cuenta

update-webhook

Actualizar los campos modificables de un webhook. webhook_type, sending_stream y domain_id no se pueden cambiar después de la creación; vuelve a crear el webhook si necesitas modificarlos.

Parámetros:

  • webhook_id (obligatorio): ID del webhook que se actualizará
  • url (opcional): Nueva URL del webhook
  • active (opcional, booleano): Habilitar o deshabilitar 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 a la que está vinculado el webhook

delete-webhook

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

Parámetros:

  • webhook_id (obligatorio): ID del webhook que se eliminará

get-contact

Obtener un contacto por ID o correo electrónico. Devuelve el registro completo del contacto (pertenencia a listas, estado y campos personalizados).

Parámetros:

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

create-contact

Crear un contacto nuevo.

Parámetros:

  • email (obligatorio): Dirección de correo electrónico
  • fields (opcional): Valores de campos personalizados identificados por etiqueta de combinación (p. ej., first_name). Valores de tipo cadena, número o booleano
  • list_ids (opcional): ID de las listas de contactos a las que se suscribirá este contacto
  • unsubscribed (opcional, booleano): Crear el contacto con el estado unsubscribed

update-contact

Actualizar un contacto existente identificado por ID o correo electrónico. list_ids reemplaza el conjunto completo de listas del contacto; list_ids_included/list_ids_excluded añaden o eliminan listas sin modificar las demás.

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 identificados por etiqueta de combinación
  • list_ids (opcional): Reemplazar el conjunto de listas por esta lista exacta
  • list_ids_included (opcional): ID de las listas que se añadirán (aditivo)
  • list_ids_excluded (opcional): ID de las listas que se eliminarán
  • unsubscribed (opcional, booleano): Establecer en unsubscribed (true) o subscribed (false)

delete-contact

Eliminar permanentemente un contacto por ID o correo electrónico. Devuelve el registro del contacto eliminado si la API responde con uno; de lo contrario, devuelve una carga útil de confirmación.

Parámetros:

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

create-contact-event

Registrar un evento de contacto para 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 activadores de automatización)
  • params (obligatorio): Objeto de pares clave/valor arbitrarios. Los valores pueden ser cadenas, números, booleanos o null

list-contact-lists

Enumerar todas las listas de contactos de la cuenta.

Parámetros:

  • search (opcional): Filtrar las listas de contactos por nombre (coincidencia sin distinguir mayúsculas y minúsculas), p. ej., news

get-contact-list

Obtener una lista de contactos por ID.

Parámetros:

  • list_id (obligatorio): ID de la lista de contactos que se obtendrá

create-contact-list

Crear una lista de contactos nueva.

Parámetros:

  • name (obligatorio): Nombre de la lista nueva

update-contact-list

Cambiar el nombre de una lista de contactos existente.

Parámetros:

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

delete-contact-list

Eliminar permanentemente una lista de contactos por ID.

Parámetros:

  • list_id (obligatorio): ID de la lista de contactos que se eliminará

list-contact-fields

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

Parámetros:

  • No se requieren parámetros

get-contact-field

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

Parámetros:

  • field_id (obligatorio): ID del campo de contacto

create-contact-field

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

Parámetros:

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

update-contact-field

Actualizar 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 seguir siendo única)
  • data_type (opcional): Uno de text, number, boolean, date

delete-contact-field

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

Parámetros:

  • field_id (obligatorio): ID del campo de contacto que se eliminará

create-contact-import

Importar contactos en bloque. Devuelve un registro del trabajo de importación; consulta su estado con get-contact-import.

Parámetros:

  • contacts (obligatorio): Matriz de entradas de contacto. Cada entrada requiere:
    • email (obligatorio): Dirección de correo electrónico del contacto
    • fields (opcional): Valores de campos personalizados identificados por etiqueta de combinación (valores de tipo cadena o número)
    • list_ids_included (opcional): ID de las listas a las que se añadirá el contacto
    • list_ids_excluded (opcional): ID de las listas de las que se eliminará el contacto

get-contact-import

Obtener el estado de un trabajo de importación de contactos (created/started/finished/failed), junto con los recuentos de contactos creados, actualizados y que superan el límite.

Parámetros:

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

create-contact-export

Exportar los contactos que coincidan con un conjunto de filtros combinados mediante AND. Devuelve un registro del trabajo de exportación; consulta su estado con get-contact-export para obtener la URL de descarga cuando status sea finished.

Parámetros:

  • filters (obligatorio): Array de objetos de filtro. Cada uno tiene:
    • name (obligatorio): Campo por el que 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 array)

get-contact-export

Obtener el estado de una tarea de exportación de contactos. Cuando status sea finished, el campo url contiene el enlace de descarga del CSV.

Parámetros:

  • export_id (obligatorio): ID de la tarea de exportación de contactos

list-email-campaigns

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

Parámetros:

  • token (opcional): Número de página que se recuperará (paginación mediante 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 distinguir mayúsculas de minúsculas)

get-email-campaign

Obtener 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

Crear una nueva campaña de correo electrónico. La campaña siempre se crea en el estado draft; programarla e iniciarla son acciones independientes (schedule-email-campaign, start-email-campaign).

Parámetros:

  • name (obligatorio): Nombre de la campaña
  • domain_id (obligatorio): ID del dominio verificado que se usará para la campaña, tal como lo devuelve list-domains
  • from_local_part (obligatorio): Parte local (antes de @) de la dirección del remitente
  • template_attributes (obligatorio): Plantilla de correo electrónico integrada. Tiene:
    • subject (obligatorio): Asunto del correo electrónico (máximo 255 caracteres). Admite etiquetas de combinación, por ejemplo, Hi {{first_name}}
    • body_html (opcional): Cuerpo HTML (el diseño). Es obligatorio antes de programar o iniciar la campaña. Incluye un enlace para cancelar la suscripción mediante un ancla cuyo href contenga el marcador de posición __unsubscribe_url__
    • body_text (opcional): Versión alternativa en texto sin formato del cuerpo del correo electrónico
    • merge_tags (opcional): Nombres sin formato de las etiquetas de combinación utilizadas en el asunto/cuerpo, por ejemplo, ["first_name"]
  • from_display_name (opcional): Nombre visible que aparece 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 la velocidad a delivery_options.emails_per_hour)
  • delivery_options (opcional): Opciones para limitar la velocidad de entrega (emails_per_hour)
  • contact_list_ids (opcional): IDs de las listas de contactos a las que enviar (se consideran el conjunto completo de listas incluidas)
  • contact_segment_ids (opcional): IDs de los segmentos de contactos a los que enviar (se consideran el conjunto completo de segmentos incluidos)

update-email-campaign

Actualizar una campaña de correo electrónico draft. Solo cambian los campos proporcionados; la plantilla se edita en el mismo lugar. No se pueden actualizar campañas en ningún otro estado.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico que se actualizará
  • Todos los demás parámetros son opcionales e idénticos a los de 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

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

Parámetros:

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

start-email-campaign

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

Parámetros:

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

schedule-email-campaign

Programar el inicio del envío de una campaña de correo electrónico draft para una fecha futura. Solo se pueden programar campañas draft.

Parámetros:

  • email_campaign_id (obligatorio): ID de la campaña de correo electrónico que se programará
  • datetime (obligatorio): Cuándo enviar la campaña (ISO 8601). Debe ser una fecha futura y no superar 1 mes de antelación

cancel-email-campaign

Cancelar una campaña de correo electrónico scheduled y devolverla al estado draft. Solo se pueden cancelar campañas scheduled.

Parámetros:

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

terminate-email-campaign

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

Parámetros:

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

reset-email-campaign

Restablecer una campaña de correo electrónico scheduled al estado draft. Solo se pueden restablecer campañas scheduled.

Parámetros:

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

get-email-campaign-stats

Obtener estadísticas de rendimiento agregadas de una campaña de correo electrónico (recuentos y tasas de entregas, aperturas, clics, rebotes, quejas por 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 del período de agregación (inclusive), YYYY-MM-DD. De forma predeterminada, se usa el día en que se inició la campaña por última vez
  • end_date (opcional): Fin del período de agregación (inclusive), YYYY-MM-DD. De forma predeterminada, se usa la fecha actual

list-accounts

Mostrar las cuentas de Mailtrap a las que puede acceder el token de API actual, junto con los niveles de acceso de cada cuenta. Funciona sin MAILTRAP_ACCOUNT_ID, así que úsalo para encontrar el ID de tu cuenta.

Parámetros:

  • No se requieren parámetros

get-billing-usage

Obtener el uso del ciclo de facturación actual de la cuenta: planes de envío y pruebas, límites y recuentos actuales.

Parámetros:

  • No se requieren parámetros

list-account-accesses

Mostrar los accesos a la cuenta (usuarios, invitaciones y tokens de API). Los filtros opcionales limitan los resultados a recursos específicos. Requiere permisos de administrador/propietario de la cuenta.

Parámetros:

  • domain_uuids (opcional): Filtrar por UUID de dominios (array de cadenas)
  • inbox_ids (opcional): Filtrar por IDs de sandbox (array de cadenas)
  • project_ids (opcional): Filtrar por IDs de proyectos de sandbox (array de cadenas)

remove-account-access

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

Parámetros:

  • account_access_id (obligatorio): ID del registro de acceso que se eliminará

get-permission-resources

Obtener todos los recursos (sandboxes, proyectos, dominios, facturación y cuenta) para los que el token de API tiene acceso de administrador, anidados según la jerarquía.

Parámetros:

  • No se requieren parámetros

bulk-update-permissions

Crear, actualizar o eliminar permisos en bloque para un único acceso a la cuenta. Se actualizan los pares (resource_type, resource_id) existentes; los nuevos se crean. Establece destroy: true en una entrada para eliminarla.

Parámetros:

  • account_access_id (obligatorio): ID del acceso a la cuenta de destino
  • permissions (obligatorio): Array 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 true, elimina este permiso en lugar de crearlo o actualizarlo

list-api-tokens

Mostrar todos los tokens de API de la cuenta.

Parámetros:

  • No se requieren parámetros

create-api-token

Crear 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 de inmediato. Si lo pierdes, vuelve a crear el token.

Parámetros:

  • name (obligatorio): Nombre visible del token
  • expires_at (opcional): Fecha de vencimiento del token en formato de fecha y hora ISO 8601. Omítelo para usar el valor predeterminado del servidor (1 año); proporciona un null explícito para un token que nunca vence. Se rechazan los valores pasados o los que superen los 5 años de antelación
  • resources (opcional): Array de permisos de recursos para limitar el alcance del 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

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

Parámetros:

  • api_token_id (obligatorio): ID del token de API

reset-api-token

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

Parámetros:

  • api_token_id (obligatorio): ID del token de API que se restablecerá
  • expires_at (opcional): Vencimiento del nuevo token en formato de fecha y hora ISO 8601. Omítelo para usar el valor predeterminado del servidor (1 año); proporciona un null explícito para un token que nunca vence. Se rechazan los valores pasados o los que superen los 5 años de antelación

delete-api-token

Eliminar permanentemente un token de API por ID. El token ya no podrá autenticar después de eliminarlo.

Parámetros:

  • api_token_id (obligatorio): ID del token de API que se eliminará

list-sub-accounts

Mostrar las subcuentas de la organización. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos para administrar subcuentas.

Parámetros:

  • No se requieren parámetros

create-sub-account

Crear una nueva subcuenta en la organización. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos para administrar subcuentas.

Parámetros:

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

delete-sub-account

Eliminar permanentemente una subcuenta por ID y borrar todos sus datos. Al eliminar la última subcuenta, se elimina la organización; una llamada repetida devuelve 404. Si se intenta eliminar simultáneamente la misma subcuenta, se devuelve 409. Requiere la variable de entorno MAILTRAP_ORGANIZATION_ID y permisos de administrador de la organización; además, la organización debe tener habilitada la función Organization & Sub-accounts (de lo contrario, se devuelve 403).

Parámetros:

  • sub_account_id (obligatorio): ID de la subcuenta que se eliminará

list-inbound-folders

Mostrar todas las carpetas de entrada de la cuenta. Devuelve un resumen con formato.

Parámetros:

  • No se requieren parámetros

get-inbound-folder

Obtener una carpeta de entrada por ID. Devuelve el registro completo de la carpeta en formato JSON.

Parámetros:

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

create-inbound-folder

Crear una nueva carpeta de entrada.

Parámetros:

  • name (obligatorio): Nombre de la carpeta

update-inbound-folder

Cambiar el nombre de una carpeta de entrada.

Parámetros:

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

delete-inbound-folder

Eliminar 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

Mostrar todas las bandejas de entrada de una carpeta de entrada. Devuelve un resumen con formato.

Parámetros:

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

get-inbound-inbox

Obtener una bandeja de entrada por ID. Devuelve el registro completo de la bandeja de entrada en formato JSON.

Parámetros:

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

create-inbound-inbox

Crear una nueva bandeja de entrada en una carpeta.

Parámetros:

  • folder_id (obligatorio): ID de la carpeta de entrada
  • name (obligatorio): Nombre de la bandeja de entrada
  • domain_id (opcional): Asociar a un dominio personalizado (bandeja de entrada general). Omitir para una bandeja de entrada alojada en Mailtrap

update-inbound-inbox

Cambiar el nombre de 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

Eliminar 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

Enumerar los mensajes recibidos en una bandeja de entrada (paginación mediante cursor). Devuelve un resumen con formato y una indicación para la página siguiente cuando hay más resultados.

Parámetros:

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

get-inbound-message

Obtener un mensaje entrante con su cuerpo completo y las URL de descarga de los archivos adjuntos. Devuelve el registro completo del mensaje en formato JSON.

Parámetros:

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

delete-inbound-message

Eliminar permanentemente un mensaje entrante.

Parámetros:

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

reply-to-inbound-message

Responder a un mensaje entrante (se envía al remitente original). Envía un correo electrónico real. Las direcciones aceptan una cadena de correo electrónico sin formato 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 (se recomienda al menos uno): Cuerpo de la respuesta
  • from (opcional): Remitente. No se acepta en bandejas de entrada alojadas en Mailtrap; es obligatorio en bandejas de entrada 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 con valores de cadena

reply-all-to-inbound-message

Responder a un mensaje entrante y poner en copia a los demás destinatarios originales. Envía un correo electrónico real. Usa los 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
  • Además, los mismos campos de envío opcionales que reply-to-inbound-message

forward-inbound-message

Reenviar un mensaje entrante a nuevos destinatarios. Envía un correo electrónico real.

Parámetros:

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

list-inbound-threads

Enumerar los hilos de conversación de una bandeja de entrada (paginación mediante cursor), con la opción de filtrar por search. Devuelve un resumen con formato y una indicación para la página siguiente cuando hay más resultados.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • last_id (opcional): Cursor de paginación de last_id de una respuesta anterior
  • search (opcional): Texto que no distingue entre mayúsculas y minúsculas, que se compara con el asunto del hilo y las direcciones de remitente, destinatario, copia y copia oculta de sus mensajes. Pasa el mismo valor al paginar

get-inbound-thread

Obtener un hilo entrante con sus mensajes incluidos (del más antiguo al más reciente). Devuelve el registro completo del hilo en formato JSON.

Parámetros:

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

delete-inbound-thread

Eliminar permanentemente un hilo entrante.

Parámetros:

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

list-inbound-forward-rules

Enumerar las reglas de reenvío de una bandeja de entrada. Devuelve un resumen con formato.

Parámetros:

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

get-inbound-forward-rule

Obtener una regla de reenvío entrante por su ID. Devuelve el registro completo de la regla, incluidas sus condiciones y destinos, en formato JSON.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • forward_rule_id (obligatorio): ID de la regla de reenvío

create-inbound-forward-rule

Crear una regla de reenvío en una bandeja de entrada. Los mensajes recibidos que cumplan todas las condiciones se reenvían a los destinos de la regla.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • name (obligatorio): Nombre de la regla, único dentro de la bandeja de entrada
  • conditions (opcional): Matriz de { match_type, operator, value?, header_key? }. match_type es sender, recipient o header; operator es equal, not_equal, contains, starts_with, ends_with, empty o not_empty (solo empty/not_empty para header, y no aceptan value); header_key es obligatorio para header. Omitir o pasar [] para que coincida con todos los mensajes
  • destinations (opcional): Matriz de { email } a los que reenviar los mensajes coincidentes

update-inbound-forward-rule

Actualizar una regla de reenvío entrante. Solo cambian los campos proporcionados; si se proporciona una matriz de conditions o destinations, se reemplaza el conjunto completo.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • forward_rule_id (obligatorio): ID de la regla de reenvío
  • name (opcional): Nuevo nombre de la regla
  • conditions (opcional): Conjunto de condiciones de reemplazo (misma estructura que al crear); [] elimina todas las condiciones, por lo que la regla coincide con todos los mensajes
  • destinations (opcional): Conjunto de destinos de reemplazo; [] elimina todos los destinos

delete-inbound-forward-rule

Eliminar permanentemente una regla de reenvío entrante.

Parámetros:

  • inbox_id (obligatorio): ID de la bandeja de entrada
  • forward_rule_id (obligatorio): ID de la regla de reenvío

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_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Si usas asdf para administrar 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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_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_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

Pruebas

Ejecutar herramientas con Mailtrap real

Hay dos formas de probar una herramienta de principio a fin con una cuenta real de Mailtrap: la interfaz del navegador de MCP Inspector para la exploración interactiva, o su modo CLI para realizar llamadas puntuales desde el shell.

En ambos casos, primero hay que compilar el paquete:

npm run build

y exportar MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID en el shell (el script mcp:cli pasa ambos al servidor iniciado).

Interfaz del navegador

npm run dev

Inspector muestra una URL como http://localhost:6274. Ábrela, cambia a la pestaña Tools, elige una herramienta (por ejemplo, get-template), completa los parámetros en formato JSON y haz clic en Run. La respuesta de Mailtrap aparece en el panel de abajo.

CLI

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

# 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-domain-setup-instructions \
  --tool-arg 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 desarrollar con MCP Inspector:

npm run dev:mcpb

Gestión de errores

Este servidor usa una gestión de errores estructurada y alineada con las convenciones de MCP:

  • VALIDATION_ERROR: Errores de validación de entrada
  • CONFIGURATION_ERROR: Configuración ausente o no válida
  • EXECUTION_ERROR: Errores de ejecución
  • TIMEOUT: Tiempo de espera de la operación agotado (30 segundos de forma predeterminada)

Los errores incluyen mensajes prácticos y se registran en un formato estructurado.

Seguridad

  • Entradas validadas mediante esquemas de Zod
  • Variables de entorno gestionadas de forma segura
  • Protección contra tiempos de espera en las operaciones (30 segundos)
  • Detalles confidenciales depurados en los mensajes de error

Registro

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

Activa el registro de depuración configurando DEBUG=true.

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

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

Ejemplo de análisis de registros con 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. Falta el token de API: asegúrate de que MAILTRAP_API_TOKEN esté configurado
  2. El sandbox no funciona: proporciona sandbox_id en la llamada a la herramienta (o el valor heredado test_inbox_id en las herramientas de envío, enumeración y visualización de mensajes), o configura la variable de entorno MAILTRAP_SANDBOX_ID
  3. Errores de tiempo de espera: comprueba la conectividad de red y el estado de la API de Mailtrap
  4. Errores de validación: asegúrate de proporcionar todos los campos obligatorios

Contribuciones

Se aceptan informes de errores y solicitudes de incorporación de cambios en GitHub. Este proyecto pretende ser un espacio seguro y acogedor para la colaboración, y se espera que quienes contribuyan respeten 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 todas las personas que interactúen en las bases de código, los rastreadores de incidencias, las salas de chat y las listas de correo del proyecto Mailtrap sigan el código de conducta.