Mailtrap

officiel

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

Que pouvez-vous faire avec Mailtrap MCP ?

Envoyer un e-mail transactionnel — Demandez à l’assistant d’envoyer un e-mail avec un objet et un corps en texte ou en HTML, en utilisant éventuellement un modèle et des variables.
Tester dans Email Sandbox — Envoyez des messages dans un environnement de test et examinez leur contenu, leurs en-têtes et leurs pièces jointes sans qu’ils parviennent à de vrais destinataires.
Déboguer la livraison avec les journaux — Répertoriez et filtrez les journaux des e-mails envoyés, puis ouvrez un message spécifique pour consulter l’historique de ses événements et son statut de livraison.
Analyser les statistiques d’envoi — Obtenez les taux de livraison, de rebond, d’ouverture, de clic et de signalement comme spam pour une période donnée, ventilés par domaine, catégorie ou date.
Gérer les modèles — Créez, répertoriez, mettez à jour et supprimez les modèles d’e-mail stockés dans votre compte Mailtrap.
Gérer les domaines et les suppressions — Répertoriez les domaines, obtenez les instructions de configuration DNS et consultez ou supprimez les adresses supprimées.

Documentation

Serveur MCP officiel de Mailtrap

Le serveur MCP officiel de Mailtrap, la plateforme de distribution d’e-mails. Il connecte votre compte Mailtrap à Claude, Cursor, VS Code et à d’autres assistants IA compatibles avec MCP.

Envoyez des e-mails transactionnels et en masse, testez des messages en toute sécurité dans Email Sandbox, gérez les modèles, les contacts, les domaines et les webhooks, consultez les journaux d’e-mails et les statistiques de distribution, résolvez les problèmes de délivrabilité et gérez les ressources du compte, le tout à l’aide de prompts en langage naturel.

Fonctionnalités

API e-mail et SMTP — Envoyez des e-mails transactionnels et en masse, y compris des messages par lots et basés sur des modèles.
Tests d’e-mails — Testez des messages dans Email Sandbox et examinez leur contenu, leurs en-têtes, leurs pièces jointes, leurs scores de spam et leur compatibilité avec les clients HTML.
Suivi de la distribution — Recherchez dans les journaux d’e-mails, consultez l’historique des événements et analysez les taux de distribution, de rebond, d’ouverture, de clic et de spam.
Infrastructure e-mail — Gérez les domaines, la vérification DNS, les webhooks et les suppressions.
Contacts — Gérez les contacts, les listes, les champs personnalisés et les événements, ainsi que les importations et les exportations.
Gestion du compte — Consultez l’utilisation de la facturation et gérez les accès, les autorisations, les jetons API et les sous-comptes.

Clients MCP pris en charge

Fonctionne avec Claude Desktop, Claude Code, Cursor, VS Code et tout autre client compatible avec MCP. Les instructions de configuration de chacun sont ci-dessous.

Prérequis

Avant d’utiliser ce serveur MCP, vous devez :

Créer un compte Mailtrap
Vérifier votre domaine
Obtenir votre jeton API dans les paramètres de l’API Mailtrap
Obtenir votre ID de compte dans la gestion des comptes Mailtrap
Installer Node.js 22 ou une version ultérieure, sauf si vous exécutez l’image Docker

Variables d’environnement requises :

MAILTRAP_API_TOKEN - Requis pour toutes les fonctionnalités
MAILTRAP_ACCOUNT_ID - Requis pour les modèles, get-sending-stats, les journaux d’e-mails, la liste et l’affichage des sandboxes, les domaines et les suppressions. Facultatif uniquement pour les outils d’envoi (send-email, send-sandbox-email et les outils batch-send-*), les outils de campagnes e-mail, get-marketing-stats, les outils d’informations sur l’entreprise, les outils de désactivation du suivi et list-accounts.

Facultatives (peuvent être transmises comme paramètres d’outil à la place) :

DEFAULT_FROM_EMAIL - Adresse 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ù elle renseigne base.from). Permet de changer d’expéditeur à chaque appel à l’aide du paramètre from.
MAILTRAP_SANDBOX_ID - ID de sandbox par défaut lorsqu’un outil ne reçoit pas sandbox_id (l’ancien test_inbox_id reste accepté pour les outils d’envoi, de liste et d’affichage des messages de sandbox). Permet de changer de sandbox à chaque appel à l’aide des paramètres.
MAILTRAP_TEST_INBOX_ID - Alias obsolète de MAILTRAP_SANDBOX_ID ; toujours lu comme valeur de repli pour les configurations existantes, et génère un avertissement d’obsolescence sur stderr lorsqu’il est utilisé.
MAILTRAP_ORGANIZATION_ID - Requis pour les outils d’organisation (list-sub-accounts, create-sub-account, delete-sub-account).
MAILTRAP_ORGANIZATION_API_TOKEN - Jeton API associé à l’organisation. Requis pour les outils d’organisation (distinct de MAILTRAP_API_TOKEN).

Installation rapide

Docker

Exécutez le serveur via stdio avec l’image du catalogue MCP Docker :

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

Consultez les prérequis pour connaître les variables d’environnement requises et facultatives.

Pour créer une image à partir de ce dépôt : docker build -t mcp/mailtrap .

Smithery CLI

Smithery est un registre et un programme d’installation de serveurs MCP compatible avec les clients IA.

Installez le serveur publié (mailtrap/mailtrap-mcp) dans un client local (remplacez le nom du client selon vos besoins) :

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

Consultez la documentation de Smithery CLI pour découvrir d’autres clients (cursor, windsurf, etc.) et savoir comment publier des mises à jour.

Configuration

Claude Desktop

Utilisez MCPB pour installer le serveur Mailtrap. Vous trouverez ces fichiers dans Releases.
Téléchargez le fichier .MCPB et ouvrez-le. Si vous utilisez Claude Desktop, il s’ouvrira et vous 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": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Si vous utilisez asdf pour gérer Node.js, vous devez utiliser le chemin absolu de 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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

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)

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

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

Bundle MCP (MCPB)

Pour faciliter l’installation sur les hôtes prenant 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. Le script copie dist/, manifest.json, icon.png et la licence dans mcpb-build/, y installe les dépendances de production et empaquette uniquement ce répertoire. N’exécutez pas mcpb pack . depuis la racine du dépôt.

Utilisation

Une fois la configuration terminée, vous pouvez demander à l’agent d’envoyer des e-mails et de gérer des modèles, par exemple :

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

"Envoyer un e-mail à john.doe@example.com avec pour objet 'Meeting Tomorrow' et un rappel amical concernant notre prochaine réunion."
"Envoyer un e-mail à sarah@example.com au sujet de la mise à jour du projet, et mettre l’équipe en copie à team@example.com"
"Envoyer le modèle de bienvenue (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) à new@example.com avec les variables { name: 'Alex' }"
"Envoyer un e-mail de sandbox à test@example.com avec pour objet 'Test Template' afin de prévisualiser l’apparence de notre e-mail de bienvenue"

Journaux d’e-mails (débogage de la distribution) :

"Afficher mes journaux récents d’e-mails envoyés"
"Afficher les journaux d’e-mails envoyés à user@example.com"
"Récupérer le message du journal d’e-mail portant l’ID abc-123-uuid pour vérifier l’état de distribution"

Statistiques :

"Obtenir les statistiques d’envoi pour janvier 2025"
"Afficher les taux de distribution par domaine pour le mois dernier"
"Quelles sont mes statistiques d’e-mails par catégorie du 2025-01-01 au 2025-01-31 ?"
"Quels résultats a obtenu mon marketing par e-mail le mois dernier ? Comparer les campagnes et les automatisations"

Opérations de sandbox :

"Récupérer tous les messages de ma sandbox"
"Afficher la première page des messages de sandbox"
"Rechercher les messages contenant 'test' dans ma sandbox"
"Créer une sandbox appelée 'QA' dans le projet 42 et me fournir ses identifiants SMTP"
"Supprimer tous les messages de la sandbox 1234"
"Afficher les détails du message de sandbox portant l’ID 5159037506"

Opérations sur les modèles :

"Lister tous les modèles d’e-mail de mon compte Mailtrap"
"Créer un modèle d’e-mail appelé 'Welcome Email' avec pour objet 'Welcome to our platform!'"
"Mettre à jour le modèle portant l’ID 12345 pour remplacer l’objet par 'Updated Welcome Message'"
"Supprimer le modèle portant l’ID 67890"

Domaines :

"Lister mes domaines"
"Récupérer le domaine portant l’ID 3938"
"Créer un domaine pour example.com"
"Activer le suivi des clics pour le domaine 3938"
"Supprimer le domaine 3938"
"Récupérer le domaine 3938 avec les instructions de configuration DNS"
"Afficher les informations de l’entreprise pour le domaine 3938"
"Définir les informations de l’entreprise pour le domaine 3938 sur Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
"Remplacer la ville des informations de l’entreprise pour le domaine 3938 par New York"

Suppressions :

"Lister les suppressions pour bounced@example.com"
"Supprimer bounced@example.com du flux transactionnel du domaine 3938"
"Afficher toutes les adresses e-mail supprimées"
"Pourquoi user@example.com ne reçoit-il pas mes e-mails ?"
"Retirer user@example.com de la liste de suppression"

Désactivation du suivi :

"Désactiver le suivi des ouvertures et des clics pour privacy@example.com sur le domaine 3938"
"Lister toutes les personnes qui ont désactivé le suivi"

Contacts et listes :

"Ajouter john.doe@example.com à ma liste de contacts de la newsletter"
"Afficher toutes mes listes de contacts"
"Créer un champ de contact appelé 'signup_source' pour suivre l’origine des contacts"
"Mettre à jour le contact john.doe@example.com pour définir son offre sur 'pro'"
"Importer ces contacts CSV dans ma liste d’intégration"
"Exporter tous les contacts de ma liste de newsletter"
"Enregistrer un événement 'trial_started' pour le contact john.doe@example.com"

Webhooks :

"Lister tous les webhooks configurés sur mon compte"
"Créer un webhook pointant vers https://example.com/hooks/mailtrap pour les événements de rebond et de spam"
"Mettre à jour le webhook 4821 pour qu’il envoie également les événements de distribution"
"Supprimer le webhook 4821"

Compte et facturation :

"Quelle est mon utilisation actuelle de la facturation ce mois-ci ?"
"Combien d’e-mails me reste-t-il dans mon forfait ?"
"Lister toutes les personnes ayant accès à ce compte Mailtrap"
"Afficher les ressources d’autorisation disponibles sur mon compte"

Jetons API :

"Lister tous les jetons API de mon compte"
"Créer un jeton API pour l’environnement de préproduction"
"Réinitialiser le jeton API portant l’ID 1234"
"Supprimer le jeton API inutilisé 1234"

Organisation et sous-comptes :

"Lister tous les sous-comptes de mon organisation"
"Créer un sous-compte pour le projet client 'Acme Corp'"

Outils renommés

Mailtrap appelle désormais les boîtes de réception de test des sandboxes et les domaines d’envoi des domaines ; les outils ont été renommés en conséquence. Les anciens noms n’apparaissent plus dans la liste des outils, mais les appels à ces noms fonctionnent toujours et génèrent un avertissement d’obsolescence sur stderr. Ils seront supprimés dans une prochaine version majeure.

Les clients MCP et les frameworks d’agents font correspondre les listes d’autorisation, de refus et de filtrage aux noms d’outils annoncés. Remplacez donc les entrées propres à chaque outil par les nouveaux noms : une entrée de refus pour delete-sending-domain ne bloque plus delete-domain.

Ancien nom	Nouveau nom
`create-sandbox-inbox`	`create-sandbox`
`get-sandbox-inbox`	`get-sandbox`
`update-sandbox-inbox`	`update-sandbox`
`delete-sandbox-inbox`	`delete-sandbox`
`clean-sandbox-inbox`	`clean-sandbox`
`list-sending-domains`	`list-domains`
`get-sending-domain`	`get-domain`
`create-sending-domain`	`create-domain`
`update-sending-domain`	`update-domain`
`delete-sending-domain`	`delete-domain`
`send-sending-domain-setup-instructions`	`send-domain-setup-instructions`
paramètre `sending_domain_id` des outils de domaine et d’informations sur l’entreprise	`domain_id`
variable d’environnement `MAILTRAP_TEST_INBOX_ID`	`MAILTRAP_SANDBOX_ID`

Les filtres qui reflètent un champ d’API conservent leur nom : sending_domain_id sur list-email-logs et sending_domain_ids sur les outils de statistiques.

Outils disponibles

send-email

Envoie un e-mail transactionnel via Mailtrap. Prend en charge deux modes mutuellement exclusifs : contenu intégré (subject + text/html) ou basé sur un modèle (template_uuid).

Paramètres :

from (facultatif) : Expéditeur au format { email, name? } (une simple adresse e-mail est également acceptée à l’exécution). Si cette valeur n’est pas fournie, DEFAULT_FROM_EMAIL est utilisé.
to (facultatif) : Tableau de destinataires sous forme d’objets { email, name? } (de simples adresses e-mail ou une adresse unique hors tableau sont également acceptées à l’exécution). 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 (CC) sous forme d’objets { email, name? } (de simples adresses e-mail sont également acceptées à l’exécution).
bcc (facultatif) : Tableau de destinataires en copie cachée (BCC) sous forme d’objets { email, name? } (de simples adresses e-mail sont également acceptées à l’exécution).
subject (conditionnel) : Objet de l’e-mail. Obligatoire pour les envois avec contenu intégré ; 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 avec contenu intégré ; 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 avec contenu intégré ; doit être omis lorsque template_uuid est défini.
category (facultatif) : Catégorie d’e-mail pour le suivi et l’analyse. Doit être omise lorsque template_uuid est défini.
template_uuid (facultatif) : Utiliser un modèle d’e-mail Mailtrap à la place du contenu intégré. Lorsque cette valeur est définie, subject / text / html / category doivent être omis (conformément à l’API Mailtrap).
template_variables (facultatif) : Objet contenant les 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 à l’API Mailtrap (flux d’envoi par défaut). Les champs communs sont placés dans base ; les remplacements propres à chaque destinataire sont placés dans requests[]. Chaque requête doit inclure au moins un destinataire via to, cc ou bcc. Même règle d’exclusion mutuelle entre contenu intégré et modèle que pour send-email — vérifiée après fusion de la base avec chaque requête.

Paramètres :

base (facultatif) : Objet contenant les champs communs à l’ensemble du lot.
- from (facultatif) : Expéditeur au format { email, name? } (une simple adresse e-mail est également acceptée à l’exécution). À défaut, utilise DEFAULT_FROM_EMAIL.
- reply_to (facultatif) : Adresse de réponse.
- subject / text / html / category (facultatif, mode contenu intégré) : Contenu par défaut pour chaque requête.
- template_uuid / template_variables (facultatif, mode modèle) : Modèle et variables par défaut. Mutuellement exclusifs avec les champs de contenu intégré.
- custom_variables (facultatif) : Variables personnalisées par défaut (valeurs de type chaîne).
- headers (facultatif) : En-têtes personnalisés par défaut.
requests (obligatoire) : Tableau non vide de messages destinés aux destinataires. Chaque entrée contient :
- to (facultatif) : Tableau de destinataires sous forme d’objets { email, name? } (de simples adresses e-mail ou une adresse unique hors tableau sont également acceptées à l’exécution). Facultatif si cc ou bcc est fourni ; au moins l’un de to / cc / bcc doit contenir un destinataire.
- cc, bcc, reply_to (facultatif).
- Remplacements de contenu intégré (subject/text/html/category) ou de modèle (template_uuid/template_variables) ; tout champ omis reprend la valeur correspondante de base.
- custom_variables, headers (facultatif).

batch-send-bulk-email

Envoie un lot d’e-mails en masse via l’API de flux d’envoi en masse de Mailtrap. Même structure base + requests[], mêmes règles de validation et mêmes règles de contenu intégré ou de modèle que pour batch-send-transactional-email — la seule différence est que cet outil achemine l’appel via le point de terminaison en masse plutôt que transactionnel. Consultez les paramètres ci-dessus.

list-email-logs

Répertorie les journaux des e-mails envoyés (historique de livraison), avec pagination et filtres facultatifs. À utiliser depuis l’IDE pour déboguer les problèmes de livraison.

Paramètres :

search_after (facultatif) : Curseur de pagination issu de next_page_cursor de la réponse précédente
sent_after (facultatif) : Date/heure ISO 8601 ; seuls les journaux des envois postérieurs à cette date sont inclus
sent_before (facultatif) : Date/heure ISO 8601 ; seuls les journaux des envois antérieurs à cette date sont inclus
from_email (facultatif) : Filtrer par adresse e-mail de l’expéditeur ; utiliser avec from_operator (par défaut : ci_equal)
to_email (facultatif) : Filtrer par adresse e-mail du destinataire ; utiliser avec to_operator (par défaut : ci_equal)
status (facultatif) : Filtrer par état de livraison : delivered, not_delivered, enqueued, opted_out ; utiliser avec status_operator (par défaut : equal)
subject (facultatif) : Filtrer par objet de l’e-mail ; utiliser avec subject_operator (par défaut : ci_contain). Utiliser subject_operator : empty/not_empty pour filtrer selon la présence d’un objet.
sending_domain_id (facultatif) : Filtrer par ID de domaine (nombre) ; utiliser avec sending_domain_id_operator (par défaut : equal)
sending_stream (facultatif) : Filtrer par flux : transactional ou bulk ; utiliser avec sending_stream_operator (par défaut : equal)
events (facultatif) : 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 (facultatif) : Filtrer par nombre de clics/ouvertures ; utiliser avec *_operator : equal, greater_than, less_than
client_ip / sending_ip (facultatif) : Filtrer par adresse IP ; utiliser avec *_operator : equal, not_equal, contain, not_contain
email_service_provider_response (facultatif) : Filtrer par texte de réponse du fournisseur ; utiliser avec *_operator (ci_contain, etc.)
email_service_provider (facultatif) : Filtrer par fournisseur (exact) ; utiliser avec *_operator : equal, not_equal
recipient_mx (facultatif) : Filtrer par MX du destinataire ; utiliser avec recipient_mx_operator (ci_contain, etc.)
category (facultatif) : Filtrer par catégorie d’e-mail ; utiliser avec category_operator : equal, not_equal

Tous les paramètres sont facultatifs.

get-email-log-message

Récupère un seul message de journal d’e-mail par ID (UUID) : un résumé lisible (expéditeur, destinataire, objet, heure d’envoi, état, catégorie, flux, engagement, contexte de livraison), puis l’historique détaillé des événements. 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 (obligatoire) : UUID du message de journal d’e-mail (issu de la réponse d’envoi ou de list-email-logs). Utilisez list-email-logs pour trouver les ID des messages.
include_content (facultatif) : Lorsque true, récupère le fichier EML brut (si raw_message_url est disponible) et ajoute des sections contenant le corps analysé en HTML et en texte brut, comme dans show-sandbox-email-message.

get-sending-stats

Récupère les statistiques d’envoi d’e-mails (taux de livraison, de rebond, d’ouverture, de clic et de signalement comme spam) pour une période donnée. Vous pouvez également ventiler les résultats par domaine, catégorie, fournisseur de services de messagerie ou date. Consultez les taux de livraison sans quitter l’éditeur.

Paramètres :

start_date (obligatoire) : Date de début de la période statistique (YYYY-MM-DD)
end_date (obligatoire) : Date de fin de la période statistique (YYYY-MM-DD)
breakdown (facultatif) : 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 ID de domaine (tableau d’entiers)
sending_streams (facultatif) : Limiter à transactional et/ou bulk (tableau de chaînes)
categories (facultatif) : Limiter à ces catégories d’e-mail (tableau de chaînes)
email_service_providers (facultatif) : Limiter à ces fournisseurs, par exemple Google, Yahoo, Outlook (tableau de chaînes)

get-marketing-stats

Récupère les statistiques agrégées d’Email Marketing pour les campagnes et les automatisations sur une période donnée : nombres et taux d’envois, de livraisons, de rebonds, d’ouvertures, de clics, de signalements comme spam et de désabonnements. delivery_rate et bounce_rate sont des parts de sent_count ; les autres taux sont des parts de delivery_count.

Paramètres :

start_date (obligatoire) : Début de la période (inclus), YYYY-MM-DD
end_date (obligatoire) : Fin de la période (incluse), YYYY-MM-DD
sending_domain_ids (facultatif) : Limiter les résultats à ces ID de domaine (tableau d’entiers)
sources (facultatif) : campaigns ou automations limite les statistiques à cette source ; omettez ce paramètre ou indiquez les deux pour inclure tout le trafic Email Marketing (tableau de chaînes)
email_service_providers (facultatif) : Limiter à ces fournisseurs, par exemple Google, Yahoo, Outlook (tableau de chaînes)

create-template

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

Paramètres :

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

list-templates

Répertorie les modèles d’e-mail de votre compte Mailtrap avec une pagination par jeton de page. Lorsqu’il existe d’autres modèles, le résultat indique le token de la page suivante. Les pages correspondent à des décalages dans la liste triée des plus récents aux plus anciens ; après avoir supprimé des modèles, relancez la liste à partir de token 1 au lieu de continuer avec le jeton suivant. Une page vide indique la dernière page contenant encore des modèles.

Paramètres :

token (facultatif) : Numéro de la page à récupérer (pagination par jeton de page). Par défaut : 1
per_page (facultatif) : Nombre de modèles par page. Par défaut : 50, maximum 100. Indiquez la même valeur pour chaque page

get-template

Récupère un modèle d’e-mail par ID, avec son objet, sa catégorie et son 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) : Nouvel objet de l’e-mail
html (facultatif) : Nouveau contenu HTML du modèle
text (facultatif) : Nouvelle version en texte brut du modèle
category (facultatif) : 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 (obligatoire) : ID du modèle à supprimer

send-sandbox-email

Envoie un e-mail à votre sandbox Mailtrap à des fins de développement et de test. C’est idéal pour tester des modèles d’e-mail sans envoyer de messages à de vrais destinataires. Prend en charge les deux mêmes modes que send-email — contenu intégré ou basé sur un modèle (template_uuid).

Paramètres :

sandbox_id (facultatif) : Préféré. ID du sandbox Mailtrap. Obligatoire sauf si MAILTRAP_SANDBOX_ID est défini.
test_inbox_id (facultatif) : Alias hérité de sandbox_id lorsque sandbox_id est omis.
from (facultatif) : Expéditeur au format { email, name? } (une simple adresse e-mail est également acceptée à l’exécution). Si cette valeur n’est pas fournie, DEFAULT_FROM_EMAIL est utilisé.
to (facultatif) : Tableau de destinataires sous forme d’objets { email, name? } (les simples adresses e-mail dans le tableau ou une chaîne d’adresses e-mail simples séparées par des virgules sont également acceptées à l’exécution). 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 (CC) sous forme d’objets { email, name? } (les simples adresses e-mail sont également acceptées à l’exécution).
bcc (facultatif) : Tableau de destinataires en copie cachée (BCC) sous forme d’objets { email, name? } (les simples adresses e-mail sont également acceptées à l’exécution).
subject (conditionnel) : 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 de l’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 à la place du contenu en ligne. Lorsque cette valeur est définie, subject / text / html / category doivent être omis.
template_variables (facultatif) : Objet contenant les 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 sandbox Mailtrap en un seul appel API, sans les remettre à de vrais destinataires. Même structure base + requests[], mêmes règles de validation et mêmes règles d’envoi en ligne ou par modèle que pour batch-send-transactional-email — la différence est que cet outil achemine l’appel via le point de terminaison du sandbox pour un seul sandbox.

Paramètres :

sandbox_id (facultatif) : ID du sandbox Mailtrap. Obligatoire sauf si MAILTRAP_SANDBOX_ID est défini ; transmettez-le à chaque appel pour cibler un sandbox spécifique.
base (facultatif), requests (obligatoire) : Voir batch-send-transactional-email ci-dessus.

[!NOTE] La plupart des outils de sandbox utilisent sandbox_id (ou se rabattent sur MAILTRAP_SANDBOX_ID ; la variable d’environnement obsolète MAILTRAP_TEST_INBOX_ID fonctionne toujours). send-sandbox-email, get-sandbox-messages et show-sandbox-email-message acceptent également l’ancien test_inbox_id. get-sandbox, update-sandbox, delete-sandbox et clean-sandbox utilisent sandbox_id avec l’ancien inbox_id (même ID ; inbox_id n’est pas utilisé par les outils de messagerie). Les outils de messagerie entrante utilisent inbox_id pour un produit différent (courrier reçu), et non pour le sandbox.

get-sandbox-messages

Récupère la liste des messages de votre sandbox Mailtrap. Utile pour vérifier quels e-mails ont été reçus dans votre sandbox pendant les tests.

Paramètres :

sandbox_id (facultatif) : Préféré. ID du sandbox, sauf si MAILTRAP_SANDBOX_ID est défini.
test_inbox_id (facultatif) : Alias hérité de sandbox_id.
page (facultatif) : Numéro de page pour la pagination (minimum : 1)
last_id (facultatif) : Pagination à l’aide du dernier ID de message. Renvoie les messages suivant l’ID de message indiqué (minimum : 1)
search (facultatif) : Requête de recherche pour filtrer les messages

[!NOTE] Les paramètres d’ID du sandbox sont facultatifs lorsque MAILTRAP_SANDBOX_ID est défini. Si aucun de sandbox_id, test_inbox_id ou de la variable d’environnement n’est fourni, l’appel échoue. Pagination : utilisez page, last_id ou search selon vos besoins.

show-sandbox-email-message

Affiche des informations détaillées et le contenu d’un e-mail spécifique de votre sandbox Mailtrap, y compris le corps HTML et texte.

Paramètres :

sandbox_id (facultatif) : Préféré. ID du sandbox, sauf si MAILTRAP_SANDBOX_ID est défini.
test_inbox_id (facultatif) : Alias hérité de sandbox_id.
message_id (obligatoire) : ID du message e-mail du sandbox à récupérer

[!NOTE] Utilisez d’abord get-sandbox-messages pour obtenir les ID des messages, puis cet outil pour afficher leur contenu complet.

list-sandbox-projects

Liste tous les projets de sandbox et leurs sandboxes.

Paramètres :

Aucun paramètre requis

create-sandbox-project

Crée un projet de sandbox pour regrouper des sandboxes.

Paramètres :

name (obligatoire) : Nom du projet (2 à 100 caractères)

get-sandbox-project

Récupère un projet de sandbox par ID, y compris ses sandboxes et le nombre d’e-mails.

Paramètres :

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

update-sandbox-project

Renomme un projet de sandbox existant.

Paramètres :

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

delete-sandbox-project

Supprime un projet de sandbox et tous ses sandboxes.

Paramètres :

project_id (obligatoire) : ID du projet à supprimer

create-sandbox

Crée un sandbox dans un projet. Renvoie les nouveaux identifiants SMTP du sandbox.

Paramètres :

project_id (obligatoire) : ID du projet dans lequel créer le sandbox
name (obligatoire) : Nom du sandbox

get-sandbox

Récupère les détails d’un sandbox, y compris les identifiants SMTP, le nombre d’e-mails et son état.

Paramètres :

sandbox_id (facultatif) : ID du sandbox. Obligatoire sauf si MAILTRAP_SANDBOX_ID est défini.
inbox_id (facultatif) : Alias hérité de sandbox_id.

update-sandbox

Met à jour le nom ou le nom d’utilisateur e-mail d’un sandbox.

Paramètres :

sandbox_id (obligatoire) : ID du sandbox (alias hérité : inbox_id)
name (facultatif) : Nouveau nom du sandbox
email_username (facultatif) : Nouveau nom d’utilisateur e-mail du sandbox

Au moins l’un de name ou email_username doit être fourni.

delete-sandbox

Supprime un sandbox et tous ses messages.

Paramètres :

sandbox_id (obligatoire) : ID du sandbox (alias hérité : inbox_id)

clean-sandbox

Supprime tous les messages d’un sandbox sans supprimer le sandbox lui-même.

Paramètres :

sandbox_id (obligatoire) : ID du sandbox (alias hérité : inbox_id)

list-sandboxes

Liste tous les sandboxes accessibles au jeton API dans l’ensemble des projets.

Paramètres :

Aucun paramètre requis

mark-sandbox-as-read

Marque comme lus tous les messages d’un sandbox.

Paramètres :

sandbox_id (obligatoire) : ID du sandbox concerné

reset-sandbox-credentials

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

Paramètres :

sandbox_id (obligatoire) : ID du sandbox concerné

enable-sandbox-email-address

Active l’adresse de réception des e-mails d’un sandbox (active l’adresse Mailtrap qui achemine les messages vers le sandbox via SMTP).

Paramètres :

sandbox_id (obligatoire) : ID du sandbox concerné

reset-sandbox-email-address

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

Paramètres :

sandbox_id (obligatoire) : ID du sandbox concerné

forward-sandbox-message

Transfère un message du sandbox vers une adresse e-mail externe. Le transfert est décompté de votre quota mensuel.

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox à transférer
email (obligatoire) : Adresse e-mail vers laquelle transférer le message

update-sandbox-message

Marque un message du sandbox comme lu ou non lu.

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox à mettre à jour
is_read (obligatoire) : true marque le message comme lu, false le marque comme non lu

delete-sandbox-message

Supprime un seul message du sandbox.

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox à supprimer

get-sandbox-message-spam-score

Récupère le rapport SpamAssassin d’un message du 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. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-html-analysis

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-headers

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-html

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-text

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-raw

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-eml

Récupère le message sous forme de contenu de fichier EML (adapté à une pièce jointe à un ticket ou à l’importation dans un autre client de messagerie).

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-message-html-source

Récupère le code source HTML non rendu d’un message du sandbox (HTML avant toute transformation côté Mailtrap, comme la réécriture des liens CID).

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

list-sandbox-attachments

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox

get-sandbox-attachment

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

Paramètres :

sandbox_id (facultatif) : ID du sandbox. À défaut, utilise MAILTRAP_SANDBOX_ID.
message_id (obligatoire) : ID du message du sandbox contenant la pièce jointe
attachment_id (obligatoire) : ID de la pièce jointe à récupérer

list-domains

Liste les domaines et leur état de vérification DNS.

Paramètres :

Aucun paramètre requis

get-domain

Récupère un domaine par ID et son état de vérification (y compris les enregistrements DNS). Vous pouvez inclure des instructions de configuration DNS en définissant include_setup_instructions sur true.

Paramètres :

domain_id (obligatoire) : ID du domaine (alias hérité : sending_domain_id)
include_setup_instructions (facultatif) : Si true, ajoute les instructions de configuration DNS à la réponse. Valeur par défaut : false

create-domain

Crée un domaine. Après sa création, ajoutez des enregistrements DNS pour le vérifier (utilisez get-domain avec include_setup_instructions: true pour afficher les enregistrements).

Paramètres :

domain_name (obligatoire) : Nom de domaine (par exemple, example.com)

update-domain

Mettre à jour les paramètres de suivi et de réception d’un domaine.

Paramètres :

domain_id (obligatoire) : ID du domaine (ancien alias : sending_domain_id)
open_tracking_enabled (facultatif) : Suivre les ouvertures des e-mails envoyés depuis ce domaine
click_tracking_enabled (facultatif) : Suivre les clics sur les liens des e-mails envoyés depuis ce domaine
tracking_opt_out_enabled (facultatif) : Ajouter le lien de désactivation du suivi aux e-mails suivis. Nécessite le suivi des ouvertures ou des clics
auto_unsubscribe_link_enabled (facultatif) : Ajouter automatiquement un lien de désabonnement aux e-mails
inbound_enabled (facultatif) : Autoriser l’association du domaine à une boîte de réception entrante en tant que domaine fourre-tout

Au moins un paramètre autre que domain_id doit être fourni.

delete-domain

Supprimer un domaine.

Paramètres :

domain_id (obligatoire) : ID du domaine à supprimer (ancien alias : sending_domain_id)

send-domain-setup-instructions

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

Paramètres :

domain_id (obligatoire) : ID du domaine (ancien alias : sending_domain_id)
email (obligatoire) : Adresse e-mail à laquelle envoyer les instructions de configuration DNS

get-company-info

Obtenir les informations sur l’entreprise d’un domaine, utilisées pour la vérification de conformité du domaine.

Paramètres :

domain_id (obligatoire) : ID du domaine (ancien alias : sending_domain_id)

create-company-info

Définir les informations sur l’entreprise d’un domaine, requises pour la vérification de conformité du domaine.

Paramètres :

domain_id (obligatoire) : ID du domaine (ancien alias : sending_domain_id)
name (obligatoire) : Nom de l’entreprise ou de la personne
address (obligatoire) : Adresse postale
city (obligatoire) : Ville
country (obligatoire) : Pays
zip_code (obligatoire) : Code postal
website_url (obligatoire) : URL du site Web de l’entreprise
phone (facultatif) : Numéro de téléphone
privacy_policy_url (facultatif) : URL de la page de politique de confidentialité
terms_of_service_url (facultatif) : URL de la page des conditions d’utilisation
info_level (facultatif) : business ou individual

update-company-info

Mettre à jour les informations sur l’entreprise d’un domaine.

Paramètres :

domain_id (obligatoire) : ID du domaine (ancien alias : sending_domain_id)
Tous les champs de create-company-info sont facultatifs. Au moins un doit être fourni ; les champs omis restent inchangés.

list-suppressions

Répertorier ou rechercher 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.

create-suppression

Ajouter une adresse e-mail à la liste de suppression du compte afin que Mailtrap cesse de lui envoyer des e-mails.

Paramètres :

email (obligatoire) : Adresse e-mail à supprimer
domain_id (obligatoire) : ID du domaine auquel s’applique la suppression
sending_stream (obligatoire) : transactional ou bulk
type (facultatif) : hard bounce, spam complaint, unsubscription ou manual import. Valeur par défaut : manual import

delete-suppression

Supprimer une suppression par ID. Mailtrap reprendra l’envoi à cette adresse e-mail, sauf si elle est à nouveau supprimée.

Paramètres :

suppression_id (obligatoire) : ID de la suppression à supprimer

list-tracking-opt-outs

Répertorier les adresses e-mail exclues du suivi des ouvertures et des clics. Renvoie jusqu’à 1000 enregistrements par appel.

Paramètres :

email (facultatif) : Filtre par e-mail. Renvoie uniquement les exclusions correspondant à cette adresse
start_time (facultatif) : Uniquement les exclusions créées à partir de cette date et heure (ISO 8601)
end_time (facultatif) : Uniquement les exclusions créées jusqu’à cette date et heure (ISO 8601)
last_id (facultatif) : Curseur de pagination — le last_id de la réponse précédente

create-tracking-opt-out

Exclure une adresse e-mail du suivi des ouvertures et des clics pour un domaine.

Paramètres :

email (obligatoire) : Adresse e-mail à exclure du suivi
domain_id (obligatoire) : ID du domaine auquel s’applique l’exclusion

delete-tracking-opt-out

Retirer une adresse e-mail de la liste d’exclusion du suivi afin que le suivi des ouvertures et des clics s’applique à nouveau.

Paramètres :

tracking_opt_out_id (obligatoire) : ID de l’exclusion du suivi à supprimer

list-webhooks

Répertorier 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

Obtenir un webhook par 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éer un webhook. La réponse inclut un signing_secret permettant de vérifier les signatures des charges utiles du webhook — ce secret n’est renvoyé qu’à la création ; enregistrez-le donc maintenant. Si vous le perdez, recréez le webhook.

Paramètres :

url (obligatoire) : URL à laquelle Mailtrap enverra les événements du webhook par POST
webhook_type (obligatoire) : "email_sending", "audit_log" ou "inbound_receiving"
active (facultatif, booléen) : valeur par défaut : true
payload_format (facultatif) : "json" ou "jsonlines". Valeur 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 auquel limiter ce webhook
inbound_inbox_id (facultatif, inbound_receiving uniquement) : ID de la boîte de réception entrante associée au webhook ; omettre pour l’appliquer à toutes les boîtes de réception du compte

update-webhook

Mettre à 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 associée au webhook

delete-webhook

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

Paramètres :

webhook_id (obligatoire) : ID du webhook à supprimer

get-contact

Obtenir un contact par ID ou par 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éer un contact.

Paramètres :

email (obligatoire) : Adresse e-mail
fields (facultatif) : 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 (facultatif) : ID des listes de contacts auxquelles abonner ce contact
unsubscribed (facultatif, booléen) : Créer le contact avec le statut unsubscribed

update-contact

Mettre à jour un contact existant identifié par ID ou par e-mail. list_ids remplace l’ensemble des appartenances du contact ; list_ids_included/list_ids_excluded ajoutent ou retirent des appartenances sans modifier les autres.

Paramètres :

contact_identifier (obligatoire) : ID du contact ou adresse e-mail
email (facultatif) : Nouvelle adresse e-mail
fields (facultatif) : Valeurs des champs personnalisés indexées par balise de fusion
list_ids (facultatif) : Remplacer l’ensemble des appartenances par cette liste exacte
list_ids_included (facultatif) : ID des listes à ajouter (ajout)
list_ids_excluded (facultatif) : ID des listes à retirer
unsubscribed (facultatif, booléen) : Définir sur unsubscribed (true) ou subscribed (false)

delete-contact

Supprimer définitivement un contact par ID ou par e-mail. Renvoie l’enregistrement du contact supprimé si l’API en fournit un ; sinon, renvoie une charge utile de confirmation.

Paramètres :

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

create-contact-event

Enregistrer un événement associé à un contact (par ID ou par e-mail). Sert à déclencher les automatisations des listes de contacts.

Paramètres :

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

list-contact-lists

Répertorier 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

Obtenir une liste de contacts par ID.

Paramètres :

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

create-contact-list

Créer une liste de contacts.

Paramètres :

name (obligatoire) : Nom de la nouvelle liste

update-contact-list

Renommer 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

Supprimer définitivement une liste de contacts par ID.

Paramètres :

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

list-contact-fields

Répertorier toutes les définitions de champs de contact du compte.

Paramètres :

Aucun paramètre requis

get-contact-field

Obtenir une définition de champ de contact par ID.

Paramètres :

field_id (obligatoire) : ID du champ de contact

create-contact-field

Créer une définition de champ de contact. merge_tag doit être unique dans le compte et sert de nom de remplacement dans les variables de modèle.

Paramètres :

name (obligatoire) : Nom d’affichage (par ex. « Prénom »)
merge_tag (obligatoire) : Nom de remplacement unique (par ex. first_name)
data_type (obligatoire) : L’un de text, number, boolean, date

update-contact-field

Mettre à 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) : L’un de text, number, boolean, date

delete-contact-field

Supprimer 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

Importer 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 doit contenir :
- email (obligatoire) : Adresse e-mail du contact
- fields (facultatif) : Valeurs des champs personnalisés indexées 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

Obtenir le statut d’une tâche d’importation de contacts (créée/démarrée/terminée/échouée), ainsi que le nombre de contacts créés, mis à jour et dépassant la limite.

Paramètres :

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

create-contact-export

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

Paramètres :

filters (obligatoire) : Tableau d’objets de filtre. Chacun contient :
- name (obligatoire) : Champ sur lequel appliquer le filtre (list_id, subscription_status, email, etc.)
- operator (obligatoire) : L’une des valeurs suivantes : 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

Obtenir l’état d’une tâche d’exportation de contacts. Une fois que status vaut finished, le champ url contient le lien de téléchargement du fichier CSV.

Paramètres :

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

list-email-campaigns

Lister les campagnes e-mail du compte, de la plus récente à la plus ancienne, avec une pagination par jeton de page. Filtrer éventuellement par nom avec search.

Paramètres :

token (facultatif) : Numéro de page à récupérer (pagination par jeton de page). La valeur par défaut est 1
per_page (facultatif) : Nombre de campagnes par page. La valeur par défaut est 50, le maximum est 100
search (facultatif) : Filtrer les campagnes par nom (correspondance partielle sans distinction entre majuscules et minuscules)

get-email-campaign

Obtenir une campagne e-mail par ID.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail

create-email-campaign

Créer une campagne e-mail. La campagne est toujours créée à l’état draft ; la planification et le démarrage s’effectuent avec des outils distincts (schedule-email-campaign, start-email-campaign).

Paramètres :

name (obligatoire) : Nom de la campagne
domain_id (obligatoire) : ID du domaine vérifié utilisé pour la campagne, tel que renvoyé par list-domains
from_local_part (obligatoire) : Partie locale (avant le @) de l’adresse d’expéditeur
template_attributes (obligatoire) : Modèle d’e-mail intégré. Contient :
- subject (obligatoire) : Objet de l’e-mail (255 caractères max.). Prend en charge les balises de fusion, par exemple Hi {{first_name}}
- body_html (facultatif) : Corps HTML (la conception). Obligatoire avant de pouvoir planifier ou démarrer la campagne. Inclure un lien de désabonnement via une ancre dont le href contient le placeholder __unsubscribe_url__
- body_text (facultatif) : Version texte brut du corps de l’e-mail
- merge_tags (facultatif) : Noms seuls des balises de fusion référencées dans l’objet/le corps, par exemple ["first_name"]
from_display_name (facultatif) : Nom d’affichage figurant dans l’en-tête From
reply_to (facultatif) : Éléments de l’adresse Reply-To (display_name, local_part, domain)
delivery_mode (facultatif) : rapid (envoyer aussi vite que possible) ou gradual (limiter le débit à delivery_options.emails_per_hour)
delivery_options (facultatif) : Options de limitation du débit d’envoi (emails_per_hour)
contact_list_ids (facultatif) : ID des listes de contacts auxquelles envoyer la campagne (considérées comme l’ensemble complet des listes incluses)
contact_segment_ids (facultatif) : ID des segments de contacts auxquels envoyer la campagne (considérés comme l’ensemble complet des segments inclus)

update-email-campaign

Mettre à jour une campagne e-mail à l’état draft. Seuls les champs fournis sont modifiés ; le modèle est modifié sur place. Les campagnes dans tout autre état ne peuvent pas être mises à jour.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à mettre à jour
Tous les autres paramètres sont facultatifs et identiques à ceux de create-email-campaign (name, domain_id, from_local_part, from_display_name, reply_to, template_attributes, delivery_mode, delivery_options, contact_list_ids, contact_segment_ids)

delete-email-campaign

Supprimer une campagne e-mail par ID. Seule une campagne à l’état draft peut être supprimée.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à supprimer

start-email-campaign

Démarrer immédiatement l’envoi d’une campagne e-mail draft. Seules les campagnes draft peuvent être démarrées ; le modèle doit avoir une conception body_html, et l’audience ainsi que le domaine vérifié doivent être définis.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à démarrer

schedule-email-campaign

Planifier le démarrage de l’envoi d’une campagne e-mail draft à une date ultérieure. Seules les campagnes draft peuvent être planifiées.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à planifier
datetime (obligatoire) : Date et heure d’envoi de la campagne (ISO 8601). Doit être dans le futur et ne pas dépasser un mois à l’avance

cancel-email-campaign

Annuler une campagne e-mail scheduled et la remettre à l’état draft. Seules les campagnes scheduled peuvent être annulées.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à annuler

terminate-email-campaign

Mettre fin à une campagne e-mail en cours d’envoi (started, queued ou paused), en interrompant l’envoi en cours.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à interrompre

reset-email-campaign

Réinitialiser une campagne e-mail scheduled pour la remettre à l’état draft. Seules les campagnes scheduled peuvent être réinitialisées.

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail à réinitialiser

get-email-campaign-stats

Obtenir les statistiques agrégées de performance d’une campagne e-mail (nombres et taux de distribution, d’ouvertures, de clics, de rebonds, de signalements comme spam et de désabonnements).

Paramètres :

email_campaign_id (obligatoire) : ID de la campagne e-mail
start_date (facultatif) : Début de la période d’agrégation (inclus), YYYY-MM-DD. Par défaut, le jour du dernier démarrage de la campagne
end_date (facultatif) : Fin de la période d’agrégation (incluse), YYYY-MM-DD. Par défaut, la date du jour

list-accounts

Lister les comptes Mailtrap auxquels le jeton API actuel peut accéder, avec les niveaux d’accès de chacun. Fonctionne sans MAILTRAP_ACCOUNT_ID ; utilisez-le donc pour trouver l’ID de votre compte.

Paramètres :

Aucun paramètre requis

get-billing-usage

Obtenir l’utilisation du compte pour le cycle de facturation en cours : forfaits d’envoi et de test, limites et nombres actuels.

Paramètres :

Aucun paramètre requis

list-account-accesses

Lister les accès au compte (utilisateurs, invitations, jetons API). Des filtres facultatifs permettent de limiter les résultats à des ressources spécifiques. Nécessite les autorisations d’administrateur ou de propriétaire du compte.

Paramètres :

domain_uuids (facultatif) : Filtrer par UUID de domaine (tableau de chaînes)
inbox_ids (facultatif) : Filtrer par ID de sandbox (tableau de chaînes)
project_ids (facultatif) : Filtrer par ID de projet sandbox (tableau de chaînes)

remove-account-access

Supprimer un accès au compte par ID. Pour les identifiants User, cette opération révoque leurs autorisations ; pour les identifiants Invite ou ApiToken, elle supprime entièrement l’identifiant. Nécessite les autorisations d’administrateur ou de propriétaire.

Paramètres :

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

get-permission-resources

Obtenir toutes les ressources (sandboxes, projets, domaines, facturation, compte) sur lesquelles le jeton API dispose d’un accès administrateur, organisées selon la hiérarchie.

Paramètres :

Aucun paramètre requis

bulk-update-permissions

Créer, mettre à jour ou supprimer en masse des autorisations pour un seul accès au compte. Les paires (resource_type, resource_id) existantes sont mises à jour ; les nouvelles sont créées. Définir 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 contient :
- resource_id (obligatoire) : ID de la ressource (nombre ou chaîne)
- resource_type (obligatoire) : L’une des valeurs suivantes : account, project, inbox, domain, billing
- access_level (facultatif) : admin/100 ou viewer/10
- destroy (facultatif, booléen) : Si la valeur est true, supprime cette autorisation au lieu de la créer ou de la mettre à jour

list-api-tokens

Lister tous les jetons API du compte.

Paramètres :

Aucun paramètre requis

create-api-token

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

Paramètres :

name (obligatoire) : Nom d’affichage du jeton
expires_at (facultatif) : Date d’expiration du jeton au format date-heure ISO 8601. Omettre ce paramètre pour utiliser la valeur par défaut du serveur (1 an) ; fournir explicitement null pour un jeton qui n’expire jamais. Les dates passées ou situées à plus de 5 ans dans le futur sont refusées
resources (facultatif) : Tableau d’autorisations de ressources pour limiter la portée du jeton. Chaque entrée contient :
- resource_type (obligatoire) : L’une des valeurs suivantes : account, project, inbox, domain, billing
- resource_id (obligatoire) : ID de la ressource
- access_level (obligatoire) : 100 (administrateur) ou 10 (lecteur)

get-api-token

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

Paramètres :

api_token_id (obligatoire) : ID du jeton API

reset-api-token

Réinitialiser (faire tourner) un jeton API par ID. La réponse inclut la nouvelle valeur secrète token — renvoyée uniquement lors de cet appel ; enregistrez-la immédiatement. L’ancien jeton est invalidé.

Paramètres :

api_token_id (obligatoire) : ID du jeton API à réinitialiser
expires_at (facultatif) : Date d’expiration du nouveau jeton au format date-heure ISO 8601. Omettre ce paramètre pour utiliser la valeur par défaut du serveur (1 an) ; fournir explicitement null pour un jeton qui n’expire jamais. Les dates passées ou situées à plus de 5 ans dans le futur sont refusées

delete-api-token

Supprimer définitivement un jeton API par ID. Après sa suppression, le jeton ne peut plus servir à l’authentification.

Paramètres :

api_token_id (obligatoire) : ID du jeton API à supprimer

list-sub-accounts

Lister 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éer un sous-compte dans 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

delete-sub-account

Supprimer définitivement un sous-compte par ID et toutes ses données. La suppression du dernier sous-compte entraîne la suppression de l’organisation ; un nouvel appel renvoie 404. Une suppression simultanée du même sous-compte renvoie 409. Nécessite la variable d’environnement MAILTRAP_ORGANIZATION_ID et les autorisations d’administrateur de l’organisation. La fonctionnalité Organization & Sub-accounts doit être activée pour l’organisation (sinon, 403).

Paramètres :

sub_account_id (obligatoire) : ID du sous-compte à supprimer

list-inbound-folders

Lister tous les dossiers entrants du compte. Renvoie un résumé mis en forme.

Paramètres :

Aucun paramètre requis

get-inbound-folder

Obtenir un dossier entrant par ID. Renvoie l’enregistrement complet du dossier au format JSON.

Paramètres :

folder_id (obligatoire) : ID du dossier entrant

create-inbound-folder

Créer un dossier entrant.

Paramètres :

name (obligatoire) : Nom du dossier

update-inbound-folder

Renommer un dossier entrant.

Paramètres :

folder_id (obligatoire) : ID du dossier entrant
name (obligatoire) : Nouveau nom du dossier

delete-inbound-folder

Supprimer 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

Lister toutes les boîtes de réception d’un dossier entrant. Renvoie un résumé mis en forme.

Paramètres :

folder_id (obligatoire) : ID du dossier entrant

get-inbound-inbox

Obtenir une boîte de réception par ID. Renvoie l’enregistrement complet de la boîte de réception 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éer une boîte de réception dans un dossier entrant.

Paramètres :

folder_id (obligatoire) : ID du dossier de réception
name (obligatoire) : Nom de la boîte de réception
domain_id (facultatif) : Associer à un domaine personnalisé (boîte de réception fourre-tout). Omettre pour une boîte de réception hébergée par Mailtrap

update-inbound-inbox

Renommer une boîte de réception entrante.

Paramètres :

folder_id (obligatoire) : ID du dossier de réception
inbox_id (obligatoire) : ID de la boîte de réception
name (obligatoire) : Nouveau nom de la boîte de réception

delete-inbound-inbox

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

Paramètres :

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

list-inbound-messages

Lister 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 lorsqu'il existe d'autres résultats.

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érer 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

Supprimer 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épondre à un message entrant (envoi à l'expéditeur d'origine). Envoie un véritable e-mail. Les adresses peuvent être une adresse e-mail seule 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. Refusé pour les boîtes de réception hébergées par Mailtrap ; obligatoire pour les boîtes de réception associées à un domaine personnalisé
cc / bcc / reply_to (facultatif) : Adresses supplémentaires
category (facultatif) : Catégorie du message
attachments (facultatif) : Tableau de { content (base64), filename, type?, disposition?, content_id? }
headers / custom_variables (facultatif) : Objets contenant des valeurs de type chaîne

reply-all-to-inbound-message

Répondre à un message entrant en mettant 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
Ainsi que les mêmes champs d'envoi facultatifs que reply-to-inbound-message

forward-inbound-message

Transférer 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 (adresse e-mail seule ou { email, name? }, ou un tableau)
Ainsi que les mêmes champs d'envoi facultatifs que reply-to-inbound-message

list-inbound-threads

Lister les fils de conversation d'une boîte de réception entrante (pagination par curseur), avec un filtrage facultatif par search. Renvoie un résumé formaté avec une indication de page suivante lorsqu'il existe d'autres résultats.

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
search (facultatif) : Texte sans distinction entre majuscules et minuscules, comparé à l'objet du fil et aux adresses de ses messages dans les champs from/to/cc/bcc. Transmettre la même valeur lors de la pagination

get-inbound-thread

Récupérer 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

Supprimer définitivement un fil entrant.

Paramètres :

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

list-inbound-forward-rules

Lister les règles de transfert d'une boîte de réception entrante. Renvoie un résumé formaté.

Paramètres :

inbox_id (obligatoire) : ID de la boîte de réception

get-inbound-forward-rule

Récupérer une règle de transfert entrante par son ID. Renvoie l'enregistrement complet de la règle au format JSON, y compris ses conditions et ses destinations.

Paramètres :

inbox_id (obligatoire) : ID de la boîte de réception
forward_rule_id (obligatoire) : ID de la règle de transfert

create-inbound-forward-rule

Créer une règle de transfert pour une boîte de réception entrante. Les messages reçus qui satisfont toutes les conditions sont transférés vers les destinations de la règle.

Paramètres :

inbox_id (obligatoire) : ID de la boîte de réception
name (obligatoire) : Nom de la règle, unique dans la boîte de réception
conditions (facultatif) : Tableau de { match_type, operator, value?, header_key? }. match_type est sender, recipient ou header ; operator est equal, not_equal, contains, starts_with, ends_with, empty ou not_empty (empty/not_empty uniquement pour header, et ne prennent aucun value) ; header_key est obligatoire pour header. Omettre ou transmettre [] pour correspondre à tous les messages
destinations (facultatif) : Tableau de { email } vers lesquels transférer les messages correspondants

update-inbound-forward-rule

Mettre à jour une règle de transfert entrante. Seuls les champs fournis sont modifiés ; un tableau conditions ou destinations fourni remplace l'ensemble complet.

Paramètres :

inbox_id (obligatoire) : ID de la boîte de réception
forward_rule_id (obligatoire) : ID de la règle de transfert
name (facultatif) : Nouveau nom de la règle
conditions (facultatif) : Ensemble de conditions de remplacement (même structure qu'à la création) ; [] supprime toutes les conditions, de sorte que la règle correspond à tous les messages
destinations (facultatif) : Ensemble de destinations de remplacement ; [] supprime toutes les destinations

delete-inbound-forward-rule

Supprimer définitivement une règle de transfert entrante.

Paramètres :

inbox_id (obligatoire) : ID de la boîte de réception
forward_rule_id (obligatoire) : ID de la règle de transfert

Développement

Cloner le dépôt :

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

Installer 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": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Si vous utilisez asdf pour gérer Node.js, vous devez utiliser le chemin absolu de 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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

VS Code

[!TIP] 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": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

Tests

Exécuter les outils avec un véritable compte Mailtrap

Il existe deux façons de tester un outil de bout en bout avec un véritable compte Mailtrap : l'interface Web du MCP Inspector pour une exploration interactive, ou son mode CLI pour effectuer des appels ponctuels depuis le shell.

Dans les deux cas, le bundle doit d'abord être compilé :

npm run build

et MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID doivent être exportés dans votre shell (le script mcp:cli transmet les deux au serveur lancé).

Interface Web

npm run dev

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

CLI

Pour effectuer 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-domain-setup-instructions \
  --tool-arg domain_id=3938 \
  --tool-arg email=devops@example.com

Exécuter le 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 le 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élai d'expiration de l'opération (30 secondes par défaut)

Les erreurs comprennent des messages exploitables et sont consignées sous forme structurée.

Sécurité

Validation des entrées à l'aide de schémas Zod
Gestion sécurisée des variables d'environnement
Protection contre les délais d'expiration des opérations (30 secondes)
Assainissement des informations sensibles dans les messages d'erreur

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 que les hôtes rencontrent des erreurs d'analyse JSON dues à l'entrelacement des journaux.

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

Dépannage

Problèmes courants :

Jeton API manquant : vérifiez que MAILTRAP_API_TOKEN est défini
Le sandbox ne fonctionne pas : fournissez sandbox_id dans l'appel d'outil (ou l'ancien test_inbox_id pour les outils d'envoi/liste/affichage de messages), ou définissez la variable d'environnement MAILTRAP_SANDBOX_ID
Erreurs de délai d'expiration : vérifiez la connectivité réseau et l'état de l'API Mailtrap
Erreurs de validation : vérifiez que tous les champs obligatoires sont renseignés

Contribution

Les rapports de bogues et les demandes de fusion sont les bienvenus sur GitHub. Ce projet vise à offrir un espace sûr et accueillant pour la collaboration ; les contributeurs sont tenus de respecter le code de conduite.

Licence

Ce package est disponible en open source selon les termes de la licence MIT.

Code de conduite

Toute personne participant aux bases de code, aux systèmes de suivi des problèmes, aux salons de discussion et aux listes de diffusion du projet Mailtrap est tenue de respecter le code de conduite.