AgenticEmail : email pour agents IA
AgenticEmail donne à un agent une véritable boîte mail adressable qu'il possède. Contrairement à une API d'envoi sortant uniquement, chaque boîte envoie et reçoit : les courriels entrants arrivent sous forme de JSON parsé via un webhook ou un flux WebSocket. Utilisez cette compétence dès qu'un agent doit être joignable par email, et pas seulement capable d'envoyer.
Déclencheurs courants : l'agent doit s'inscrire à un service tiers, recevoir un code de vérification ou OTP, être notifié par email, exécuter un workflow de support ou de prospection, ou échanger des emails avec un humain ou un autre agent.
Configuration
- Obtenez une clé API (elle commence par
am_) sur https://app.agenticemail.dev. Le niveau gratuit inclut de vraies boîtes, l'envoi, la réception et les webhooks. - Exportez-la :
export AGENTICEMAIL_API_KEY=am_... - Choisissez une voie d'intégration ci-dessous. Toutes utilisent
https://api.agenticemail.dev.
Choisissez une voie
- Serveur MCP hébergé (recommandé pour les agents compatibles MCP comme Claude, Cursor et Vercel AI SDK). Connectez
https://api.agenticemail.dev/mcpavec la clé API comme jeton Bearer. L'agent a alors accès directement à ces outils :create_inbox,list_inboxes,list_threads,get_thread,list_messages,get_message,send_message,reply_to_message. - CLI (
npm i -g agenticemail-cli), pour les agents pilotés par le shell. - SDK (
npm i agenticemailpour TypeScript, oupip install 'agenticemail[e2e]'pour Python), pour le code.
Configuration client MCP
Clients HTTP natifs (Claude, Cursor et autres compatibles HTTP streamable) :
{
"mcpServers": {
"agenticemail": {
"type": "http",
"url": "https://api.agenticemail.dev/mcp",
"headers": { "Authorization": "Bearer ${AGENTICEMAIL_API_KEY}" }
}
}
}
Client uniquement Stdio, faire un pont :
npx mcp-remote https://api.agenticemail.dev/mcp \
--header "Authorization: Bearer $AGENTICEMAIL_API_KEY"
Flux principal : créer, envoyer, recevoir, répondre
CLI :
INBOX=$(agenticemail inboxes create --username assistant | jq -r .id)
agenticemail messages send "$INBOX" --to [email protected] \
--subject "Bonjour" --text "Envoyé par un agent."
agenticemail messages list "$INBOX" --limit 5
agenticemail messages reply "$INBOX" <msgId> --text "Je m'en occupe."
agenticemail wait-for-message "$INBOX" --timeout 300
SDK TypeScript :
import { AgenticEmail } from "agenticemail";
const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });
const inbox = await client.inboxes.create({ username: "assistant" });
await client.messages.send(inbox.id, {
to: ["[email protected]"],
subject: "Bonjour",
text: "Envoyé par un agent.",
});
const { data } = await client.messages.list(inbox.id, { limit: 5 });
const msg = await client.messages.get(inbox.id, data[0].id);
await client.messages.reply(inbox.id, msg.id, { text: "Merci." });
SDK Python :
from agenticemail import AgenticEmail
client = AgenticEmail(api_key=os.environ["AGENTICEMAIL_API_KEY"])
inbox = client.inboxes.create(username="assistant")
client.messages.send(inbox.id, to=["[email protected]"], subject="Bonjour", text="...")
for m in client.messages.list(inbox.id, limit=5).data:
print(m.subject)
REST (si vous n'utilisez pas de SDK)
URL de base https://api.agenticemail.dev, en-tête Authorization: Bearer $AGENTICEMAIL_API_KEY.
| Méthode | Chemin | Objectif |
|---|---|---|
| POST | /v1/inboxes | Créer une boîte. Corps { "username": "assistant" } (optionnel). |
| GET | /v1/inboxes | Lister les boîtes. |
| POST | /v1/inboxes/{id}/messages | Envoyer. Corps { "to": ["[email protected]"], "subject": "...", "text": "..." }. |
| GET | /v1/inboxes/{id}/messages | Lister. Paramètres limit, cursor. |
| GET | /v1/inboxes/{id}/messages/{msgId} | Obtenir un message parsé. |
| POST | /v1/inboxes/{id}/messages/{msgId}/reply | Répondre dans le fil. |
| POST | /v1/webhooks | Enregistrer un webhook. Corps { "url": "...", "eventTypes": ["message.received"] }. |
Chaque objet message possède un booléen encrypted pour que le client sache s'il faut déchiffrer.
Réception des courriels entrants
Enregistrez un webhook pour que les nouveaux courriels atteignent l'agent dès leur arrivée :
agenticemail webhooks create --url https://votre-app/hook \
--event-types message.received
Chaque événement contient l'expéditeur parsé, le sujet, le texte, le HTML et les pièces jointes. Un flux WebSocket est disponible pour les mêmes événements si l'agent est déjà en cours d'exécution (agenticemail events tail).
Chiffrement de bout en bout (optionnel)
Pour les courriels d'agent à agent, AgenticEmail propose un chiffrement de bout en bout optionnel : la clé privée est générée et conservée côté client (SDK ou CLI), jamais sur le serveur, donc la plateforme ne peut pas lire le contenu. Activez-le dans le CLI avec agenticemail keys generate <inbox> puis agenticemail keys publish <inbox>, après quoi messages send et messages get chiffrent et déchiffrent automatiquement. Dans le SDK, passez une identité e2e lors de la construction du client :
import { AgenticEmail, generateIdentity } from "agenticemail";
const client = new AgenticEmail({
apiKey: process.env.AGENTICEMAIL_API_KEY!,
e2e: { identity: generateIdentity(), autoPublish: true },
});
Ce qu'il fait et ne fait pas, honnêtement :
- Il est optionnel et ne fonctionne qu'entre deux boîtes AgenticEmail qui ont chacune publié une clé. Le texte brut est le comportement par défaut.
- La clé privée est côté client uniquement et n'atteint jamais le serveur, donc ni la plateforme ni son fournisseur de cloud ne peuvent lire le contenu chiffré.
- Un envoi vers une adresse externe (Gmail, serveur d'entreprise) revient au texte brut, car il n'y a pas de clé publiée à laquelle chiffrer.
- Les métadonnées de routage (De, À, heure, taille) restent visibles, comme SMTP l'exige.
- Perdez la clé privée et les anciens courriels chiffrés deviennent irrécupérables. C'est le coût du fait que le serveur ne la détient jamais.
Documentation
Documentation complète : https://agenticemail.dev/docs