Guide
Gmail API et IA : scopes restreints et vérification
gmail.readonly, gmail.metadata, gmail.modify : quels scopes une IA demande, lesquels sont restreints, quand Google exige une évaluation de sécurité.
Mis à jour le
Une IA qui lit des mails Gmail par l'API Gmail demande presque toujours un scope restreint : c'est le cas de gmail.readonly, de gmail.metadata et de gmail.modify. Pour une application publique, un scope restreint implique une vérification par Google et, si les données passent par vos serveurs, une évaluation de sécurité renouvelée tous les douze mois. Une application interne à votre organisation Google Workspace en est exemptée. Voici le détail, d'après la documentation Google lue le 15/11/2026.
Un scope OAuth est une permission précise, affichée à l'utilisateur sur l'écran de consentement : « voir vos messages », « envoyer en votre nom »…
Les scopes Gmail et leur classement
| Scope | Ce qu'il permet (d'après Google) | Classement |
|---|---|---|
gmail.labels |
Voir et modifier les libellés | Non sensible |
gmail.send |
Envoyer des mails en votre nom | Sensible |
gmail.metadata |
Voir les métadonnées (libellés, en-têtes), pas le corps | Restreint |
gmail.readonly |
Voir les messages et les paramètres | Restreint |
gmail.compose |
Gérer les brouillons et envoyer | Restreint |
gmail.insert |
Ajouter des mails dans la boîte | Restreint |
gmail.modify |
Lire, rédiger et envoyer ; pas de suppression définitive immédiate | Restreint |
https://mail.google.com/ |
Tout, y compris la suppression définitive | Restreint |
Les scopes gmail.addons.* (non sensibles ou sensibles) ne valent que pour un module complémentaire Google Workspace, pendant que l'utilisateur s'en sert : ils ne conviennent pas à un traitement en arrière-plan.
Google demande de ne réclamer https://mail.google.com/ que si l'application doit supprimer immédiatement et définitivement des messages, sans passer par la corbeille. Pour une IA, c'est rarement justifié.
Choisir selon ce que fait l'IA
| L'IA doit… | Scope le plus étroit |
|---|---|
| Classer d'après l'expéditeur, l'objet, les libellés | gmail.metadata |
| Lire le contenu pour résumer ou extraire | gmail.readonly |
| Préparer des brouillons de réponse | gmail.compose |
| Envoyer seule | gmail.send, à réserver aux cas validés |
| Poser des libellés | gmail.labels (avec un scope de lecture si elle doit lire) |
La vérification des scopes restreints
Qui doit la passer : une application qui demande des scopes restreints et n'entre dans aucune exception.
Les exceptions listées par Google :
- Usage personnel : vous êtes le seul utilisateur, ou l'application ne sert qu'à quelques personnes que vous connaissez.
- Application interne : utilisée seulement par les personnes de votre organisation Google Workspace ou Cloud Identity, avec le projet et l'écran de consentement réglés sur « Internal ».
- Installation à l'échelle du domaine par l'administrateur : elle dispense de la vérification de la marque, pas de la vérification de l'application si elle utilise des scopes sensibles ou restreints.
L'évaluation de sécurité : une application qui accède à des données restreintes et peut les atteindre depuis un serveur tiers doit passer une évaluation par un évaluateur agréé par Google, selon le cadre CASA (Cloud Application Security Assessment). Elle doit être revérifiée au moins tous les douze mois après la date d'approbation de la lettre d'évaluation. La documentation Gmail le résume ainsi : si vous stockez ou transmettez des données de scopes restreints sur des serveurs, vous devez passer cette évaluation.
Pour une PME qui branche une IA sur ses propres boîtes, la voie la plus simple est donc l'application interne. Pour un éditeur qui vend une IA branchée sur Gmail à d'autres entreprises, la vérification et l'évaluation annuelle font partie du coût du produit.
Être prévenu des nouveaux mails
L'API Gmail notifie par Cloud Pub/Sub, le service de messagerie de Google Cloud, et non par un appel direct à votre serveur :
- Créer un sujet (topic) Pub/Sub et un abonnement.
- Autoriser le compte
gmail-api-push@system.gserviceaccount.comà publier sur ce sujet. - Appeler
watchsur la boîte. - À chaque notification, décoder le message (Base64URL) : il contient l'adresse et le nouvel identifiant d'historique (
historyId). - Appeler
history.listdepuis le dernierhistoryIdconnu pour obtenir les changements.
Deux limites à retenir : watch doit être rappelé au moins tous les sept jours (Google recommande une fois par jour), et chaque utilisateur surveillé est limité à un événement par seconde, les événements au-delà étant perdus. Prévoyez donc une relecture périodique de l'historique en filet de sécurité.
Et pour toutes les boîtes de l'entreprise ?
Lire les boîtes de tous les salariés sans leur consentement individuel passe par la délégation au niveau du domaine, accordée par un super-administrateur. Certains scopes, comme gmail.settings.sharing, n'existent d'ailleurs qu'avec un compte de service doté de cette délégation. C'est un pouvoir étendu, expliqué sur la page délégation au niveau du domaine. L'équivalent chez Microsoft est sur Microsoft Graph et les mails Outlook.
Questions fréquentes
gmail.readonly est-il un scope restreint ?
Oui. Dans le tableau de Google, gmail.readonly, gmail.metadata, gmail.modify, gmail.compose, gmail.insert et l'accès complet https://mail.google.com/ sont classés « restreints ».
Une application Gmail interne à l'entreprise doit-elle passer la vérification de Google ?
Google exempte les applications internes, utilisées seulement par les personnes de votre organisation Google Workspace ou Cloud Identity, si le projet et l'écran de consentement sont réglés sur « Internal ». Il exempte aussi l'usage personnel ou par quelques utilisateurs connus.
Combien de temps dure un abonnement aux notifications Gmail ?
Il faut rappeler la méthode watch au moins tous les sept jours, sinon les notifications s'arrêtent. Google recommande de l'appeler une fois par jour.
Sources
Pages consultées pour écrire cet article :