Mailtrap

Serveur MCP officiel Mailtrap

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

Envoyez des e-mails transactionnels et en masse, testez des messages en toute sécurité dans Email Sandbox, gérez des modèles, des contacts, des domaines d'envoi et des webhooks, inspectez les journaux d'e-mails et les statistiques de livraison, résolvez les problèmes de délivrabilité et gérez les ressources du compte — le tout à l'aide de requêtes 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.
• Test d'e-mails — Testez des messages dans Email Sandbox et inspectez le contenu, les en-têtes, les pièces jointes, les scores de spam et la compatibilité client HTML.
• Surveillance de la livraison — Recherchez dans les journaux d'e-mails, inspectez l'historique des événements et analysez les taux de livraison, de rebond, d'ouverture, de clic et de spam.
• Infrastructure e-mail — Gérez les domaines d'envoi, la vérification DNS, les webhooks et les suppressions.
• Contacts — Gérez les contacts, les listes, les champs personnalisés et les événements, avec importations et 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 MCP. Les instructions de configuration pour chacun sont ci-dessous.

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 du compte Mailtrap

Variables d'environnement requises :

• MAILTRAP_API_TOKEN - Requis pour toutes les fonctionnalités
• MAILTRAP_ACCOUNT_ID - Requis pour les modèles, les statistiques, les journaux d'e-mails, l'affichage/la liste de la sandbox, les domaines d'envoi et les suppressions. Optionnel uniquement pour les outils d'envoi (send-email, send-sandbox-email et les outils batch-send-*), les outils de campagne e-mail, les outils d'informations sur l'entreprise et les outils de désinscription au suivi.

Optionnel (peut être transmis 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ù 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 de sandbox lorsque sandbox_id n'est pas fourni. Permet de basculer entre les sandbox 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 de sandbox lorsque test_inbox_id n'est pas fourni. Permet de basculer entre les boîtes de réception par appel via le paramètre test_inbox_id. Alias hérité pour MAILTRAP_SANDBOX_ID, toujours honoré 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

CLI Smithery

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

npx @smithery/cli install mailtrap

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

Configuration

Claude Desktop

Utilisez MCPB pour installer le serveur Mailtrap. Vous pouvez trouver ces fichiers dans 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

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

Utilisation

Une fois configuré, vous pouvez demander à l'agent d'envoyer des e-mails et de gérer des 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 concernant notre prochaine réunion."
• "Envoyez un e-mail à sarah@example.com concernant la mise à jour du projet, et mettez l'équipe en copie à 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 l'apparence de notre e-mail de bienvenue"

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

• "Listez mes journaux d'e-mails envoyés récents"
• "Affichez les journaux d'e-mails envoyés à user@example.com"
• "Obtenez le message du journal d'e-mails 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 2025-01-01 au 2025-01-31 ?"

Opérations Sandbox :

• "Obtenez 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 sur les modèles :

• "Listez tous les modèles d'e-mails dans 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"
• "Activez le suivi des clics pour le domaine d'envoi 3938"
• "Supprimez le domaine d'envoi 3938"
• "Obtenez le domaine d'envoi 3938 avec les instructions de configuration DNS"
• "Affichez les informations de l'entreprise pour le domaine d'envoi 3938"
• "Définissez les informations de l'entreprise pour le domaine 3938 à Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
• "Changez la ville des informations de l'entreprise pour le domaine 3938 à New York"

Suppressions :

• "Listez les suppressions pour bounced@example.com"
• "Supprimez bounced@example.com sur le flux transactionnel du domaine 3938"
• "Affichez toutes les adresses e-mail supprimées"
• "Pourquoi user@example.com ne reçoit-il pas mes e-mails ?"
• "Retirez user@example.com de la liste de suppression"

Désinscriptions au suivi :

• "Arrêtez de suivre les ouvertures et les clics pour privacy@example.com sur le domaine 3938"
• "Listez tous ceux qui se sont désinscrits du suivi"

Contacts et listes :

• "Ajoutez john.doe@example.com à ma liste de contacts newsletter"
• "Affichez toutes mes listes de contacts"
• "Créez un champ de contact appelé 'signup_source' pour suivre d'où viennent les contacts"
• "Mettez à jour le contact john.doe@example.com pour définir leur plan sur 'pro'"
• "Importez les contacts de ce CSV dans ma liste d'onboarding"
• "Exportez tous les contacts de ma liste newsletter"
• "Enregistrez un événement 'trial_started' pour le contact john.doe@example.com"

Webhooks :

• "Listez tous les webhooks configurés sur mon compte"
• "Créez un webhook pointant vers https://example.com/hooks/mailtrap pour les événements de rebond et de spam"
• "Mettez à jour le webhook 4821 pour également envoyer les événements de livraison"
• "Supprimez le webhook 4821"

Compte et facturation :

• "Quelle est mon utilisation de facturation actuelle ce mois-ci ?"
• "Combien d'e-mails me reste-t-il dans mon plan ?"
• "Listez tous ceux qui ont accès à ce compte Mailtrap"
• "Affichez les ressources d'autorisation disponibles sur mon compte"

Jetons API :

• "Listez tous les jetons API sur mon compte"
• "Créez un nouveau jeton API pour l'environnement de staging"
• "Réinitialisez le jeton API avec l'ID 1234"
• "Supprimez le jeton API inutilisé 1234"

Organisation et sous-comptes :

• "Listez tous les sous-comptes dans mon organisation"
• "Créez un nouveau sous-compte pour le projet client 'Acme Corp'"

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). 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-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 en copie (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 en copie cachée (BCC) 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) : Texte du corps de l'e-mail. 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 l'analyse. Doit être omise lorsque template_uuid est défini.
• template_uuid (optionnel) : Utilisez 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. Uniquement autorisé 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 requête doit inclure au moins un destinataire via to, cc ou bcc. Même exclusion mutuelle en ligne-vs-modèle que send-email — vérifiée après fusion de la base avec chaque requête.

Paramètres :

• base (facultatif) : Objet avec des champs partagés dans tout le lot.
  • from (facultatif) : Expéditeur en tant que { email, name? } (une simple chaîne d'e-mail est également acceptée à l'exécution). Repli sur DEFAULT_FROM_EMAIL.
  • reply_to (facultatif) : Adresse de réponse.
  • subject / text / html / category (facultatif, mode en ligne) : Contenu par défaut pour chaque demande.
  • template_uuid / template_variables (facultatif, mode modèle) : Modèle par défaut + variables. Mutuellement exclusif avec les champs en ligne.
  • custom_variables (facultatif) : Variables personnalisées par défaut (à valeur de chaîne).
  • headers (facultatif) : En-têtes personnalisés par défaut.
• requests (obligatoire) : Tableau non vide de messages par destinataire. Chaque entrée a :
  • to (facultatif) : Tableau de destinataires en tant qu'objets { email, name? } (les simples chaînes d'e-mail, ou une seule adresse non-tableau, sont également acceptées à l'exécution). Facultatif si cc ou bcc est fourni ; au moins un de to / cc / bcc doit contenir un destinataire.
  • cc, bcc, reply_to (facultatif).
  • Remplacements en ligne (subject/text/html/category) ou modèle (template_uuid/template_variables) ; tout champ omis se replie sur la valeur base correspondante.
  • custom_variables, headers (facultatif).

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 le point de terminaison 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 facultatifs. Utilisez-le pour déboguer les problèmes de livraison depuis l'IDE.

Paramètres :

• search_after (facultatif) : Curseur de pagination depuis le next_page_cursor de la réponse précédente
• sent_after (facultatif) : Date/heure ISO 8601 ; uniquement les journaux envoyés après cette heure
• sent_before (facultatif) : Date/heure ISO 8601 ; uniquement les journaux envoyés avant cette heure
• from_email (facultatif) : Filtrer par e-mail de l'expéditeur ; utiliser avec from_operator (défaut : ci_equal)
• to_email (facultatif) : Filtrer par e-mail du destinataire ; utiliser avec to_operator (défaut : ci_equal)
• status (facultatif) : Filtrer par statut de livraison : delivered, not_delivered, enqueued, opted_out ; utiliser avec status_operator (défaut : equal)
• subject (facultatif) : Filtrer par sujet de l'e-mail ; utiliser avec subject_operator (défaut : ci_contain). Utilisez subject_operator : empty/not_empty pour filtrer par présence de sujet.
• sending_domain_id (facultatif) : Filtrer par ID de domaine d'envoi (nombre) ; utiliser avec sending_domain_id_operator (défaut : equal)
• sending_stream (facultatif) : Filtrer par flux : transactional ou bulk ; utiliser avec sending_stream_operator (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 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

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

get-sending-stats

Obtenez les statistiques d'envoi d'e-mails (taux de livraison, rebond, ouverture, clic, spam) pour une plage de dates. En option, 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 (obligatoire) : Date de début pour la plage de statistiques (AAAA-MM-JJ)
• end_date (obligatoire) : Date de fin pour la plage de statistiques (AAAA-MM-JJ)
• breakdown (facultatif) : Comment ventiler les statistiques : aggregated (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 d'envoi (tableau d'entiers)
• sending_streams (facultatif) : Limiter à transactional et/ou bulk (tableau de chaînes)
• categories (facultatif) : Limiter à ces catégories d'e-mails (tableau de chaînes)
• email_service_providers (facultatif) : Limiter à ces fournisseurs, par ex. Google, Yahoo, Outlook (tableau de chaînes)

create-template

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

Paramètres :

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

list-templates

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

Paramètres :

• Aucun paramètre requis

get-template

Obtient un seul modèle d'e-mail par ID, y compris le sujet, la catégorie et le corps HTML/texte.

Paramètres :

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

update-template

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

Paramètres :

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

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

delete-template

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

Paramètres :

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

send-sandbox-email

Envoie un e-mail à votre boîte de réception de test Mailtrap à des fins de développement et de test. 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 en ligne ou basé sur modèle (template_uuid).

Paramètres :

• test_inbox_id (facultatif) : ID de la boîte de réception de test Mailtrap. Requis sauf si MAILTRAP_TEST_INBOX_ID est défini ; passez par appel pour cibler une boîte de réception spécifique.
• from (facultatif) : Expéditeur en tant que { 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 (facultatif) : Tableau de destinataires en tant qu'objets { email, name? } (les simples chaînes d'e-mail dans le tableau, ou une chaîne séparée par des virgules d'e-mails simples, sont également acceptées à l'exécution). Facultatif si cc ou bcc est fourni ; au moins un de to / cc / bcc doit contenir un destinataire.
• cc (facultatif) : Tableau de destinataires CC en tant qu'objets { email, name? } (les simples chaînes d'e-mail sont également acceptées à l'exécution).
• bcc (facultatif) : Tableau de destinataires BCC en tant qu'objets { email, name? } (les simples chaînes d'e-mail sont également acceptées à l'exécution).
• subject (conditionnel) : Ligne d'objet de l'e-mail. Requis pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• text (conditionnel) : Texte du corps de l'e-mail. Requis (avec ou à la place de html) pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• html (conditionnel) : Version HTML du corps de l'e-mail. Requis (avec ou à la place de text) pour les envois en ligne ; doit être omis lorsque template_uuid est défini.
• category (facultatif) : Catégorie d'e-mail pour le suivi. Doit être omis lorsque template_uuid est défini.
• template_uuid (facultatif) : Utiliser un modèle d'e-mail Mailtrap au lieu du contenu en ligne. Lorsqu'il est défini, subject / text / html / category doit être omis.
• template_variables (facultatif) : Objet de variables substituées dans le modèle référencé par template_uuid. Uniquement autorisé 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 livraison à de vrais destinataires. Même forme base + requests[], validation et règles en ligne-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 (facultatif) : ID de la sandbox Mailtrap (boîte de réception de test). Requis sauf si MAILTRAP_SANDBOX_ID est défini ; passez par appel pour cibler une sandbox spécifique.
• base (facultatif), requests (obligatoire) : 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 par appel en passant test_inbox_id. Les outils prenant sandbox_id utilisent MAILTRAP_SANDBOX_ID en premier.

get-sandbox-messages

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

Paramètres :

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

[!NOTE] Tous les paramètres sont facultatifs. Si aucun n'est fourni, la première page de messages de la boîte de réception sera renvoyée. Utilisez page pour 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 depuis votre boîte de réception de test Mailtrap, y compris le contenu du corps HTML et texte.

Paramètres :

• message_id (obligatoire) : ID du message e-mail sandbox à récupérer

[!NOTE] Utilisez get-sandbox-messages d'abord 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

Obtient un projet sandbox par ID, y compris ses boîtes de réception et les compteurs d'e-mails.

Paramètres :

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

update-sandbox-project

Renomme un projet sandbox existant.

Paramètres :

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

list-sandboxes

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

Paramètres :

• Aucun paramètre requis

mark-sandbox-as-read

Marque tous les messages d'une sandbox comme lus.

Paramètres :

• sandbox_id (obligatoire) : ID de la sandbox sur laquelle agir

reset-sandbox-credentials

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

Paramètres :

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

enable-sandbox-email-address

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

Paramètres :

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

reset-sandbox-email-address

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

Paramètres :

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

forward-sandbox-message

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

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox à transférer
• email (obligatoire) : Adresse e-mail vers laquelle transférer le message

update-sandbox-message

Marque un message de sandbox comme lu ou non lu.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox à mettre à jour
• is_read (obligatoire) : true marque comme lu, false marque comme non lu

delete-sandbox-message

Supprime un seul message de sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox à supprimer

get-sandbox-message-spam-score

Obtient le rapport de spam SpamAssassin pour un message de 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. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-html-analysis

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

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-headers

Obtient les en-têtes de courrier analysés pour un message de sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-html

Obtient le corps HTML rendu d'un message de sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-text

Obtient le corps en texte brut d'un message de sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-raw

Obtient le message brut au format MIME (en-têtes + corps) pour un message de sandbox.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-eml

Obtient le message rendu sous forme de fichier EML (adapté pour joindre à un ticket ou importer dans un autre client de messagerie).

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-message-html-source

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

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

list-sandbox-attachments

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

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de sandbox

get-sandbox-attachment

Obtient les métadonnées et l'URL de téléchargement pour une seule pièce jointe.

Paramètres :

• sandbox_id (facultatif) : ID du sandbox. Utilise MAILTRAP_SANDBOX_ID par défaut.
• message_id (obligatoire) : ID du message de 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

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

Paramètres :

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

create-sending-domain

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

Paramètres :

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

update-sending-domain

Met à jour les paramètres de suivi et de réception d'un domaine d'envoi.

Paramètres :

• sending_domain_id (obligatoire) : ID du domaine d'envoi
• 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 dans les e-mails envoyés depuis ce domaine
• tracking_opt_out_enabled (facultatif) : Ajouter le lien de désinscription 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 le domaine à être attaché à une boîte de réception entrante comme attrape-tout

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

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

get-company-info

Obtient les informations d'entreprise d'un domaine d'envoi, utilisées pour la vérification de conformité du domaine.

Paramètres :

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

create-company-info

Définit les informations d'entreprise d'un domaine d'envoi, requises pour la vérification de conformité du domaine.

Paramètres :

• sending_domain_id (obligatoire) : ID du domaine d'envoi
• 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

Met à jour les informations d'entreprise d'un domaine d'envoi.

Paramètres :

• sending_domain_id (obligatoire) : ID du domaine d'envoi
• Chaque champ de create-company-info, tous facultatifs. Au moins un doit être fourni ; les champs omis restent inchangés.

list-suppressions

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

Paramètres :

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

create-suppression

Ajoute une adresse e-mail à la liste de suppression du compte, afin que Mailtrap cesse de lui livrer des messages.

Paramètres :

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

delete-suppression

Supprime une suppression par ID. Mailtrap reprendra la livraison à 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

Liste les adresses e-mail exclues du suivi des ouvertures et des clics. Renvoie jusqu'à 1000 enregistrements par appel.

Paramètres :

• email (facultatif) : Filtre d'e-mail. Renvoie uniquement les désinscriptions correspondant à cette adresse
• start_time (facultatif) : Uniquement les désinscriptions créées à ou après cette heure (ISO 8601)
• end_time (facultatif) : Uniquement les désinscriptions créées à ou avant cette heure (ISO 8601)
• last_id (facultatif) : Curseur de pagination — le last_id de la réponse précédente

create-tracking-opt-out

Exclut une adresse e-mail du suivi des ouvertures et des clics pour un domaine d'envoi.

Paramètres :

• email (obligatoire) : Adresse e-mail à exclure du suivi
• domain_id (obligatoire) : ID du domaine d'envoi auquel la désinscription s'applique

delete-tracking-opt-out

Retire une adresse e-mail de la liste de désinscription du suivi, afin que le suivi des ouvertures et des clics s'applique à nouveau.

Paramètres :

• tracking_opt_out_id (obligatoire) : ID de la désinscription du suivi à 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

Obtient un seul webhook 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 des webhooks — ce secret n'est renvoyé qu'à la création, alors stockez-le maintenant. Si vous le perdez, recréez le webhook.

Paramètres :

• url (obligatoire) : URL à laquelle Mailtrap enverra les événements de 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

Obtenez 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éez un nouveau 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 inscrire ce contact
• unsubscribed (facultatif, booléen) : Créer le contact avec le statut unsubscribed

update-contact

Mettez à jour un contact existant identifié par ID ou e-mail. list_ids remplace l'ensemble complet des appartenances 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 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 (additif)
• list_ids_excluded (facultatif) : ID des listes à retirer
• unsubscribed (facultatif, booléen) : Définir sur unsubscribed (vrai) ou subscribed (faux)

delete-contact

Supprimez définitivement un contact par ID ou e-mail. Renvoie l'enregistrement du contact supprimé lorsque l'API répond avec celui-ci ; sinon, renvoie une charge utile de confirmation.

Paramètres :

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

create-contact-event

Enregistrez un événement de contact associé à un contact (par ID ou e-mail). Utilisé pour déclencher les 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 nul

list-contact-lists

Listez 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

Obtenez une liste de contacts par ID.

Paramètres :

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

create-contact-list

Créez une nouvelle liste de contacts.

Paramètres :

• name (obligatoire) : Nom de la nouvelle liste

update-contact-list

Renommez 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

Supprimez définitivement une liste de contacts par ID.

Paramètres :

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

list-contact-fields

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

Paramètres :

• Aucun paramètre requis

get-contact-field

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

Paramètres :

• field_id (obligatoire) : ID du champ de contact

create-contact-field

Créez 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) : L'un des text, number, boolean, date

update-contact-field

Mettez à 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 des text, number, boolean, date

delete-contact-field

Supprimez 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

Importez 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 contacts. Chaque entrée nécessite :
  • 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

Obtenez 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

Exportez 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 possède :
  • name (obligatoire) : Champ sur lequel filtrer (list_id, subscription_status, email, etc.)
  • operator (obligatoire) : L'un des 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

Obtenez 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-email-campaigns

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

Paramètres :

• token (facultatif) : Numéro de page à récupérer (pagination par jeton de page). Par défaut 1
• per_page (facultatif) : Nombre de campagnes par page. Par défaut 50, maximum 100
• search (facultatif) : Filtrer les campagnes par nom (correspondance partielle insensible à la casse)

get-email-campaign

Obtenez une campagne e-mail par ID.

Paramètres :

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

create-email-campaign

Créez une nouvelle campagne e-mail. La campagne est toujours créée dans l'état draft ; la planification et le démarrage sont des outils distincts (schedule-email-campaign, start-email-campaign).

Paramètres :

• name (obligatoire) : Nom de la campagne
• domain_id (obligatoire) : ID du domaine d'envoi vérifié utilisé pour la campagne, tel que renvoyé par les points de terminaison des domaines d'envoi
• from_local_part (obligatoire) : Partie locale (avant le @) de l'adresse de l'expéditeur
• template_attributes (obligatoire) : Modèle e-mail intégré. Possède :
  • subject (obligatoire) : Objet de l'e-mail (255 caractères max). Prend en charge les balises de fusion, par ex. Hi {{first_name}}
  • body_html (facultatif) : Corps HTML (la conception). Requis avant que la campagne puisse être planifiée ou démarrée. Incluez un lien de désabonnement via une ancre dont le href contient l'espace réservé __unsubscribe_url__
  • body_text (facultatif) : Alternative en texte brut du corps de l'e-mail
  • merge_tags (facultatif) : Noms nus des balises de fusion référencées dans l'objet/corps, par ex. ["first_name"]
• from_display_name (facultatif) : Nom d'affichage affiché dans l'en-tête De
• reply_to (facultatif) : Parties de l'adresse de réponse (display_name, local_part, domain)
• delivery_mode (facultatif) : rapid (envoyer aussi vite que possible) ou gradual (limiter à delivery_options.emails_per_hour)
• delivery_options (facultatif) : Options de limitation du débit de livraison (emails_per_hour)
• contact_list_ids (facultatif) : ID des listes de contacts auxquelles envoyer (traitées comme l'ensemble complet des listes incluses)
• contact_segment_ids (facultatif) : ID des segments de contacts auxquels envoyer (traités comme l'ensemble complet des segments inclus)

update-email-campaign

Mettez à jour une campagne e-mail draft. Seuls les champs fournis changent ; 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 à 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

Supprimez une campagne e-mail par ID. Seule une campagne dans l'état draft peut être supprimée.

Paramètres :

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

start-email-campaign

Commencez 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 d'envoi vérifié doivent être définis.

Paramètres :

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

schedule-email-campaign

Planifiez une campagne e-mail draft pour commencer l'envoi à une heure future. Seules les campagnes draft peuvent être planifiées.

Paramètres :

• email_campaign_id (obligatoire) : ID de la campagne e-mail à planifier
• datetime (obligatoire) : Quand envoyer la campagne (ISO 8601). Doit être dans le futur et au plus 1 mois à l'avance

cancel-email-campaign

Annulez une campagne e-mail scheduled, la ramenant à 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

Terminez une campagne e-mail actuellement en cours d'envoi (started, queued ou paused), interrompant l'envoi en cours.

Paramètres :

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

reset-email-campaign

Réinitialisez une campagne e-mail scheduled à 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

Obtenez les statistiques de performance agrégées pour une campagne e-mail (compteurs et taux pour les livraisons, ouvertures, clics, rebonds, plaintes pour spam et désabonnements).

Paramètres :

• email_campaign_id (obligatoire) : ID de la campagne e-mail
• start_date (facultatif) : Début de la fenêtre d'agrégation (inclusif), YYYY-MM-DD. Par défaut le jour où la campagne a été démarrée pour la dernière fois
• end_date (facultatif) : Fin de la fenêtre d'agrégation (inclusive), YYYY-MM-DD. Par défaut la date actuelle

list-accounts

Listez 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

Obtenez l'utilisation du cycle de facturation actuel pour le compte : plans d'envoi et de test, limites et compteurs actuels.

Paramètres :

• Aucun paramètre requis

list-account-accesses

Listez 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 les autorisations 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

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

Paramètres :

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

get-permission-resources

Obtenez 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éez, mettez à jour ou supprimez en masse les permissions pour un accès de compte unique. Les paires (resource_type, resource_id) existantes sont mises à jour ; les nouvelles sont créées. Définissez destroy: true sur une entrée pour la supprimer.

Paramètres :

• account_access_id (obligatoire) : ID de l'accès au compte cible
• permissions (obligatoire) : Tableau d'entrées de permission. Chacune contient :
  • resource_id (obligatoire) : ID de la ressource (nombre ou chaîne)
  • resource_type (obligatoire) : Une des valeurs account, project, inbox, domain, billing
  • access_level (facultatif) : admin/100 ou viewer/10
  • destroy (facultatif, booléen) : Lorsqu'il est défini sur true, supprime cette permission au lieu de la créer ou de 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 où 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
• expires_at (facultatif) : Expiration du jeton au format date-heure ISO 8601. Omettez pour utiliser la valeur par défaut du serveur (1 an) ; passez une valeur explicite null pour un jeton qui n'expire jamais. Les valeurs passées ou les valeurs de plus de 5 ans sont rejetées
• resources (facultatif) : Tableau de permissions de ressources pour limiter le jeton. Chaque entrée contient :
  • resource_type (obligatoire) : Une des valeurs 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 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 ID. La réponse inclut la nouvelle valeur secrète token — renvoyée uniquement lors de cet appel, alors stockez-la immédiatement. Le jeton précédent est invalidé.

Paramètres :

• api_token_id (obligatoire) : ID du jeton API à réinitialiser
• expires_at (facultatif) : Expiration du nouveau jeton au format date-heure ISO 8601. Omettez pour utiliser la valeur par défaut du serveur (1 an) ; passez une valeur explicite null pour un jeton qui n'expire jamais. Les valeurs passées ou les valeurs de plus de 5 ans sont rejetées

delete-api-token

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

Paramètres :

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

list-sub-accounts

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

Paramètres :

• Aucun paramètre requis

create-sub-account

Crée un nouveau sous-compte sous 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 unique par 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 unique par 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) : Attacher à un domaine d'envoi personnalisé (boîte de réception fourre-tout). Omettez pour une boîte de réception 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 un indice 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 unique 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 (envoie à l'expéditeur d'origine). Envoie un véritable e-mail. Les adresses acceptent une chaîne d'e-mail simple 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 de réception hébergées par Mailtrap ; requis pour les boîtes de réception à 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 de valeurs de chaîne

reply-all-to-inbound-message

Répond à un message entrant et copie les autres destinataires de l'original. 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 (chaîne d'e-mail simple 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 dans une boîte de réception entrante (pagination par curseur). Renvoie un résumé formaté avec un indice 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 unique 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

2. Installez les dépendances :

npm install

Configuration avec Claude Desktop ou Cursor

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

Ajoutez la configuration suivante :

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "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] 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_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Tests

Exécution des 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 que le bundle soit d'abord construit :

npm run build

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

Interface navigateur

npm run dev

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

CLI

Pour des appels ponctuels sans l'interface, utilisez npm run mcp:cli. Passez les indicateurs CLI de l'Inspector après -- afin que npm les transmette tels quels :

# 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 alignée sur les conventions MCP :

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

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

Sécurité

• Entrées validées via les schémas Zod
• Variables d'environnement gérées de manière sécurisée
• Protection contre les délais d'expiration sur les opérations (30 secondes)
• Détails sensibles nettoyés dans la sortie 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 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")'

Dépannage

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 d'expiration : vérifiez la connectivité réseau et le statut de l'API Mailtrap
4. Erreurs de validation : assurez-vous que tous les champs 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 sous les termes de la licence MIT.

Code de conduite

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