Mailtrap

officiel

S'intègre avec l'API Email de Mailtrap.

GitHub
63

Que pouvez-vous faire avec Mailtrap MCP ?

  • Envoyer des e-mails transactionnels — Demander l'envoi d'un e-mail via send-email avec du contenu en ligne ou un modèle, incluant CC/BCC et des variables personnalisées.
  • Gérer les modèles d'e-mails — Utiliser list-templates, create-template, update-template ou delete-template pour maintenir des conceptions d'e-mails réutilisables.
  • Inspecter les journaux de livraison — Interroger list-email-logs avec des filtres comme le destinataire, le statut ou la date, puis explorer les détails avec get-email-log-message.
  • Tester les e-mails en bac à sable — Envoyer vers une boîte de réception de test via send-sandbox-email, puis consulter les messages avec get-sandbox-messages et show-sandbox-email-message.
  • Analyser les performances d'envoi — Obtenir les taux de livraison, de rebond et d'engagement via get-sending-stats, éventuellement ventilés par domaine ou catégorie.
  • Configurer l'infrastructure d'envoi — Gérer list-sending-domains, créer ou supprimer des domaines, et récupérer les instructions de configuration DNS.

Documentation

TypeScript test NPM

Serveur MCP Mailtrap

Un serveur MCP qui fournit des outils pour l'envoi et les tests en sandbox 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, statistiques, journaux d'e-mails, listage/affichage sandbox et domaines d'envoi. Optionnel uniquement pour les outils d'envoi (send-email, send-sandbox-email et les outils batch-send-*).

Optionnel (peut être passé en paramètre d'outil à la place) :

  • DEFAULT_FROM_EMAIL - E-mail d'expéditeur par défaut lorsque from n'est pas fourni à send-email, send-sandbox-email ou aux outils batch-send-* (où il remplit base.from). Permet de changer d'expéditeur par appel via le paramètre from.
  • MAILTRAP_SANDBOX_ID - ID de sandbox par défaut pour les outils sandbox lorsque sandbox_id n'est pas fourni. Permet de basculer entre sandboxes par appel via le paramètre sandbox_id.
  • MAILTRAP_TEST_INBOX_ID - ID de boîte de réception de test par défaut pour les outils sandbox lorsque test_inbox_id n'est pas fourni. Permet de basculer entre boîtes de réception par appel via le paramètre test_inbox_id. Alias hérité de MAILTRAP_SANDBOX_ID, toujours respecté comme solution de repli.
  • MAILTRAP_ORGANIZATION_ID - Requis pour les outils d'organisation (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Jeton API à portée organisationnelle. Requis pour les outils d'organisation (distinct de MAILTRAP_API_TOKEN).

Installation rapide

Install in Cursor

Install with Node in VS Code

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 des clients et fournit un processus d'installation interactif. C'est le moyen le plus simple de commencer à utiliser les serveurs MCP en local.

Configuration

Claude Desktop

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

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": "your_sender@example.com",
        "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": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Emplacement du fichier de configuration Claude Desktop

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

Windows : %APPDATA%\Claude\claude_desktop_config.json

Emplacement du fichier de configuration 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": "your_sender@example.com",
          "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".

Bundle MCP (MCPB)

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

Ceci 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 e-mails et de gérer les modèles, par exemple :

Opérations d'envoi d'e-mails :

  • "Envoyez un e-mail à john.doe@example.com avec l'objet 'Réunion demain' et un rappel amical de notre prochaine réunion."
  • "Envoyez un e-mail à sarah@example.com à propos de la mise à jour du projet, et en copie à l'équipe à team@example.com"
  • "Envoyez le modèle de bienvenue (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) à new@example.com avec les variables { name: 'Alex' }"
  • "Envoyez un e-mail sandbox à test@example.com avec l'objet 'Modèle de test' pour prévisualiser notre e-mail de bienvenue"

Journaux d'e-mails (débogage de livraison) :

  • "Listez mes journaux d'e-mails envoyés récemment"
  • "Affichez les journaux d'e-mails envoyés à user@example.com"
  • "Obtenez le message de journal d'e-mail pour l'ID abc-123-uuid afin de vérifier le statut de livraison"

Statistiques d'envoi :

  • "Obtenez les statistiques d'envoi pour janvier 2025"
  • "Affichez les taux de livraison par domaine pour le mois dernier"
  • "Quelles sont mes statistiques d'e-mails par catégorie du 01/01/2025 au 31/01/2025 ?"

Opérations sandbox :

  • "Récupérez tous les messages de ma boîte de réception sandbox"
  • "Affichez la première page des messages sandbox"
  • "Recherchez les messages contenant 'test' dans ma boîte de réception sandbox"
  • "Affichez les détails du message sandbox avec l'ID 5159037506"

Opérations de modèles :

  • "Listez tous les modèles d'e-mails de mon compte Mailtrap"
  • "Créez un nouveau modèle d'e-mail appelé 'E-mail de bienvenue' avec l'objet 'Bienvenue sur notre plateforme !'"
  • "Mettez à jour le modèle avec l'ID 12345 pour changer l'objet en 'Message de bienvenue mis à jour'"
  • "Supprimez le modèle avec l'ID 67890"

Domaines d'envoi :

  • "Listez mes domaines d'envoi"
  • "Obtenez le domaine d'envoi avec l'ID 3938"
  • "Créez un domaine d'envoi pour example.com"
  • "Supprimez le domaine d'envoi 3938"
  • "Obtenez le domaine d'envoi 3938 avec les instructions de configuration DNS"

Outils disponibles

send-email

Envoie un e-mail 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 { email, name? } (une simple chaîne d'e-mail est également acceptée à l'exécution). Si non fourni, DEFAULT_FROM_EMAIL est utilisé.
  • to (optionnel) : Tableau de destinataires sous forme d'objets { email, name? } (les chaînes d'e-mail simples, ou une seule adresse non-tableau, sont également acceptées à l'exécution). Optionnel si cc ou bcc est fourni ; au moins un de to / cc / bcc doit contenir un destinataire.
  • cc (optionnel) : Tableau de destinataires CC sous forme d'objets { email, name? } (les chaînes d'e-mail simples sont également acceptées à l'exécution).
  • bcc (optionnel) : Tableau de destinataires CCI sous forme d'objets { email, name? } (les chaînes d'e-mail simples sont également acceptées à l'exécution).
  • subject (conditionnel) : Ligne d'objet de l'e-mail. Requise pour les envois en ligne ; doit être omise lorsque template_uuid est défini.
  • text (conditionnel) : Corps de l'e-mail en texte. Requis (en plus 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. Requise (en plus ou à la place de text) pour les envois en ligne ; doit être omise lorsque template_uuid est défini.
  • category (optionnel) : Catégorie d'e-mail pour le suivi et les analyses. Doit être omise lorsque template_uuid est défini.
  • template_uuid (optionnel) : 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 (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'e-mails transactionnels en un seul appel API Mailtrap (flux d'envoi par défaut). Les champs partagés vont dans base ; les remplacements par destinataire vont dans requests[]. Chaque demande 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 demande.

Paramètres :

  • base (optionnel) : Objet avec des champs partagés sur le lot.
    • from (optionnel) : Expéditeur sous forme de { email, name? } (une simple chaîne d'e-mail est également acceptée à l'exécution). Retombe à DEFAULT_FROM_EMAIL.
    • reply_to (optionnel) : Adresse de réponse.
    • subject / text / html / category (optionnels, mode en ligne) : Contenu par défaut pour chaque demande.
    • template_uuid / template_variables (optionnels, mode modèle) : Modèle + variables par défaut. Mutuellement exclusifs avec les champs en ligne.
    • custom_variables (optionnel) : Variables personnalisées par défaut (à valeur 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) : Tableau de destinataires sous forme d'objets { email, name? } (les chaînes d'e-mail simples, ou une seule adresse non-tableau, sont également acceptées à l'exécution). Optionnel si cc ou bcc est fourni ; au moins un de to / cc / bcc doit contenir un destinataire.
    • cc, bcc, reply_to (optionnels).
    • Remplacements en ligne (subject/text/html/category) ou modèle (template_uuid/template_variables) ; tout champ omis retombe sur la valeur base correspondante.
    • custom_variables, headers (optionnels).

batch-send-bulk-email

Envoie un lot d'e-mails 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 l'endpoint en masse au lieu de celui transactionnel. Voir les paramètres ci-dessus.

list-email-logs

Liste les journaux d'e-mails envoyés (historique de livraison) avec pagination et filtres optionnels. Utilisez-le pour déboguer les problèmes de livraison depuis l'IDE.

Paramètres :

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

Tous les paramètres sont optionnels.

get-email-log-message

Obtient un seul message de journal d'e-mail par ID (UUID) : un résumé lisible (de, à, objet, heure d'envoi, statut, catégorie, flux, engagement, contexte de livraison), 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 du journal des e-mails (à partir de la réponse d'envoi ou de list-email-logs). Utilisez list-email-logs pour trouver les ID de messages.
  • include_content (optionnel) : Lorsque true, récupère l'EML brut (si raw_message_url est disponible) et ajoute les sections de corps HTML analysé et texte brut, similaire à show-sandbox-email-message.

get-sending-stats

Obtenez les statistiques d'envoi d'e-mails (taux de livraison, de rebond, d'ouverture, de clic, de spam) pour une plage de dates. Optionnellement, ventilez par domaine, catégorie, fournisseur de services e-mail ou date. Vérifiez les taux de livraison sans quitter l'éditeur.

Paramètres :

  • start_date (requis) : Date de début de la plage de statistiques (AAAA-MM-JJ)
  • end_date (requis) : Date de fin de la plage de statistiques (AAAA-MM-JJ)
  • breakdown (optionnel) : Comment ventiler les statistiques : aggregated (par défaut), by_domain, by_category, by_email_service_provider ou by_date
  • sending_domain_ids (optionnel) : Limiter les résultats à ces ID de domaines d'envoi (tableau d'entiers)
  • sending_streams (optionnel) : Limiter à transactional et/ou bulk (tableau de chaînes)
  • categories (optionnel) : Limiter à ces catégories d'e-mails (tableau de chaînes)
  • email_service_providers (optionnel) : 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 (requis) : Nom du modèle
  • subject (requis) : Ligne d'objet de l'e-mail
  • html (ou text est requis) : Contenu HTML du modèle
  • text (ou html est requis) : Version texte brut du modèle
  • category (optionnel) : 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 par ID, y compris l'objet, la catégorie et le corps HTML/texte.

Paramètres :

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

update-template

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

Paramètres :

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

[!NOTE] Au moins un champ modifiable (name, subject, html, text ou category) 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 (requis) : 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. C'est parfait 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 inline ou basé sur un modèle (template_uuid).

Paramètres :

  • test_inbox_id (optionnel) : ID de la boîte de réception de test Mailtrap. Requis sauf si MAILTRAP_TEST_INBOX_ID est défini ; transmettez-le à chaque appel pour cibler une boîte de réception spécifique.
  • from (optionnel) : Expéditeur sous forme de { email, name? } (une chaîne d'e-mail simple est également acceptée à l'exécution). S'il n'est pas fourni, DEFAULT_FROM_EMAIL est utilisé.
  • to (optionnel) : Tableau de destinataires sous forme d'objets { email, name? } (les chaînes d'e-mails simples dans le tableau, ou une chaîne d'e-mails simples séparés par des virgules, sont également acceptées à l'exécution). 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 (CC) sous forme d'objets { email, name? } (les chaînes d'e-mails simples sont également acceptées à l'exécution).
  • bcc (optionnel) : Tableau de destinataires en copie cachée (BCC) sous forme d'objets { email, name? } (les chaînes d'e-mails simples sont également acceptées à l'exécution).
  • subject (conditionnel) : Ligne d'objet de l'e-mail. Requise pour les envois inline ; doit être omise lorsque template_uuid est défini.
  • text (conditionnel) : Texte du corps de l'e-mail. Requis (en plus ou à la place de html) pour les envois inline ; doit être omis lorsque template_uuid est défini.
  • html (conditionnel) : Version HTML du corps de l'e-mail. Requise (en plus ou à la place de text) pour les envois inline ; doit être omise lorsque template_uuid est défini.
  • category (optionnel) : Catégorie d'e-mail pour le suivi. Doit être omise lorsque template_uuid est défini.
  • template_uuid (optionnel) : Utilisez un modèle d'e-mail Mailtrap au lieu du contenu inline. Lorsqu'il est défini, subject / text / html / category doivent être omis.
  • 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-sandbox-email

Envoie un lot d'e-mails à votre boîte de réception de test Mailtrap en un seul appel API, sans les livrer à de vrais destinataires. Même forme base + requests[], même validation et mêmes règles inline-vs-modèle que batch-send-transactional-email — la différence est que cet outil achemine l'appel via le point de terminaison sandbox pour une seule boîte de réception de test.

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox Mailtrap (boîte de réception de test). Requis sauf si MAILTRAP_SANDBOX_ID est défini ; transmettez-le à chaque appel pour cibler un sandbox spécifique.
  • base (optionnel), requests (requis) : Voir batch-send-transactional-email ci-dessus.

[!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 à chaque appel en transmettant test_inbox_id. Les outils qui prennent sandbox_id utilisent MAILTRAP_SANDBOX_ID en premier.

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 (optionnel) : Numéro de page pour la pagination (minimum : 1)
  • last_id (optionnel) : Pagination utilisant l'ID du dernier message. Renvoie les messages après l'ID de message spécifié (minimum : 1)
  • search (optionnel) : Requête de recherche pour filtrer les messages

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

show-sandbox-email-message

Affiche des informations détaillées et le contenu d'un message e-mail 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 (requis) : ID du message e-mail 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 ID, y compris ses boîtes de réception et ses compteurs d'e-mails.

Paramètres :

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

update-sandbox-project

Renomme un projet sandbox existant.

Paramètres :

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

list-sandboxes

Liste tous les sandbox accessibles au jeton API dans 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 (requis) : ID du sandbox concerné

reset-sandbox-credentials

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

Paramètres :

  • sandbox_id (requis) : ID du sandbox concerné

enable-sandbox-email-address

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

Paramètres :

  • sandbox_id (requis) : ID du sandbox concerné

reset-sandbox-email-address

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

Paramètres :

  • sandbox_id (requis) : ID du sandbox concerné

forward-sandbox-message

Transfère un message sandbox vers une adresse e-mail externe. Compte dans votre quota mensuel de transfert.

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : ID du message sandbox à transférer
  • email (requis) : Adresse e-mail vers laquelle transférer le message

update-sandbox-message

Marque un message sandbox comme lu ou non lu.

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : ID du message sandbox à mettre à jour
  • is_read (requis) : true marque comme lu, false marque comme non lu

delete-sandbox-message

Supprime un seul message sandbox.

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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 (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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 (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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 (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : ID du message sandbox

get-sandbox-message-html

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

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : ID du message sandbox

get-sandbox-message-text

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

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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 (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : ID du message sandbox

get-sandbox-message-eml

Récupère le message rendu sous forme de charge utile de fichier EML (adapté pour joindre à un ticket ou importer dans un autre client de messagerie).

Paramètres :

  • sandbox_id (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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 (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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 (optionnel) : ID du sandbox. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (requis) : 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. Repli sur MAILTRAP_SANDBOX_ID.
  • message_id (obligatoire) : ID du message sandbox contenant 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). Incluez é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. 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. example.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 pour 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 définitifs, plaintes pour spam, désabonnements, importations manuelles). Renvoie jusqu'à 1000 résultats par appel.

Paramètres :

  • email (facultatif) : Filtre par e-mail. Renvoie uniquement les suppressions correspondant à cette adresse.

delete-suppression

Supprime une suppression par ID. Mailtrap reprendra la livraison à cet e-mail sauf s'il est de 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 ID. Renvoie l'enregistrement complet du webhook au format JSON. Remarque : signing_secret n'est pas renvoyé ici — il n'est disponible que 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 des charges utiles du webhook — ce secret n'est renvoyé qu'à la création, alors conservez-le maintenant. Si vous le perdez, recréez le webhook.

Paramètres :

  • url (obligatoire) : URL à laquelle Mailtrap enverra les événements du webhook
  • webhook_type (obligatoire) : "email_sending", "audit_log" ou "inbound_receiving"
  • active (facultatif, booléen) : par défaut true
  • payload_format (facultatif) : "json" ou "jsonlines". Par défaut "json"
  • sending_stream (facultatif, email_sending uniquement) : "transactional" ou "bulk"
  • event_types (facultatif, email_sending uniquement) : tableau de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (facultatif, email_sending uniquement) : ID du domaine d'envoi pour limiter ce webhook
  • inbound_inbox_id (facultatif, inbound_receiving uniquement) : ID de la boîte de réception entrante à laquelle le webhook est lié ; omettez pour appliquer à toutes les boîtes de réception du compte

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 (facultatif) : Nouvelle URL du webhook
  • active (facultatif, booléen) : Activer ou désactiver le webhook
  • payload_format (facultatif) : "json" ou "jsonlines"
  • event_types (facultatif, email_sending uniquement) : tableau de delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (facultatif, inbound_receiving uniquement) : ID de la boîte de réception entrante à laquelle le webhook est lié

delete-webhook

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

Paramètres :

  • webhook_id (obligatoire) : ID du webhook à supprimer

get-contact

Récupère un contact par ID ou e-mail. Renvoie l'enregistrement complet du contact (appartenances aux listes, statut, champs personnalisés).

Paramètres :

  • contact_identifier (obligatoire) : ID du contact ou adresse e-mail

create-contact

Crée un nouveau contact.

Paramètres :

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

update-contact

Met à jour un contact existant identifié par ID ou e-mail. list_ids remplace l'ensemble complet des adhésions du contact ; list_ids_included/list_ids_excluded ajoutent/retirent sans perturber le reste.

Paramètres :

  • contact_identifier (obligatoire) : ID du contact ou e-mail
  • email (facultatif) : Nouvelle adresse e-mail
  • fields (facultatif) : Valeurs des champs personnalisés clés par balise de fusion
  • list_ids (facultatif) : Remplacer l'ensemble des adhésions par cette liste exacte
  • list_ids_included (facultatif) : ID des listes à ajouter (additif)
  • list_ids_excluded (facultatif) : ID des listes à retirer
  • unsubscribed (facultatif, booléen) : Définir sur unsubscribed (vrai) ou subscribed (faux)

delete-contact

Supprime définitivement un contact par ID ou e-mail. Renvoie l'enregistrement du contact supprimé lorsque l'API en renvoie un ; sinon renvoie une charge utile de confirmation.

Paramètres :

  • contact_identifier (obligatoire) : ID du contact ou e-mail

create-contact-event

Enregistre un événement de contact pour un contact (par ID ou e-mail). Utilisé pour déclencher des automatisations de listes de contacts.

Paramètres :

  • contact_identifier (obligatoire) : ID du contact ou e-mail
  • 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 :

  • search (facultatif) : Filtrer les listes de contacts par nom (correspondance insensible à la casse), par ex. news

get-contact-list

Récupère une liste de contacts par 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 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 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 dans le 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) : 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 (facultatif) : Nouveau nom d'affichage
  • merge_tag (facultatif) : Nouvelle balise de fusion (doit rester unique)
  • data_type (facultatif) : Un de text, number, boolean, date

delete-contact-field

Supprime définitivement une définition de champ de contact par 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 e-mail du contact
    • fields (facultatif) : Valeurs des champs personnalisés clés par balise de fusion (valeurs de type chaîne ou nombre)
    • list_ids_included (facultatif) : ID des listes auxquelles ajouter le contact
    • list_ids_excluded (facultatif) : ID des listes desquelles retirer 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/dépassement de 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) : 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 du 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 facultatifs réduisent le résultat à des ressources spécifiques. Nécessite des permissions d'administrateur/propriétaire du compte.

Paramètres :

  • domain_uuids (facultatif) : Filtrer par UUID de domaines d'envoi (tableau de chaînes)
  • inbox_ids (facultatif) : Filtrer par ID de boîtes de réception sandbox (tableau de chaînes)
  • project_ids (facultatif) : Filtrer par ID de projets sandbox (tableau de chaînes)

remove-account-access

Supprime un accès au compte par ID. Pour les spécificateurs User, cela révoque leurs permissions ; pour les spécificateurs Invite ou ApiToken, cela supprime entièrement le spécificateur. Nécessite admin/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) auxquelles 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 les permissions 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 d'accès au compte cible
  • permissions (obligatoire) : Tableau d'entrées de permissions. Chacune comporte :
    • resource_id (obligatoire) : ID de la ressource (nombre ou chaîne)
    • resource_type (obligatoire) : Un parmi account, project, inbox, domain, billing
    • access_level (facultatif) : admin/100 ou viewer/10
    • destroy (facultatif, booléen) : Lorsqu'il est vrai, supprime cette permission 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é, alors stockez-le immédiatement. Si vous le perdez, recréez le jeton.

Paramètres :

  • name (obligatoire) : Nom d'affichage du jeton
  • resources (facultatif) : Tableau de permissions de ressources pour limiter la portée du jeton. Chaque entrée comporte :
    • resource_type (obligatoire) : Un parmi account, project, inbox, domain, billing
    • resource_id (obligatoire) : ID de la ressource
    • access_level (obligatoire) : 100 (administrateur) ou 10 (lecteur)

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 (fait pivoter) un jeton API par son ID. La réponse inclut la nouvelle valeur secrète token — renvoyée uniquement lors de cet appel, alors stockez-la immédiatement. L'ancien jeton 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 authentifier les requêtes après sa 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 permissions de gestion des sous-comptes.

Paramètres :

  • Aucun paramètre requis

create-sub-account

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

Paramètres :

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

list-inbound-folders

Liste tous les dossiers entrants du compte. Renvoie un résumé formaté.

Paramètres :

  • Aucun paramètre requis

get-inbound-folder

Récupère un dossier entrant par son ID. Renvoie l'enregistrement complet du dossier au format JSON.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant

create-inbound-folder

Crée un nouveau dossier entrant.

Paramètres :

  • name (obligatoire) : Le nom du dossier

update-inbound-folder

Renomme un dossier entrant.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant
  • name (obligatoire) : Le nouveau nom du dossier

delete-inbound-folder

Supprime définitivement un dossier entrant ainsi que toutes ses boîtes de réception.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant

list-inbound-inboxes

Liste toutes les boîtes de réception d'un dossier entrant. Renvoie un résumé formaté.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant

get-inbound-inbox

Récupère une boîte de réception entrante par son ID. Renvoie l'enregistrement complet de la boîte au format JSON.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant
  • inbox_id (obligatoire) : ID de la boîte de réception

create-inbound-inbox

Crée une nouvelle boîte de réception entrante dans un dossier.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant
  • name (obligatoire) : Le nom de la boîte de réception
  • domain_id (facultatif) : À rattacher à un domaine d'envoi personnalisé (boîte de réception fourre-tout). À omettre pour une boîte hébergée par Mailtrap

update-inbound-inbox

Renomme une boîte de réception entrante.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant
  • inbox_id (obligatoire) : ID de la boîte de réception
  • name (obligatoire) : Le nouveau nom de la boîte de réception

delete-inbound-inbox

Supprime définitivement une boîte de réception entrante.

Paramètres :

  • folder_id (obligatoire) : ID du dossier entrant
  • inbox_id (obligatoire) : ID de la boîte de réception

list-inbound-messages

Liste les messages reçus dans une boîte de réception entrante (pagination par curseur). Renvoie un résumé formaté avec une indication de page suivante lorsque d'autres résultats existent.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • last_id (facultatif) : Curseur de pagination provenant du last_id d'une réponse précédente

get-inbound-message

Récupère un message entrant avec son corps complet et les URL de téléchargement des pièces jointes. Renvoie l'enregistrement complet du message au format JSON.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • message_id (obligatoire) : ID du message

delete-inbound-message

Supprime définitivement un message entrant.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • message_id (obligatoire) : ID du message

reply-to-inbound-message

Répond à un message entrant (envoi à l'expéditeur d'origine). Envoie un véritable e-mail. Les adresses acceptent une simple chaîne e-mail ou { email, name? }.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • message_id (obligatoire) : ID du message auquel répondre
  • text / html (au moins un recommandé) : Corps de la réponse
  • from (facultatif) : Expéditeur. Rejeté pour les boîtes hébergées par Mailtrap ; requis pour les boîtes avec domaine personnalisé
  • cc / bcc / reply_to (facultatif) : Adresses supplémentaires
  • category (facultatif) : Catégorie de message
  • attachments (facultatif) : Tableau de { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (facultatif) : Objets de valeurs chaînes

reply-all-to-inbound-message

Répond à un message entrant et met en copie les autres destinataires du message d'origine. Envoie un véritable e-mail. Mêmes paramètres que reply-to-inbound-message.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • message_id (obligatoire) : ID du message auquel répondre
  • Plus les mêmes champs d'envoi facultatifs que reply-to-inbound-message

forward-inbound-message

Transfère un message entrant à de nouveaux destinataires. Envoie un véritable e-mail.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • message_id (obligatoire) : ID du message à transférer
  • to (obligatoire) : Au moins un destinataire (simple chaîne e-mail ou { email, name? }, ou un tableau)
  • Plus les mêmes champs d'envoi facultatifs que reply-to-inbound-message

list-inbound-threads

Liste les fils de conversation d'une boîte de réception entrante (pagination par curseur). Renvoie un résumé formaté avec une indication de page suivante lorsque d'autres résultats existent.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • last_id (facultatif) : Curseur de pagination provenant du last_id d'une réponse précédente

get-inbound-thread

Récupère un fil entrant avec ses messages intégrés (du plus ancien au plus récent). Renvoie l'enregistrement complet du fil au format JSON.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • thread_id (obligatoire) : ID du fil

delete-inbound-thread

Supprime définitivement un fil entrant.

Paramètres :

  • inbox_id (obligatoire) : ID de la boîte de réception
  • thread_id (obligatoire) : ID du fil

Développement

  1. Clonez le dépôt :
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Installez les dépendances :
npm install

Configuration avec Claude Desktop ou Cursor

[!TIP] Voir l'emplacement du fichier de configuration dans la section Setup.

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": "your_sender@example.com",
        "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": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Voir l'emplacement du fichier de configuration dans la section Setup.

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

Tests

Exécuter les outils avec un vrai compte Mailtrap

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

Les deux nécessitent d'abord la construction du bundle :

npm run build

et l'export de MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID dans votre shell (le script mcp:cli transmet les deux au serveur lancé).

Interface navigateur

npm run dev

L'Inspector affiche une URL telle que http://localhost:6274. Ouvrez-la, passez à l'onglet Tools, choisissez un outil (par ex. get-template), remplissez les paramètres au format JSON, puis cliquez sur Run. La réponse de Mailtrap apparaît dans le panneau ci-dessous.

CLI

Pour des appels ponctuels sans l'interface, utilisez npm run mcp:cli. Passez les options CLI de l'Inspector après -- afin 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=devops@example.com

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 l'MCP Inspector :

npm run dev:mcpb

Gestion des erreurs

Ce serveur utilise une gestion structurée des erreurs conforme aux conventions MCP :

  • VALIDATION_ERROR : Échecs de validation des entrées
  • CONFIGURATION_ERROR : Configuration manquante ou invalide
  • EXECUTION_ERROR : Erreurs d'exécution
  • TIMEOUT : Dépassement du délai d'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épassements de délai sur les opérations (30 secondes)
  • Détails sensibles nettoyés dans la sortie des erreurs

Journalisation

Journaux 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 journaux sur stderr afin que stdout reste réservé aux trames JSON-RPC. Cela évite aux hôtes de rencontrer des erreurs d'analyse JSON dues à des journaux entrelacés.

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

Résolution des problèmes

Problèmes courants :

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

Contribution

Les rapports de bogues et les demandes de fusion 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 avec les bases de code, les suiveurs de tickets, les salons de discussion et les listes de diffusion du projet Mailtrap est tenue de respecter le code de conduite.