Automatiser ses emails avec Python et l'API Gmail en 2026

Vous allez automatiser l'envoi et la lecture d'emails Gmail avec Python et la Gmail API v1 en 20 minutes, en utilisant google-api-python-client 2.196.0 et OAuth 2.0. Licence Apache 2.0 — gratuit. Documentation officielle Gmail API Python.

Ce que vous allez construire et pourquoi en 2026

Un script Python qui se connecte à votre boîte Gmail via OAuth 2.0, lit les messages non lus, envoie des emails automatiques et classe les messages par label. Prérequis : Python 3.10+ installé (python3 --version pour vérifier), un compte Google, 8 Go RAM minimum. Temps estimé : 20 minutes sur macOS/Linux, 30 minutes sur Windows. La Gmail API offre 1 milliard de requêtes/jour gratuitement — de quoi automatiser des dizaines de milliers d'emails.

Installation : commandes exactes à copier

mkdir gmail-automate && cd gmail-automate
python3 -m venv venv
source venv/bin/activate # Windows: venvScriptsactivate
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Résultat attendu : Successfully installed google-api-python-client-2.196.0 google-auth-httplib2-0.2.0 google-auth-oauthlib-1.2.1. Erreur courante : error: externally-managed-environment sur Ubuntu 24.04 → utiliser le venv comme indiqué ci-dessus, ou pip install --break-system-packages (non recommandé).

Configuration : les fichiers et variables à définir

1. Aller sur Google Cloud Console → Créer un projet → Activer la Gmail API.

2. Menu → Google Auth platform → Branding : nommer l'application, ajouter un email de support, sélectionner le type Interne si vous avez un domaine Google Workspace, sinon Externe.

3. Menu → Google Auth platform → Clients → Create Client → type Application de bureau → télécharger le fichier JSON → renommer en credentials.json et le placer à la racine du projet.

4. Ajouter credentials.json et token.json au fichier .gitignore — ces fichiers contiennent des secrets OAuth, ne jamais les committer.

Le code du projet : construire la fonctionnalité principale

Créer gmail_auto.py :

import os.path
import base64
from email.mime.text import MIMEText
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError # Scopes : lecture + envoi + modification des labels
SCOPES = [ "https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.send", "https://www.googleapis.com/auth/gmail.modify",
] def get_credentials(): """Authentifier via OAuth 2.0 et retourner les credentials.""" creds = None if os.path.exists("token.json"): creds = Credentials.from_authorized_user_file("token.json", SCOPES) if not creds or not creds.valid: if creds and creds.expired and creds.refresh_token: creds.refresh(Request()) else: flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES) creds = flow.run_local_server(port=0) with open("token.json", "w") as token: token.write(creds.to_json()) return creds def list_unread_emails(service, max_results=10): """Lister les emails non lus.""" results = service.users().messages().list( userId="me", labelIds=["INBOX", "UNREAD"], maxResults=max_results ).execute() messages = results.get("messages", []) if not messages: print("Aucun email non lu.") return [] for msg in messages: msg_detail = service.users().messages().get(userId="me", id=msg["id"], format="metadata", metadataHeaders=["From", "Subject"]).execute() headers = {h["name"]: h["value"] for h in msg_detail.get("payload", {}).get("headers", [])} print(f" De : {headers.get('From', 'inconnu')} | Objet : {headers.get('Subject', '(sans objet)')}") return messages def send_email(service, to, subject, body_text): """Envoyer un email via la Gmail API.""" message = MIMEText(body_text) message["to"] = to message["subject"] = subject raw = base64.urlsafe_b64encode(message.as_bytes()).decode() message_body = {"raw": raw} sent = service.users().messages().send(userId="me", body=message_body).execute() print(f"Email envoyé — ID : {sent['id']}") return sent def label_emails(service, message_ids, label_name): """Ajouter un label personnalisé à une liste de messages.""" # Trouver ou créer le label labels = service.users().labels().list(userId="me").execute().get("labels", []) label_id = None for label in labels: if label["name"].lower() == label_name.lower(): label_id = label["id"] break if not label_id: created = service.users().labels().create(userId="me", body={"name": label_name, "labelListVisibility": "labelShow", "messageListVisibility": "show"}).execute() label_id = created["id"] print(f"Label '{label_name}' créé — ID : {label_id}") # Appliquer le label for msg_id in message_ids: service.users().messages().modify(userId="me", id=msg_id, body={"addLabelIds": [label_id]}).execute() print(f"Label '{label_name}' appliqué à {len(message_ids)} email(s)") if __name__ == "__main__": creds = get_credentials() service = build("gmail", "v1", credentials=creds) print("=== Emails non lus ===") unread = list_unread_emails(service) print("\n=== Envoi d'un email de test ===") send_email(service, "votre-email@gmail.com", "Test Gmail API", "Ceci est un email automatique envoyé via la Gmail API Python.") if unread: print("\n=== Classification automatique ===") ids = [m["id"] for m in unread[:5]] label_emails(service, ids, "AutoTraite")

Le script utilise 3 scopes OAuth : gmail.readonly pour lire, gmail.send pour envoyer, gmail.modify pour modifier les labels. La première exécution ouvre un navigateur pour l'autorisation Google — le token est sauvegardé dans token.json pour les exécutions suivantes.

Tester et valider que ça fonctionne

Lancer le script :

source venv/bin/activate
python gmail_auto.py

Première exécution : le navigateur s'ouvre pour l'autorisation Google. Autoriser l'application → le token est sauvegardé dans token.json. Exécutions suivantes : le token existant est rafraîchi automatiquement.

Résultat attendu dans le terminal :

=== Emails non lus === De : expediteur@example.com | Objet : Réunion demain De : newsletter@service.fr | Objet : Votre résumé hebdomadaire
=== Envoi d'un email de test ===
Email envoyé — ID : 18c4d5e6f7a8b9
=== Classification automatique ===
Label 'AutoTraite' créé — ID : Label_1234
Label 'AutoTraite' appliqué à 2 email(s)

Si vous recevez Error 400: redirect_uri_mismatch, vérifiez que le type de client OAuth est bien "Application de bureau" (pas "Application web"). Si HttpError 403, vérifiez que la Gmail API est activée dans Google Cloud Console.

Déployer et utiliser en production

Pour automatiser ce script en cron (exécution quotidienne à 8h) :

# Crontab
0 8 * * * cd /chemin/vers/gmail-automate && /chemin/vers/venv/bin/python gmail_auto.py >> /var/log/gmail-automate.log 2>&1

Pour un usage serveur sans navigateur (headless), remplacer flow.run_local_server(port=0) par :

flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
creds = flow.run_console() # Affiche une URL à copier dans un navigateur

Pour surveiller les nouveaux emails en temps réel, utiliser les Push Notifications de la Gmail API : service.users().watch(userId="me", body={"topicName": "projects/votre-projet/topics/gmail"}).execute() — chaque nouvel email déclenche un Pub/Sub vers votre endpoint.

Pour mettre à jour les packages : pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib.

Aller plus loin : 3 extensions concrètes

1. Répondeur automatique intelligent : combiner avec l'API OpenAI ou Mistral (pip install openai) pour générer des réponses contextuelles aux emails. Lire le corps du message avec service.users().messages().get(userId="me", id=msg_id, format="full"), extraire le texte du payload, l'envoyer à l'IA, puis répondre via send_email().

2. Filtrage anti-spam avancé : créer des filtres Gmail via l'API (service.users().settings().filters().create()) qui déplacent automatiquement les emails correspondant à des critères (expéditeur, sujet, mots-clés) vers un label spécifique ou la corbeille.

3. Rapport quotidien par email : combiner list_unread_emails() avec send_email() pour envoyer un résumé quotidien des emails non lus à votre adresse, classés par label. Programmer avec cron ou GitHub Actions pour une exécution automatique.