subagent-python

Le SDK Python de Subagent Mail : des boîtes mail pour agents IA. Votre agent crée sa boîte, écrit, lit ses fils et répond avec sa propre adresse. Le serveur applique les règles d'envoi : montée progressive, créneaux, validation humaine, désinscription.

• Une méthode par opération du serveur (64), mêmes noms et mêmes arguments que les outils du MCP.
• Aucune dépendance : bibliothèque standard seulement, Python 3.9 ou plus.
• Typé : arguments et résultats sont tirés des schémas du serveur.
• Généré depuis le registre d'opérations du serveur, jamais écrit à la main.

Installer

pip install subagent-mail

Démarrer

1. Une clé

Sans clé, une seule opération est ouverte : sign_up. Elle rend une clé, affichée une seule fois, et une boîte sur subagentmail.fr. Votre humain reçoit un code à 6 chiffres par e-mail ; verify ouvre l'envoi.

from subagent_mail import Subagent

client = Subagent()  # lit SUBAGENT_KEY ; sans clé, seule sign_up est ouverte

inscription = client.sign_up(username="atelier-exemple", human_email="marie@exemple.fr")
print(inscription["api_key"])           # affichée une seule fois : rangez-la
print(inscription["inbox"]["address"])  # atelier-exemple@subagentmail.fr

client.verify(otp_code="482913")        # le code reçu par votre humain

Vous avez déjà une clé ? Rangez-la hors du code, le client la lit seul :

export SUBAGENT_KEY="sak_…"

2. Où en est la boîte

inbox_status est le point de départ de toute session : l'espace, les permissions de la clé, le créneau d'envoi, et pour chaque boîte son quota du jour.

etat = client.inbox_status()
boite = etat["inboxes"][0]
print(boite["address"], boite["quota"]["remaining_today"])

3. Un premier envoi

Un envoi de test ne part qu'à l'humain de l'espace ou à une autre de ses boîtes : remplacez l'adresse par la vôtre.

envoi = client.send_email(
    inbox_id=boite["id"],
    to="marie@exemple.fr",
    subject="Premier message",
    text="Bonjour Marie,\n\nCeci est mon premier message.\n",
    test=True,                            # à soi-même seulement
    requires_approval=True,               # reste en brouillon jusqu'à la validation d'un humain
    idempotency_key="premier-message-1",  # rejouer cet appel ne crée pas de doublon
)
print(envoi["message"]["status"])  # draft

Sans requires_approval, le message entre en file et part dans le créneau d'envoi, selon le quota du jour de la boîte. estimated_send_at donne l'heure de départ au plus tôt. Un message en file n'est pas une erreur : ne le renvoyez pas.

Les opérations

Arguments, résultats et un exemple par méthode : reference.md. Sur le site : documentation · openapi.json · llms.txt.

Les résultats sont des dictionnaires typés (TypedDict) : envoi["message"]["id"]. Le serveur peut ajouter des champs : un champ inconnu ne casse rien.

Quand le serveur refuse

Un refus n'est pas une panne. Il lève SubagentError, qui porte un code stable, un message en français et une piste (hint) qui dit quoi faire. La piste se suit, elle ne se contourne pas.

from subagent_mail import SubagentError

try:
    client.approve_message(message_id=envoi["message"]["id"])
except SubagentError as refus:
    print(refus.code)     # forbidden : la clé d'un agent ne porte pas approve
    print(refus.message)  # la phrase du serveur, en français
    print(refus.hint)     # ce qu'il faut faire
    print(refus.status)   # 403

Un agent ne valide jamais son propre brouillon : approve_message demande la permission approve, que la clé rendue par sign_up ne porte pas.

Les refus les plus courants :

Tous les codes (84) : reference.md, ou subagent_mail.CODES.

SubagentConnectionError est l'autre cas : le serveur n'a pas répondu (réseau, délai dépassé). Rien ne dit alors si l'appel a abouti.

Idempotence

Passez une idempotency_key à chaque envoi qu'un agent pourrait rejouer. Elle part dans l'en-tête Idempotency-Key.

premier = client.send_email(
    inbox_id=boite["id"], to="marie@exemple.fr", subject="Compte rendu", text="Bonjour Marie, …",
    test=True, idempotency_key="compte-rendu-12-octobre",
)
second = client.send_email(
    inbox_id=boite["id"], to="marie@exemple.fr", subject="Compte rendu", text="Bonjour Marie, …",
    test=True, idempotency_key="compte-rendu-12-octobre",
)
print(second["replayed"])  # True : rien de nouveau n'a été créé

Même clé, même contenu : le message déjà créé, avec replayed à vrai. Même clé, autre contenu : refus idempotency_conflict.

Le client ne réessaie seul que ce qui se rejoue sans risque : une lecture, ou un envoi qui porte une idempotency_key, et seulement quand le serveur n'a pas répondu. Un refus n'est jamais réessayé.

Asynchrone

AsyncSubagent a les mêmes méthodes, à attendre avec await.

import asyncio
from subagent_mail import AsyncSubagent

async def reponses_a_traiter():
    client = AsyncSubagent()
    fils = await client.list_threads(status="replied")
    return fils["items"]

print(asyncio.run(reponses_a_traiter()))

Réglages

Une opération plus récente que ce SDK s'appelle par son nom : client.call("nom", {"argument": "valeur"}).

Tests

Les tests tournent contre un faux serveur local, généré depuis le même registre : il contrôle la clé, les permissions et chaque argument contre le schéma, et n'envoie rien.

python -m unittest discover -s tests

Pour essayer un script à la main sans toucher au service :

python tests/faux_serveur.py   # http://127.0.0.1:8787, clé sak_exemple_agent

Contribuer

Ce dépôt est généré depuis le registre d'opérations du serveur : une modification faite ici à la main serait écrasée à la génération suivante. Ouvrez un ticket plutôt qu'une demande de fusion.

Licence

MIT. Le serveur Subagent, lui, n'est pas ouvert : ces clients ne servent qu'avec une clé Subagent.