Documentation

Votre agent a une boîte de réception
en quatre étapes.

Connectez n'importe quel compte e-mail, collez une URL dans un client MCP compatible OAuth et autorisez. Les clients sans OAuth utilisent plutôt une clé API. Référence complète des outils et guide de connexion ci-dessous.

Démarrage rapide OAuth (claude.ai)Référence des outils Fournisseurs pris en charge

Démarrage rapide

Opérationnel en quelques minutes.

Aucun SDK requis. MCPEmails parle le MCP standard via HTTP, donc il s'intègre dans tout agent compatible MCP.

01Inscrivez-vous et connectez une boîte

Créez votre compte et connectez Gmail

Inscrivez-vous sur mcpemails.com, puis allez dans Tableau de bord → Boîtes → Connecter une boîte. Choisissez Gmail, Outlook, iCloud, Fastmail ou toute boîte IMAP, puis effectuez le flux OAuth ou collez un mot de passe d'application. Votre boîte est prête en moins d'une minute.

Connecter votre boîte →

02Créez une clé API

Générez un jeton bearer pour votre agent

Dans Tableau de bord → Clés API, cliquez sur « Créer une clé ». Nommez-la, sélectionnez les portées dont votre agent a besoin (read:email et/ou send:email), et copiez la clé. Elle n'est affichée qu'une seule fois.

# Your key looks like this:
mcpe_live_AbCdEfGhIjKlMnOpQrStUvWxYz123456

03Ajoutez MCPEmails à votre agent

Collez le point de terminaison MCP dans votre client

Choisissez l'onglet de votre client ci-dessous. Les clients MCP qui prennent en charge OAuth 2.0 (claude.ai, Claude Desktop, Cursor et autres) n'ont qu'à coller l'URL et autoriser, aucune clé API nécessaire. Les clients sans OAuth, ainsi que l'accès par script, utilisent la clé API de l'étape 02.

json

# OAuth-capable clients (claude.ai, Claude Desktop, Cursor…)
# No API key required. Paste the URL, click Connect, authorize.
#
# Example: claude.ai
#   1. Go to claude.ai → Customize → Connectors
#   2. Click "Add connector" and paste this URL:
#
#        https://www.mcpemails.com/api/mcp
#
#   3. Click Connect and sign in with your mcpemails account.
#   4. All six tools are live immediately.
#
# Claude Desktop and Cursor follow the same OAuth flow when
# the server URL is configured in their MCP settings.

04Effectuez votre premier appel

Demandez à votre agent de vérifier votre boîte de réception

Aucun copier-coller d'UUID de boîte. Votre agent appelle d'abord list_inboxes pour découvrir chaque boîte connectée et son UUID, puis vous demandez : « Vérifie ma boîte et résume les 5 derniers messages non lus. »

# The agent calls list_inboxes first, so no hardcoded UUIDs.
# System prompt (optional, for multi-inbox setups):
You have access to email via MCPEmails.
Start by calling list_inboxes to discover available inboxes.

Point de terminaison

Une URL, MCP standard.

Tout le trafic passe par un unique point de terminaison Streamable HTTP. Authentifiez-vous avec un jeton bearer issu de votre tableau de bord.

POSThttps://www.mcpemails.com/api/mcp

Envoyez un corps de requête JSON-RPC 2.0. Méthodes prises en charge : initialize, tools/list, tools/call.

Transport : Streamable HTTP (MCP 2025-06-18)

Auth : Authorization: Bearer <api-key>

Limites de débit : 100 req/min · 1 000/h · 10 000/jour par clé

Format de réponse : JSON-RPC 2.0

Handshake d'initialisation

bash

curl -X POST https://www.mcpemails.com/api/mcp \
  -H "Authorization: Bearer mcpe_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": { "name": "my-agent", "version": "1.0" },
      "capabilities": {}
    }
  }'

Connexion OAuth

Zéro configuration pour les clients compatibles OAuth.

Les clients MCP qui prennent en charge OAuth 2.0 (claude.ai, Claude Desktop, Cursor et autres) se connectent automatiquement via le code d'autorisation + PKCE. Aucune clé API, aucun fichier de configuration. Collez l'URL et cliquez sur Connecter.

Étape 1 : Allez dans claude.ai → Customize → Connectors → Add connector

Étape 2 : Collez https://www.mcpemails.com/api/mcp comme URL du serveur

Étape 3 : Cliquez sur Connect. MCPEmails ouvre un écran d'autorisation

Étape 4 : Connectez-vous avec votre compte mcpemails et approuvez l'accès

Terminé : Les six outils sont actifs. claude.ai renouvelle les jetons automatiquement

Comment ça fonctionne en coulisses

claude.ai s'enregistre via RFC 7591 Dynamic Client Registration, donc vous ne préenregistrez jamais d'ID client.

L'autorisation utilise OAuth 2.0 Authorization Code + PKCE (RFC 7636), donc aucun secret client n'est jamais transmis.

Les jetons sont limités exactement aux autorisations que vous approuvez : read:email et/ou send:email.

Vous utilisez un client sans prise en charge d'OAuth ? Créez une clé API dans Tableau de bord → Clés API et passez-la comme jeton bearer. Les connexions par clé API et par OAuth utilisent le même point de terminaison MCP et les mêmes six outils.

Référence des outils

Six outils. Toutes les opérations e-mail dont votre agent a besoin.

Commencez par list_inboxes pour découvrir les boîtes disponibles et leurs UUID. Les cinq autres outils prennent chacun un inbox_id renvoyé par cet appel. Cliquez sur « Afficher l'exemple » pour voir une requête et une réponse complètes.

list_inboxesread:email list_inboxread:email read_emailread:email search_emailsread:email send_emailsend:email reply_to_emailsend:email

list_inboxesread:email

Renvoie toutes les boîtes auxquelles la clé API ou le jeton OAuth actuel peut accéder. Appelez ceci en premier pour découvrir les valeurs inbox_id, afin de ne jamais copier-coller d'UUID depuis le tableau de bord.

Aucun paramètre. Appelez avec un objet d'arguments vide : {}

list_inboxread:email

Listez les résumés des e-mails d'une boîte connectée, du plus récent au plus ancien. Prend en charge la pagination, la sélection de dossier et le filtrage des non lus.

Paramètre	Type	Requis	Description
`inbox_id`	string (uuid)	requis	UUID de la boîte à lister. Appelez d'abord list_inboxes pour découvrir les ID de boîtes disponibles.
`limit`	integer	optionnel	Nombre maximal de résultats à renvoyer. Par défaut 20, max 100.
`offset`	integer	optionnel	Décalage de pagination basé sur zéro. Par défaut 0.
`folder`	string	optionnel	Dossier à lister. Par défaut « INBOX ». Autres valeurs : « SENT », « DRAFTS », « TRASH ».
`unread_only`	boolean	optionnel	Renvoyer uniquement les messages non lus. Par défaut false.

read_emailread:email

Récupérez le contenu complet d'un e-mail unique par ID, y compris le corps en texte brut, le HTML assaini optionnel et les données de pièces jointes optionnelles.

Paramètre	Type	Requis	Description
`inbox_id`	string (uuid)	requis	UUID de la boîte contenant l'e-mail. Appelez list_inboxes pour obtenir les ID de boîtes disponibles.
`message_id`	string	requis	ID de message du fournisseur depuis list_inbox ou search_emails.
`include_html`	boolean	optionnel	Inclure le corps HTML assaini. Par défaut false.
`include_attachments`	boolean	optionnel	Inclure les données de pièces jointes en base64. Par défaut false.
`mark_as_read`	boolean	optionnel	Marquer le message comme lu après récupération. Par défaut false.

search_emailsread:email

Recherchez dans une boîte en utilisant la syntaxe de requête native du fournisseur. Gmail prend en charge les opérateurs de recherche Gmail ; Outlook utilise $search ; les boîtes Fastmail et IMAP utilisent la recherche textuelle.

Paramètre	Type	Requis	Description
`inbox_id`	string (uuid)	requis	UUID de la boîte où rechercher. Appelez list_inboxes pour obtenir les ID de boîtes disponibles.
`query`	string	requis	Requête de recherche. Pour Gmail : « from:alice@example.com after:2026/01/01 ». Pour Outlook : requêtes en langage naturel ou KQL.
`limit`	integer	optionnel	Nombre maximal de résultats. Par défaut 20, max 100.
`offset`	integer	optionnel	Décalage de pagination. Par défaut 0.
`include_folders`	array	optionnel	Restreindre la recherche à ces noms de dossiers. Par défaut : rechercher dans tous les dossiers.

send_emailsend:email

Envoyez un nouvel e-mail depuis une boîte connectée. Prend en charge le texte brut, un corps HTML optionnel, CC/BCC et les pièces jointes (jusqu'à 10 Mo au total).

Paramètre	Type	Requis	Description
`inbox_id`	string (uuid)	requis	UUID de la boîte d'envoi. Appelez list_inboxes pour obtenir les ID de boîtes disponibles.
`to`	array[string]	requis	Adresses e-mail des destinataires. Max 50.
`subject`	string	requis	Objet de l'e-mail. Max 998 caractères.
`body`	string	requis	Corps de l'e-mail en texte brut.
`cc`	array[string]	optionnel	Destinataires en CC. Par défaut [].
`bcc`	array[string]	optionnel	Destinataires en BCC. Par défaut [].
`html_body`	string	optionnel	Version HTML du corps (multipart/alternative). L'appelant est responsable du HTML sûr.
`reply_to`	string	optionnel	Adresse de l'en-tête Reply-To.
`attachments`	array	optionnel	Pièces jointes. Chaque élément : { filename, mime_type, data (base64) }. Max 20 éléments, 10 Mo au total.

reply_to_emailsend:email

Envoyez une réponse à un e-mail existant. Les en-têtes de threading (In-Reply-To, References) sont définis automatiquement. Prend en charge la réponse à tous et les pièces jointes.

Paramètre	Type	Requis	Description
`inbox_id`	string (uuid)	requis	UUID de la boîte qui contient le message d'origine. Appelez list_inboxes pour obtenir les ID de boîtes disponibles.
`message_id`	string	requis	ID de message du fournisseur de l'e-mail auquel on répond.
`body`	string	requis	Corps de la réponse en texte brut.
`html_body`	string	optionnel	Version HTML optionnelle de la réponse.
`reply_all`	boolean	optionnel	Répondre à tous les destinataires d'origine (To + Cc). Par défaut false.
`attachments`	array	optionnel	Pièces jointes. Même schéma que send_email. Max 20 éléments.

Codes d'erreur

Codes d'erreur et conseils de réessai.

Les échecs d'authentification, de portée et de limite de débit renvoient un objet error JSON-RPC avec un code numérique. Les échecs d'exécution d'outil (boîte introuvable, erreur du fournisseur, etc.) renvoient un result normal avec isError: true et un message lisible dans content[0].text.

Code	Type	Quand cela survient	Réessayable
`-32001`	JSON-RPC error	Clé API manquante, mal formée, révoquée ou expirée. Également renvoyé lorsque la clé API n'a pas la portée requise pour l'outil appelé.	Non
`-32601`	JSON-RPC error	Méthode JSON-RPC inconnue (par ex. appel d'une méthode autre qu'initialize, tools/list, tools/call)	Non
`-32602`	JSON-RPC error	Nom d'outil inconnu, ou paramètre manquant / invalide dans tools/call	Non
`-32029`	JSON-RPC error	Limite de débit par clé ou quota quotidien de la formule dépassé. Vérifiez data.error_code : « rate_limit_exceeded » contre « quota_exceeded ». Vérifiez data.retry_after (secondes) avant de réessayer.
`isError: true`	Tool result	L'outil s'est exécuté mais a rencontré une erreur (boîte introuvable, message introuvable, échec d'authentification du fournisseur, destinataire invalide, pièce jointe trop volumineuse, fournisseur 5xx). La description de l'erreur se trouve dans content[0].text.	Non

Exemple de réponse d'erreur d'exécution

json

// Tool execution error: inbox not found
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Inbox not found or not accessible." }],
    "isError": true
  }
}

// Rate limit error: JSON-RPC error object with data
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded",
    "data": {
      "error_code": "rate_limit_exceeded",
      "window": "per_minute",
      "limit": 100,
      "used": 100,
      "retry_after": 34
    }
  }
}

Limites de débit

Limites de débit et quotas.

Fenêtres glissantes par clé

100 req / min · 1 000 / h · 10 000 / jour

Appliqué par clé API quelle que soit la formule. En cas de dépassement, le serveur renvoie le code d'erreur -32029 avec data.error_code: "rate_limit_exceeded" et un champ data.retry_after (secondes). Respectez cette valeur avant de réessayer.

Plafond par minute de la formule

Gratuit 60 / min · Solo 300 / min · Team 1 000 / min

L'usage est illimité ; il s'agit d'une limite de pointe d'usage équitable par espace de travail (agrégée sur toutes vos clés API). En cas de dépassement, les appels renvoient data.error_code: "rate_limit_exceeded" avec data.window: "per_minute" et un compte à rebours data.retry_after (secondes). Passez à une formule supérieure pour un plafond plus élevé.

Réessayer en toute sécurité

Respectez toujours retry_after ; ne réessayez jamais les envois à l'aveugle

Pour les erreurs rate_limit_exceeded, attendez data.retry_after secondes avant de réessayer. Utilisez un backoff exponentiel pour provider_error. Ne réessayez pas automatiquement send_email en cas de provider_error, car le message a peut-être déjà été accepté par le fournisseur.

Prêt à connecter votre boîte de réception ?

Commencez avec la formule Gratuit : illimitée, aucune carte requise. Passez à Solo ou Team pour des limites de pointe plus élevées et des fonctionnalités d'équipe.

Commencer gratuitement Voir les tarifs

Votre agent a une boîte de réceptionen quatre étapes.