Mailtrap MCP Server

Serveur MCP Mailtrap

Un serveur MCP qui fournit des outils pour envoyer et tester dans le bac à sable via Mailtrap.

Prérequis

Avant d'utiliser ce serveur MCP, vous devez :

1. Créer un compte Mailtrap
2. Vérifier votre domaine
3. Obtenir votre jeton API depuis les paramètres API Mailtrap
4. Obtenir votre ID de compte depuis la gestion de compte Mailtrap

Variables d'environnement requises :

• MAILTRAP_API_TOKEN - Requis pour toutes les fonctionnalités
• MAILTRAP_ACCOUNT_ID - Requis pour les modèles, les statistiques, les journaux d'emails, la liste/affichage du bac à sable et les domaines d'envoi. Optionnel uniquement pour send-email et send-sandbox-email.

Optionnelles (peuvent être passées comme paramètres d'outil à la place) :

• DEFAULT_FROM_EMAIL - Expéditeur par défaut lorsque from n'est pas fourni à send-email ou send-sandbox-email. Permet de changer d'expéditeur à chaque appel via le paramètre from.
• MAILTRAP_TEST_INBOX_ID - ID de boîte de réception de test par défaut pour les outils du bac à sable lorsque test_inbox_id n'est pas fourni. Permet de basculer entre les boîtes de réception à chaque appel via le paramètre test_inbox_id.
• MAILTRAP_SANDBOX_ID - ID de bac à sable par défaut pour les outils du bac à sable lorsque sandbox_id n'est pas fourni. Permet de basculer entre les bacs à sable à chaque appel via le paramètre sandbox_id.
• MAILTRAP_ORGANIZATION_ID - Requis pour les outils d'organisation (list-sub-accounts, create-sub-account).
• MAILTRAP_ORGANIZATION_API_TOKEN - Jeton API limité à l'organisation. Requis pour les outils d'organisation (séparé de MAILTRAP_API_TOKEN).

Installation rapide

CLI Smithery

Smithery est un installateur et gestionnaire de registre pour les serveurs MCP qui fonctionne avec tous les clients IA.

npx @smithery/cli install mailtrap

Smithery gère automatiquement la configuration du client et fournit un processus de configuration interactif. C'est le moyen le plus simple de démarrer avec les serveurs MCP localement.

Configuration

Claude Desktop

Utilisez MCPB pour installer le serveur Mailtrap. Vous pouvez trouver ces fichiers dans les Releases.
Téléchargez le fichier .MCPB et ouvrez-le. Si vous avez Claude Desktop, il l'ouvrira et proposera de le configurer.

Claude Desktop ou Cursor

Ajoutez la configuration suivante :

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Si vous utilisez asdf pour gérer Node.js, vous devez utiliser le chemin absolu vers l'exécutable (exemple pour 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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Emplacement du fichier de configuration de Claude Desktop

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

Windows : %APPDATA%\Claude\claude_desktop_config.json

Emplacement du fichier de configuration de Cursor

Mac : ~/.cursor/mcp.json

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

VS Code

Modification manuelle de la configuration

Exécutez dans la palette de commandes : Preferences: Open User Settings (JSON)

Ensuite, dans le fichier de paramètres, ajoutez la configuration suivante :

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] N'oubliez pas de redémarrer votre serveur MCP après avoir modifié la section "env".

MCP Bundle (MCPB)

Pour une installation facile dans les hôtes qui prennent en charge les bundles MCP, vous pouvez distribuer un fichier bundle .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

Cela crée mailtrap-mcp.mcpb en utilisant le dépôt manifest.json et les artefacts construits dans dist/.

Utilisation

Une fois configuré, vous pouvez demander à l'agent d'envoyer des emails et de gérer les modèles, par exemple :

Opérations d'envoi d'email :

• "Envoie un email à [email protected] avec le sujet 'Réunion demain' et un rappel amical concernant notre prochaine réunion."
• "Envoie un email à [email protected] concernant la mise à jour du projet, et mets l'équipe en copie à [email protected]"
• "Envoie le modèle de bienvenue (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) à [email protected] avec les variables { name: 'Alex' }"
• "Envoie un email de bac à sable à [email protected] avec le sujet 'Modèle de test' pour prévisualiser l'apparence de notre email de bienvenue"

Journaux d'emails (débogage de la distribution) :

• "Liste mes journaux d'emails envoyés récents"
• "Affiche les journaux d'emails pour les emails envoyés à [email protected]"
• "Obtiens le message du journal d'email pour l'ID abc-123-uuid pour vérifier le statut de distribution"

Statistiques d'envoi :

• "Obtiens les statistiques d'envoi pour janvier 2025"
• "Affiche les taux de distribution par domaine pour le mois dernier"
• "Quelles sont mes statistiques d'email par catégorie du 2025-01-01 au 2025-01-31 ?"

Opérations du bac à sable :

• "Obtiens tous les messages de ma boîte de réception du bac à sable"
• "Affiche-moi la première page des messages du bac à sable"
• "Recherche les messages contenant 'test' dans ma boîte de réception du bac à sable"
• "Affiche-moi les détails du message du bac à sable avec l'ID 5159037506"

Opérations sur les modèles :

• "Liste tous les modèles d'email dans mon compte Mailtrap"
• "Crée un nouveau modèle d'email appelé 'Email de bienvenue' avec le sujet 'Bienvenue sur notre plateforme !'"
• "Mets à jour le modèle avec l'ID 12345 pour changer le sujet en 'Message de bienvenue mis à jour'"
• "Supprime le modèle avec l'ID 67890"

Domaines d'envoi :

• "Liste mes domaines d'envoi"
• "Obtiens le domaine d'envoi avec l'ID 3938"
• "Crée un domaine d'envoi pour exemple.com"
• "Supprime le domaine d'envoi 3938"
• "Obtiens le domaine d'envoi 3938 avec les instructions de configuration DNS"

Outils disponibles

send-email

Envoie un email transactionnel via Mailtrap. Prend en charge deux modes mutuellement exclusifs — contenu en ligne (subject + text/html) ou basé sur un modèle (template_uuid).

Paramètres :

• from (optionnel) : Expéditeur sous forme de chaîne d'email ou { email, name? }. S'il n'est pas fourni, DEFAULT_FROM_EMAIL est utilisé.
• to (optionnel) : Destinataire(s) — un seul email/{ email, name? } ou un tableau. Optionnel si cc ou bcc est fourni ; au moins l'un de to / cc / bcc doit contenir un destinataire.
• cc (optionnel) : Tableau de destinataires en copie (chaînes d'email ou { email, name? } chacun).
• bcc (optionnel) : Tableau de destinataires en copie cachée (chaînes d'email ou { email, name? } chacun).
• subject (conditionnel) : Ligne d'objet de l'email. Requis pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• text (conditionnel) : Texte du corps de l'email. Requis (avec ou à la place de html) pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• html (conditionnel) : Version HTML du corps de l'email. Requis (avec ou à la place de text) pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• category (optionnel) : Catégorie d'email pour le suivi et l'analyse. Doit être omis lorsque template_uuid est défini.
• template_uuid (optionnel) : Utilise un modèle d'email Mailtrap au lieu du contenu en ligne. Lorsqu'il est défini, subject / text / html / category doivent être omis (selon l'API Mailtrap).
• template_variables (optionnel) : Objet de variables substituées dans le modèle référencé par template_uuid. Autorisé uniquement avec template_uuid.

batch-send-transactional-email

Envoie un lot d'emails transactionnels en un seul appel API Mailtrap (flux d'envoi par défaut). Les champs partagés vont sur base ; les remplacements par destinataire vont dans requests[]. Chaque requête doit inclure au moins un destinataire via to, cc ou bcc. Même exclusion mutuelle en ligne vs modèle que send-email — vérifiée après fusion de la base avec chaque requête.

Paramètres :

• base (optionnel) : Objet avec les champs partagés dans le lot.
  • from (optionnel) : Expéditeur sous forme de chaîne d'email ou { email, name? }. Se replie sur DEFAULT_FROM_EMAIL.
  • reply_to (optionnel) : Adresse de réponse.
  • subject / text / html / category (optionnel, mode en ligne) : Contenu par défaut pour chaque requête.
  • template_uuid / template_variables (optionnel, mode modèle) : Modèle par défaut + variables. Mutuellement exclusif avec les champs en ligne.
  • custom_variables (optionnel) : Variables personnalisées par défaut (à valeur de chaîne).
  • headers (optionnel) : En-têtes personnalisés par défaut.
• requests (requis) : Tableau non vide de messages par destinataire. Chaque entrée a :
  • to (optionnel) : Destinataire(s) — chaîne, { email, name? } ou un tableau. Optionnel si cc ou bcc est fourni ; au moins l'un de to / cc / bcc doit contenir un destinataire.
  • cc, bcc, reply_to (optionnel).
  • Remplacements en ligne (subject/text/html/category) ou modèle (template_uuid/template_variables) ; tout champ omis se replie sur la valeur base correspondante.
  • custom_variables, headers (optionnel).

batch-send-bulk-email

Envoie un lot d'emails en masse via l'API de flux en masse de Mailtrap. Même forme base + requests[], validation et règles en ligne vs modèle que batch-send-transactional-email — la seule différence est que cet outil achemine l'appel via le point de terminaison en masse au lieu du transactionnel. Voir les paramètres ci-dessus.

list-email-logs

Liste les journaux d'emails envoyés (historique de distribution) avec pagination et filtres optionnels. À utiliser pour déboguer les problèmes de distribution depuis l'IDE.

Paramètres :

• search_after (optionnel) : Curseur de pagination de la réponse précédente next_page_cursor
• sent_after (optionnel) : Date/heure ISO 8601 ; uniquement les journaux envoyés après cette heure
• sent_before (optionnel) : Date/heure ISO 8601 ; uniquement les journaux envoyés avant cette heure
• from_email (optionnel) : Filtrer par email de l'expéditeur ; utiliser avec from_operator (par défaut : ci_equal)
• to_email (optionnel) : Filtrer par email du destinataire ; utiliser avec to_operator (par défaut : ci_equal)
• status (optionnel) : Filtrer par statut de distribution : delivered, not_delivered, enqueued, opted_out ; utiliser avec status_operator (par défaut : equal)
• subject (optionnel) : Filtrer par sujet de l'email ; utiliser avec subject_operator (par défaut : ci_contain). Utiliser subject_operator : empty/not_empty pour filtrer par présence de sujet.
• sending_domain_id (optionnel) : Filtrer par ID de domaine d'envoi (nombre) ; utiliser avec sending_domain_id_operator (par défaut : equal)
• sending_stream (optionnel) : Filtrer par flux : transactional ou bulk ; utiliser avec sending_stream_operator (par défaut : equal)
• events (optionnel) : Filtrer par type(s) d'événement : delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension ; utiliser avec events_operator (include_event / not_include_event)
• clicks_count / opens_count (optionnel) : Filtrer par nombre de clics/ouvertures ; utiliser avec *_operator : equal, greater_than, less_than
• client_ip / sending_ip (optionnel) : Filtrer par IP ; utiliser avec *_operator : equal, not_equal, contain, not_contain
• email_service_provider_response (optionnel) : Filtrer par texte de réponse du fournisseur ; utiliser avec *_operator (ci_contain, etc.)
• email_service_provider (optionnel) : Filtrer par fournisseur (exact) ; utiliser avec *_operator : equal, not_equal
• recipient_mx (optionnel) : Filtrer par MX du destinataire ; utiliser avec recipient_mx_operator (ci_contain, etc.)
• category (optionnel) : Filtrer par catégorie d'email ; utiliser avec category_operator : equal, not_equal

Tous les paramètres sont optionnels.

get-email-log-message

Obtient un seul message de journal d'email par ID (UUID) : un résumé lisible (de, à, sujet, heure d'envoi, statut, catégorie, flux, engagement, contexte de distribution), puis l'historique détaillé des événements. Optionnellement, avec include_content: true, vous pouvez également charger et afficher le corps du message (HTML et texte brut) lorsque Mailtrap expose une URL de message brut.

Paramètres :

• message_id (requis) : UUID du message de journal d'email (de la réponse d'envoi ou de list-email-logs). Utilisez list-email-logs pour trouver les ID de message.
• include_content (optionnel) : Lorsque true, récupère l'EML brut (si raw_message_url est disponible) et ajoute les sections de corps HTML et texte brut analysées, similaire à show-sandbox-email-message.

get-sending-stats

Obtenez les statistiques d'envoi d'emails (taux de distribution, rebond, ouverture, clic, spam) pour une plage de dates. Décomposez éventuellement par domaine, catégorie, fournisseur de services de messagerie ou date. Vérifiez les taux de distribution sans quitter l'éditeur.

Paramètres :

• start_date (obligatoire) : Date de début de la plage de statistiques (AAAA-MM-JJ)
• end_date (obligatoire) : Date de fin de la plage de statistiques (AAAA-MM-JJ)
• breakdown (facultatif) : Mode de ventilation des statistiques : aggregated (par défaut), by_domain, by_category, by_email_service_provider ou by_date
• sending_domain_ids (facultatif) : Limiter les résultats à ces identifiants de domaine d'envoi (tableau d'entiers)
• sending_streams (facultatif) : Limiter à transactional et/ou bulk (tableau de chaînes)
• categories (facultatif) : Limiter à ces catégories d'e-mails (tableau de chaînes)
• email_service_providers (facultatif) : Limiter à ces fournisseurs, par ex. Google, Yahoo, Outlook (tableau de chaînes)

create-template

Crée un nouveau modèle d'e-mail dans votre compte Mailtrap.

Paramètres :

• name (obligatoire) : Nom du modèle
• subject (obligatoire) : Ligne d'objet de l'e-mail
• html (ou text est obligatoire) : Contenu HTML du modèle
• text (ou html est obligatoire) : Version texte brut du modèle
• category (facultatif) : Catégorie du modèle (par défaut « General »)

list-templates

Liste tous les modèles d'e-mails de votre compte Mailtrap.

Paramètres :

• Aucun paramètre requis

get-template

Récupère un modèle d'e-mail unique par son ID, y compris l'objet, la catégorie et le corps HTML/texte.

Paramètres :

• template_id (obligatoire) : ID du modèle à récupérer

update-template

Met à jour un modèle d'e-mail existant.

Paramètres :

• template_id (obligatoire) : ID du modèle à mettre à jour
• name (facultatif) : Nouveau nom du modèle
• subject (facultatif) : Nouvelle ligne d'objet de l'e-mail
• html (facultatif) : Nouveau contenu HTML du modèle
• text (facultatif) : Nouvelle version texte brut du modèle
• category (facultatif) : Nouvelle catégorie du modèle

[!NOTE] Au moins un champ modifiable (nom, objet, html, texte ou catégorie) doit être fourni lors de l'appel à update-template pour effectuer une mise à jour.

delete-template

Supprime un modèle d'e-mail existant.

Paramètres :

• template_id (obligatoire) : ID du modèle à supprimer

send-sandbox-email

Envoie un e-mail à votre boîte de réception de test Mailtrap à des fins de développement et de test. Idéal pour tester des modèles d'e-mails sans envoyer d'e-mails à de vrais destinataires. Prend en charge les deux mêmes modes que send-email — contenu en ligne ou basé sur un modèle (template_uuid).

Paramètres :

• test_inbox_id (facultatif) : ID de la boîte de réception de test Mailtrap. Obligatoire sauf si MAILTRAP_TEST_INBOX_ID est défini ; à passer par appel pour cibler une boîte de réception spécifique.
• from (facultatif) : Expéditeur sous forme de chaîne d'e-mail ou { email, name? }. S'il n'est pas fourni, DEFAULT_FROM_EMAIL est utilisé.
• to (facultatif) : Destinataires sous forme de chaîne séparée par des virgules, ou d'un tableau de chaînes d'e-mails / objets { email, name? }. Facultatif si cc ou bcc est fourni ; au moins l'un de to / cc / bcc doit contenir un destinataire.
• cc (facultatif) : Tableau de destinataires en copie (chaînes d'e-mails ou { email, name? } chacun).
• bcc (facultatif) : Tableau de destinataires en copie cachée (chaînes d'e-mails ou { email, name? } chacun).
• subject (conditionnel) : Ligne d'objet de l'e-mail. Obligatoire pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• text (conditionnel) : Texte du corps de l'e-mail. Obligatoire (avec ou à la place de html) pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• html (conditionnel) : Version HTML du corps de l'e-mail. Obligatoire (avec ou à la place de text) pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• category (facultatif) : Catégorie d'e-mail pour le suivi. Doit être omis lorsque template_uuid est défini.
• template_uuid (facultatif) : Utiliser un modèle d'e-mail Mailtrap au lieu du contenu en ligne. Lorsqu'il est défini, subject / text / html / category doivent être omis.
• template_variables (facultatif) : Objet de variables substituées dans le modèle référencé par template_uuid. Autorisé uniquement avec template_uuid.

[!NOTE] Pour les outils sandbox, fournissez test_inbox_id dans l'appel d'outil ou définissez la variable d'environnement MAILTRAP_TEST_INBOX_ID. Vous pouvez basculer entre les boîtes de réception par appel en passant test_inbox_id.

get-sandbox-messages

Récupère une liste de messages de votre boîte de réception de test Mailtrap. Utile pour vérifier quels e-mails ont été reçus dans votre sandbox pendant les tests.

Paramètres :

• page (facultatif) : Numéro de page pour la pagination (minimum : 1)
• last_id (facultatif) : Pagination utilisant le dernier ID de message. Renvoie les messages après l'ID de message spécifié (minimum : 1)
• search (facultatif) : Requête de recherche pour filtrer les messages

[!NOTE] Tous les paramètres sont facultatifs. Si aucun n'est fourni, la première page de messages de la boîte de réception sera renvoyée. Utilisez page pour une pagination traditionnelle, last_id pour une pagination basée sur un curseur, ou search pour filtrer les messages par contenu.

show-sandbox-email-message

Affiche les informations détaillées et le contenu d'un message électronique spécifique de votre boîte de réception de test Mailtrap, y compris le contenu du corps HTML et texte.

Paramètres :

• message_id (obligatoire) : ID du message électronique sandbox à récupérer

[!NOTE] Utilisez d'abord get-sandbox-messages pour obtenir la liste des messages et leurs ID, puis utilisez cet outil pour afficher le contenu complet d'un message spécifique.

get-sandbox-project

Récupère un projet sandbox par son ID, y compris ses boîtes de réception et le nombre d'e-mails.

Paramètres :

• project_id (obligatoire) : ID du projet à récupérer

update-sandbox-project

Renomme un projet sandbox existant.

Paramètres :

• project_id (obligatoire) : ID du projet à mettre à jour
• name (obligatoire) : Nouveau nom du projet (2 à 100 caractères)

list-sandboxes

Liste chaque sandbox accessible au jeton API sur tous les projets.

Paramètres :

• Aucun paramètre requis

mark-sandbox-as-read

Marque tous les messages d'un sandbox comme lus.

Paramètres :

• sandbox_id (obligatoire) : ID du sandbox sur lequel agir

reset-sandbox-credentials

Réinitialise les informations d'identification SMTP d'un sandbox. Renvoie le nouveau nom d'utilisateur/mot de passe.

Paramètres :

• sandbox_id (obligatoire) : ID du sandbox sur lequel agir

enable-sandbox-email-address

Active l'adresse de réception par e-mail pour un sandbox (active l'adresse Mailtrap qui délivre les messages au sandbox via SMTP).

Paramètres :

• sandbox_id (obligatoire) : ID du sandbox sur lequel agir

reset-sandbox-email-address

Génère une nouvelle adresse de réception par e-mail pour un sandbox.

Paramètres :

• sandbox_id (obligatoire) : ID du sandbox sur lequel agir

forward-sandbox-message

Transfère un message sandbox à une adresse e-mail externe. Est décompté de votre quota de transfert mensuel.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox à transférer
• email (obligatoire) : Adresse e-mail à laquelle transférer le message

update-sandbox-message

Marque un message sandbox comme lu ou non lu.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox à mettre à jour
• is_read (obligatoire) : true marque comme lu, false marque comme non lu

delete-sandbox-message

Supprime un seul message sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox à supprimer

get-sandbox-message-spam-score

Récupère le rapport de spam SpamAssassin pour un message sandbox (score, règles, rapport complet). Alternative autonome à include_spam_report: true sur show-sandbox-email-message.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-html-analysis

Récupère le rapport d'analyse HTML pour un message sandbox (scores de compatibilité client, éléments problématiques). Alternative autonome à include_html_analysis: true sur show-sandbox-email-message.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-headers

Récupère les en-têtes de courrier analysés pour un message sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-html

Récupère le corps HTML rendu d'un message sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-text

Récupère le corps en texte brut d'un message sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-raw

Récupère le message brut au format MIME (en-têtes + corps) pour un message sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-eml

Récupère le message rendu sous forme de fichier EML (adapté pour être joint à un ticket ou importé dans un autre client de messagerie).

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-message-html-source

Récupère la source HTML non rendue d'un message sandbox (HTML avant toute transformation côté Mailtrap comme les réécritures de liens CID).

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

list-sandbox-attachments

Liste toutes les pièces jointes d'un message sandbox (nom de fichier, type de contenu, taille, chemin de téléchargement).

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox

get-sandbox-attachment

Récupère les métadonnées et l'URL de téléchargement d'une seule pièce jointe.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Se replie sur MAILTRAP_SANDBOX_ID.
• message_id (obligatoire) : ID du message sandbox qui contient la pièce jointe
• attachment_id (obligatoire) : ID de la pièce jointe à récupérer

list-sending-domains

Liste les domaines d'envoi et leur statut de vérification DNS.

Paramètres :

• Aucun paramètre requis

get-sending-domain

Récupère un domaine d'envoi par son ID et son statut de vérification (y compris les enregistrements DNS). Inclut éventuellement les instructions de configuration DNS en définissant include_setup_instructions sur true.

Paramètres :

• sending_domain_id (obligatoire) : ID du domaine d'envoi
• include_setup_instructions (facultatif) : Si true, ajoute les instructions de configuration DNS à la réponse. Par défaut : false

create-sending-domain

Crée un nouveau domaine d'envoi. Après la création, ajoutez les enregistrements DNS pour vérifier le domaine (utilisez get-sending-domain avec include_setup_instructions: true pour voir les enregistrements).

Paramètres :

• domain_name (obligatoire) : Nom de domaine (par ex. exemple.com)

delete-sending-domain

Supprime un domaine d'envoi.

Paramètres :

• sending_domain_id (obligatoire) : ID du domaine d'envoi à supprimer

send-sending-domain-setup-instructions

Envoie par e-mail les instructions de configuration DNS d'un domaine d'envoi à une adresse donnée. Utile pour transmettre les enregistrements DNS à un collègue DevOps.

Paramètres :

• sending_domain_id (obligatoire) : ID du domaine d'envoi
• email (obligatoire) : Adresse e-mail à laquelle envoyer les instructions de configuration DNS

list-suppressions

Liste ou recherche les suppressions (rebonds durs, plaintes pour spam, désabonnements, importations manuelles). Renvoie jusqu'à 1000 résultats par appel.

Paramètres :

• email (optionnel) : Filtre d’email. Renvoie uniquement les suppressions correspondant à cette adresse.

delete-suppression

Supprime une suppression par son ID. Mailtrap reprendra la livraison vers cet email, sauf s’il est à nouveau supprimé.

Paramètres :

• suppression_id (obligatoire) : ID de la suppression à supprimer

list-webhooks

Liste tous les webhooks configurés pour le compte. Renvoie les enregistrements complets des webhooks au format JSON.

Paramètres :

• Aucun paramètre requis

get-webhook

Récupère un webhook unique par son ID. Renvoie l’enregistrement complet du webhook au format JSON. Remarque : signing_secret n’est pas renvoyé ici — il est uniquement disponible dans la réponse de create-webhook.

Paramètres :

• webhook_id (obligatoire) : ID du webhook à récupérer

create-webhook

Crée un webhook. La réponse inclut un signing_secret pour vérifier les signatures de charge utile du webhook — ce secret est renvoyé uniquement à la création, conservez-le donc immédiatement. Si vous le perdez, recréez le webhook.

Paramètres :

• url (obligatoire) : URL vers laquelle Mailtrap enverra les événements du webhook
• webhook_type (obligatoire) : "email_sending" ou "audit_log"
• active (optionnel, booléen) : valeur par défaut true
• payload_format (optionnel) : "json" ou "jsonlines". Valeur par défaut "json"
• sending_stream (optionnel, email_sending uniquement) : "transactional" ou "bulk"
• event_types (optionnel, email_sending uniquement) : tableau de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
• domain_id (optionnel, email_sending uniquement) : ID du domaine d’envoi pour limiter ce webhook à ce domaine

update-webhook

Met à jour les champs modifiables d’un webhook. webhook_type, sending_stream et domain_id ne peuvent pas être modifiés après la création — recréez le webhook si vous devez les changer.

Paramètres :

• webhook_id (obligatoire) : ID du webhook à mettre à jour
• url (optionnel) : Nouvelle URL du webhook
• active (optionnel, booléen) : Activer ou désactiver le webhook
• payload_format (optionnel) : "json" ou "jsonlines"
• event_types (optionnel, email_sending uniquement) : tableau de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject

delete-webhook

Supprime définitivement un webhook par son ID. Renvoie l’enregistrement du webhook supprimé.

Paramètres :

• webhook_id (obligatoire) : ID du webhook à supprimer

get-contact

Récupère un contact par son ID ou son email. Renvoie l’enregistrement complet du contact (appartenances aux listes, statut, champs personnalisés).

Paramètres :

• contact_identifier (obligatoire) : ID du contact ou adresse email

create-contact

Crée un nouveau contact.

Paramètres :

• email (obligatoire) : Adresse email
• fields (optionnel) : Valeurs des champs personnalisés indexées par balise de fusion (par ex. first_name). Valeurs de type chaîne, nombre ou booléen
• list_ids (optionnel) : IDs des listes de contacts auxquelles abonner ce contact
• unsubscribed (optionnel, booléen) : Créer le contact avec le statut unsubscribed

update-contact

Met à jour un contact existant identifié par son ID ou son email. list_ids remplace l’ensemble complet des appartenances du contact ; list_ids_included/list_ids_excluded ajoutent/suppriment sans perturber le reste.

Paramètres :

• contact_identifier (obligatoire) : ID du contact ou email
• email (optionnel) : Nouvelle adresse email
• fields (optionnel) : Valeurs des champs personnalisés indexées par balise de fusion
• list_ids (optionnel) : Remplacer l’ensemble des appartenances par cette liste exacte
• list_ids_included (optionnel) : IDs de listes à ajouter (additif)
• list_ids_excluded (optionnel) : IDs de listes à supprimer
• unsubscribed (optionnel, booléen) : Définir sur unsubscribed (vrai) ou subscribed (faux)

delete-contact

Supprime définitivement un contact par son ID ou son email. Renvoie l’enregistrement du contact supprimé lorsque l’API répond avec celui-ci ; sinon renvoie une charge utile de confirmation.

Paramètres :

• contact_identifier (obligatoire) : ID du contact ou email

create-contact-event

Enregistre un événement de contact pour un contact (par ID ou email). Utilisé pour déclencher les automatisations de liste de contacts.

Paramètres :

• contact_identifier (obligatoire) : ID du contact ou email
• name (obligatoire) : Nom de l’événement (correspond aux déclencheurs d’automatisation)
• params (obligatoire) : Objet de paires clé/valeur arbitraires. Les valeurs peuvent être de type chaîne, nombre, booléen ou null

list-contact-lists

Liste toutes les listes de contacts du compte.

Paramètres :

• Aucun paramètre requis

get-contact-list

Récupère une liste de contacts par son ID.

Paramètres :

• list_id (obligatoire) : ID de la liste de contacts à récupérer

create-contact-list

Crée une nouvelle liste de contacts.

Paramètres :

• name (obligatoire) : Nom de la nouvelle liste

update-contact-list

Renomme une liste de contacts existante.

Paramètres :

• list_id (obligatoire) : ID de la liste de contacts
• name (obligatoire) : Nouveau nom de la liste

delete-contact-list

Supprime définitivement une liste de contacts par son ID.

Paramètres :

• list_id (obligatoire) : ID de la liste de contacts à supprimer

list-contact-fields

Liste toutes les définitions de champs de contact du compte.

Paramètres :

• Aucun paramètre requis

get-contact-field

Récupère une définition de champ de contact par son ID.

Paramètres :

• field_id (obligatoire) : ID du champ de contact

create-contact-field

Crée une nouvelle définition de champ de contact. merge_tag doit être unique au sein du compte et est utilisé comme nom d’espace réservé dans les variables de modèle.

Paramètres :

• name (obligatoire) : Nom d’affichage (par ex. "Prénom")
• merge_tag (obligatoire) : Nom d’espace réservé unique (par ex. first_name)
• data_type (obligatoire) : L’un de text, number, boolean, date

update-contact-field

Met à jour une définition de champ de contact. Toute combinaison de name, merge_tag et data_type peut être modifiée.

Paramètres :

• field_id (obligatoire) : ID du champ de contact
• name (optionnel) : Nouveau nom d’affichage
• merge_tag (optionnel) : Nouvelle balise de fusion (doit rester unique)
• data_type (optionnel) : L’un de text, number, boolean, date

delete-contact-field

Supprime définitivement une définition de champ de contact par son ID.

Paramètres :

• field_id (obligatoire) : ID du champ de contact à supprimer

create-contact-import

Importe des contacts en masse. Renvoie un enregistrement de tâche d’importation ; interrogez son statut avec get-contact-import.

Paramètres :

• contacts (obligatoire) : Tableau d’entrées de contact. Chaque entrée nécessite :
  • email (obligatoire) : Adresse email du contact
  • fields (optionnel) : Valeurs des champs personnalisés indexées par balise de fusion (valeurs de type chaîne ou nombre)
  • list_ids_included (optionnel) : IDs de listes auxquelles ajouter le contact
  • list_ids_excluded (optionnel) : IDs de listes desquelles supprimer le contact

get-contact-import

Récupère le statut d’une tâche d’importation de contacts (créée/démarrée/terminée/échouée) avec les compteurs créés/mis à jour/hors limite.

Paramètres :

• import_id (obligatoire) : ID de la tâche d’importation de contacts

create-contact-export

Exporte les contacts correspondant à un ensemble de filtres combinés par ET. Renvoie un enregistrement de tâche d’exportation ; interrogez le statut avec get-contact-export pour récupérer l’URL de téléchargement une fois que status est finished.

Paramètres :

• filters (obligatoire) : Tableau d’objets de filtre. Chacun a :
  • name (obligatoire) : Champ sur lequel filtrer (list_id, subscription_status, email, etc.)
  • operator (obligatoire) : L’un de equal, not_equal, contains, not_contains, is_empty, is_not_empty
  • value (obligatoire) : Valeur de comparaison (chaîne, nombre, booléen ou tableau)

get-contact-export

Récupère le statut d’une tâche d’exportation de contacts. Une fois que status est finished, le champ url contient le lien de téléchargement CSV.

Paramètres :

• export_id (obligatoire) : ID de la tâche d’exportation de contacts

list-accounts

Liste les comptes Mailtrap auxquels le jeton API actuel peut accéder, avec les niveaux d’accès de chaque compte.

Paramètres :

• Aucun paramètre requis

get-billing-usage

Récupère l’utilisation du cycle de facturation actuel pour le compte : plans d’envoi et de test, limites et compteurs actuels.

Paramètres :

• Aucun paramètre requis

list-account-accesses

Liste les accès au compte (utilisateurs, invitations, jetons API) pour le compte. Des filtres optionnels restreignent le résultat à des ressources spécifiques. Nécessite les autorisations d’administrateur/propriétaire du compte.

Paramètres :

• domain_uuids (optionnel) : Filtrer par UUIDs de domaine d’envoi (tableau de chaînes)
• inbox_ids (optionnel) : Filtrer par IDs de boîte de réception sandbox (tableau de chaînes)
• project_ids (optionnel) : Filtrer par IDs de projet sandbox (tableau de chaînes)

remove-account-access

Supprime un accès au compte par son ID. Pour les spécificateurs User, cela révoque leurs autorisations ; pour les spécificateurs Invite ou ApiToken, cela supprime entièrement le spécificateur. Nécessite administrateur/propriétaire.

Paramètres :

• account_access_id (obligatoire) : ID de l’enregistrement d’accès à supprimer

get-permission-resources

Récupère toutes les ressources (boîtes de réception, projets, domaines, facturation, compte) pour lesquelles le jeton API a un accès administrateur, imbriquées par hiérarchie.

Paramètres :

• Aucun paramètre requis

bulk-update-permissions

Crée, met à jour ou détruit en masse des autorisations pour un seul accès au compte. Les paires (resource_type, resource_id) existantes sont mises à jour ; de nouvelles sont créées. Définissez destroy: true sur une entrée pour la supprimer.

Paramètres :

• account_access_id (obligatoire) : ID de l’accès au compte cible
• permissions (obligatoire) : Tableau d’entrées d’autorisation. Chacune a :
  • resource_id (obligatoire) : ID de ressource (nombre ou chaîne)
  • resource_type (obligatoire) : L’un de account, project, inbox, domain, billing
  • access_level (optionnel) : admin/100 ou viewer/10
  • destroy (optionnel, booléen) : Lorsque vrai, supprime cette autorisation au lieu de la créer/la mettre à jour

list-api-tokens

Liste tous les jetons API du compte.

Paramètres :

• Aucun paramètre requis

create-api-token

Crée un nouveau jeton API. La réponse inclut la valeur secrète token — c’est la seule fois que le jeton complet est renvoyé, conservez-le donc immédiatement. Si vous le perdez, recréez le jeton.

Paramètres :

• name (obligatoire) : Nom d’affichage du jeton
• resources (optionnel) : Tableau d’autorisations de ressources pour limiter la portée du jeton. Chaque entrée a :
  • resource_type (obligatoire) : L’un de account, project, inbox, domain, billing
  • resource_id (obligatoire) : ID de la ressource
  • access_level (obligatoire) : 100 (administrateur) ou 10 (observateur)

get-api-token

Récupère un jeton API par son ID. Renvoie uniquement les métadonnées — la valeur secrète du jeton n’est pas renvoyée ici (uniquement depuis create-api-token / reset-api-token).

Paramètres :

• api_token_id (obligatoire) : ID du jeton API

reset-api-token

Réinitialise (rotation) un jeton API par son ID. La réponse inclut la nouvelle valeur secrète token — renvoyée uniquement lors de cet appel, conservez-la donc immédiatement. Le jeton précédent est invalidé.

Paramètres :

• api_token_id (obligatoire) : ID du jeton API à réinitialiser

delete-api-token

Supprime définitivement un jeton API par son ID. Le jeton ne peut plus s’authentifier après la suppression.

Paramètres :

• api_token_id (obligatoire) : ID du jeton API à supprimer

list-sub-accounts

Liste les sous-comptes de l’organisation. Nécessite la variable d’environnement MAILTRAP_ORGANIZATION_ID et les autorisations de gestion des sous-comptes.

Paramètres :

• Aucun paramètre requis

create-sub-account

Créez un nouveau sous-compte sous l'organisation. Nécessite la variable d'environnement MAILTRAP_ORGANIZATION_ID et les autorisations de gestion des sous-comptes.

Paramètres :

• name (obligatoire) : Nom d'affichage du nouveau sous-compte

Développement

1. Clonez le dépôt :

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. Installez les dépendances :

npm install

Configuration avec Claude Desktop ou Cursor

[!TIP] Consultez l'emplacement du fichier de configuration dans la section Configuration.

Ajoutez la configuration suivante :

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

Si vous utilisez asdf pour gérer Node.js, vous devez utiliser le chemin absolu vers l'exécutable :

(exemple pour 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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Consultez l'emplacement du fichier de configuration dans la section Configuration.

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

Tests

Exécution des outils sur un vrai compte Mailtrap

Il existe deux façons d'exécuter un outil de bout en bout sur un vrai compte Mailtrap : l'interface utilisateur navigateur MCP Inspector pour une exploration interactive, ou son mode CLI pour des appels ponctuels depuis le terminal.

Les deux nécessitent que le bundle soit d'abord construit :

npm run build

et que MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID soient exportés dans votre shell (le script mcp:cli les transmet au serveur lancé).

Interface utilisateur navigateur

npm run dev

L'Inspector affiche une URL comme http://localhost:6274. Ouvrez-la, basculez vers l'onglet Outils, choisissez un outil (par ex. get-template), remplissez les paramètres en JSON et cliquez sur Exécuter. La réponse de Mailtrap apparaît dans le panneau ci-dessous.

CLI

Pour des appels ponctuels sans l'interface utilisateur, utilisez npm run mcp:cli. Passez les options CLI de l'Inspector après -- pour que npm les transmette telles quelles :

# 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 protected]

Exécution du serveur MCPB

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

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Pour le développement avec MCP Inspector :

npm run dev:mcpb

Gestion des erreurs

Ce serveur utilise une gestion structurée des erreurs alignée sur les conventions MCP :

• VALIDATION_ERROR : Échecs de validation des entrées
• CONFIGURATION_ERROR : Configuration manquante ou invalide
• EXECUTION_ERROR : Erreurs d'exécution
• TIMEOUT : Délai d'expiration de l'opération (30 secondes par défaut)

Les erreurs incluent des messages exploitables et sont journalisées sous forme structurée.

Sécurité

• Entrées validées via des schémas Zod
• Variables d'environnement gérées de manière sécurisée
• Protection contre les délais d'expiration sur les opérations (30 secondes)
• Détails sensibles expurgés dans les sorties d'erreur

Journalisation

Logs JSON structurés avec les niveaux : INFO, WARN, ERROR, DEBUG.

Activez la journalisation de débogage en définissant DEBUG=true.

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

Important : Le serveur écrit les logs sur stderr afin que stdout reste réservé aux trames JSON-RPC. Cela empêche les hôtes de rencontrer des erreurs d'analyse JSON dues à des logs entrelacés.

Exemple d'analyse de logs avec 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")'

Dépannage

Problèmes courants :

1. Jeton API manquant : assurez-vous que MAILTRAP_API_TOKEN est défini
2. Le bac à sable ne fonctionne pas : fournissez test_inbox_id dans l'appel de l'outil ou définissez la variable d'environnement MAILTRAP_TEST_INBOX_ID
3. Erreurs de délai d'expiration : vérifiez la connectivité réseau et le statut de l'API Mailtrap
4. Erreurs de validation : assurez-vous que tous les champs obligatoires sont fournis

Contribution

Les rapports de bugs et les pull requests sont les bienvenus sur GitHub. Ce projet se veut un espace sûr et accueillant pour la collaboration, et les contributeurs sont tenus de respecter le code de conduite.

Licence

Le package est disponible en open source selon les termes de la Licence MIT.

Code de conduite

Toute personne interagissant dans les bases de code, les trackers de problèmes, les salons de discussion et les listes de diffusion du projet Mailtrap est tenue de suivre le code de conduite.