guide · API Gmail

Comment une équipe produit doit-elle implémenter l’API Gmail en toute sécurité ?

Implémentez l’API Gmail comme un accès délégué à une boîte Gmail précise, et non comme un identifiant générique d’envoi d’e-mails. Choisissez le plus petit scope OAuth qui permet la fonctionnalité, protégez l’état d’autorisation et les jetons d’actualisation, et rattachez chaque boîte aux lettres à un tenant. Construisez les messages avec une bibliothèque mature de format de message Internet, enregistrez l’identifiant de message Gmail renvoyé et synchronisez les changements via Pub/Sub et les enregistrements d’historique. Considérez l’emprunt d’identité par compte de service comme une décision relevant de l’administrateur Workspace. Enfin, traitez l’acceptation par l’API, la livraison au serveur destinataire et l’arrivée en boîte de réception comme des résultats distincts.

Choisir le modèle de boîte aux lettres avant d’écrire du code

L’API Gmail agit sur la boîte Gmail d’un utilisateur. Elle convient lorsqu’un produit doit lire cette boîte, organiser ses libellés et ses fils de discussion, créer des brouillons, envoyer en tant qu’utilisateur autorisé ou synchroniser les changements de la boîte. Ce pouvoir est nettement plus large que l’appel à une API e-mail applicative depuis un domaine produit vérifié. Commencez par nommer précisément la tâche liée à la boîte aux lettres et l’acteur qui accorde l’accès. Un produit destiné aux utilisateurs s’appuie normalement sur le consentement OAuth pour chaque compte Google connecté. Une automatisation interne à Google Workspace peut au contraire utiliser une délégation au niveau du domaine approuvée par un administrateur. Si le seul besoin est d’envoyer des reçus, des liens de vérification, des alertes ou d’autres messages déclenchés par le produit depuis un domaine contrôlé par l’entreprise, évitez tout accès à la boîte aux lettres et évaluez une API d’e-mails transactionnels. Cette décision d’architecture réduit les accès superflus avant qu’un contrôle de sécurité ou un écran de consentement n’ait à les compenser.

Demander le scope le plus restreint possible

Configurez un client OAuth du bon type d’application, utilisez une URI de redirection enregistrée exacte et liez la réponse d’autorisation à la session de navigateur à l’origine de la demande grâce à une valeur state imprévisible. Demandez l’accès en contexte, au moment où l’utilisateur active la fonctionnalité qui en a besoin. Pour une intégration limitée à l’envoi, `https://www.googleapis.com/auth/gmail.send` est plus restreint que les scopes qui lisent ou modifient la boîte aux lettres. Google classe `gmail.send` comme sensible, tandis que des scopes comme `gmail.readonly`, `gmail.compose` et `gmail.modify` sont restreints. Une application publique utilisant un accès sensible ou restreint peut nécessiter une validation OAuth, et le stockage ou la transmission côté serveur de données relevant de scopes restreints peut entraîner des exigences supplémentaires d’évaluation de sécurité. Ne demandez l’accès hors ligne que si un traitement en arrière-plan est réellement nécessaire. Chiffrez les jetons d’actualisation, associez chaque jeton à un seul tenant interne et à un seul sujet Google, ne l’exposez jamais au code du navigateur ni aux logs, et proposez une procédure de déconnexion testée qui supprime les identifiants locaux et arrête le traitement en arrière-plan.

Comprendre les comptes de service et la délégation au niveau du domaine

Un compte de service est une identité d’application, pas une boîte Gmail prête à l’emploi. À lui seul, il n’obtient pas l’accès aux messages des collaborateurs. Pour les données utilisateur Google Workspace, un super-administrateur doit autoriser explicitement l’ID client numérique du compte de service et une liste exacte de scopes OAuth via la délégation au niveau du domaine. L’application demande ensuite des identifiants délégués pour un utilisateur nommé, et chaque appel d’API agit avec les autorisations de cet utilisateur, dans les limites des scopes autorisés. Gardez le sujet dont l’identité est empruntée explicite dans les données des tâches et les logs d’audit, afin qu’un worker en arrière-plan ne puisse pas changer de boîte aux lettres en silence. Utilisez des comptes de service distincts pour des charges de travail sensiblement différentes, évitez les clés privées téléchargeables lorsque l’environnement d’exécution peut utiliser des identifiants gérés, et réexaminez régulièrement les autorisations accordées au niveau du domaine. Les comptes Gmail grand public n’ont pas d’administrateur Workspace capable d’accorder cette délégation à l’échelle de l’organisation : utilisez donc le consentement OAuth de l’utilisateur pour ces comptes.

Envoyer des messages sans perdre le contrôle ni la traçabilité

Gmail accepte un message e-mail Internet complet dans le champ `raw`, encodé en base64url, via `users.messages.send` ; un produit peut aussi créer un brouillon et l’envoyer plus tard. Utilisez une bibliothèque de messages maintenue pour générer la structure From, To, Cc, Bcc, Subject, Date, Message-ID, texte, HTML et pièces jointes, au lieu d’assembler manuellement les lignes d’en-tête. Validez les destinataires et le contenu avant l’encodage, rejetez l’injection d’en-têtes et définissez des limites de taille explicites. Rendez l’action produit idempotente avant d’appeler Gmail : persistez une clé d’événement applicatif stable, le sujet de boîte aux lettres visé et un état de tentative d’envoi. Après une réponse réussie, stockez l’identifiant de message et l’identifiant de fil renvoyés par Gmail avec cet événement. Si le client atteint un timeout après avoir transmis la requête, rapprochez l’état de la boîte aux lettres avant de réessayer, car le message a peut-être déjà été accepté. Une nouvelle tentative aveugle peut produire un e-mail en double, même lorsque la réponse d’origine a été perdue. Utilisez la création de brouillon suivie d’une relecture humaine lorsque le contenu ou les destinataires nécessitent une approbation.

Synchroniser les changements de la boîte avec les enregistrements d’historique

Pour une intégration de boîte aux lettres côté serveur, un watch Gmail publie des signaux de changement via Google Cloud Pub/Sub. La notification est une invitation à synchroniser, pas le contenu complet d’un e-mail. Persistez l’ID d’historique actuel et l’expiration renvoyés par le watch, accusez réception rapidement des notifications et appelez `users.history.list` à partir du dernier ID d’historique validé avec succès pour découvrir les changements de messages et de libellés. Ne récupérez que les messages nécessaires à la fonctionnalité, puis faites avancer le point de reprise une fois les écritures locales réussies. Les notifications peuvent être retardées ou dupliquées : rendez donc le traitement des messages et de l’historique idempotent. Gmail exige qu’un watch de boîte aux lettres soit renouvelé au moins tous les sept jours et recommande un renouvellement quotidien ; planifiez le renouvellement bien avant l’expiration et déclenchez une alerte en cas d’échec. Si un ID d’historique stocké est hors de la plage disponible chez Gmail, l’API renvoie HTTP 404. Traitez ce cas comme une procédure de reprise définie : effectuez une synchronisation complète contrôlée, établissez un nouveau point de reprise et reprenez le traitement incrémental au lieu de réessayer indéfiniment l’ID d’historique invalide.

Suivre un workflow d’implémentation et de vérification par étapes

Premièrement, documentez si la fonctionnalité envoie, lit, modifie ou surveille des e-mails, et associez chaque opération à son scope OAuth minimal. Deuxièmement, créez des projets Google Cloud ou des clients OAuth distincts pour le développement et la production, avec des URI de redirection exactes et des responsables d’identifiants nommés. Troisièmement, implémentez l’autorisation avec validation du state, accès hors ligne uniquement si nécessaire, stockage chiffré des jetons, révocation des jetons et contrôles d’accès au niveau du tenant. Quatrièmement, testez avec des boîtes aux lettres contrôlées : connexion, actualisation d’un jeton d’accès expiré, révocation du consentement, reconnexion, envoi unique, simulation d’un timeout ambigu et confirmation de la prévention des doublons. Cinquièmement, si vous recevez des changements, configurez les autorisations Pub/Sub, démarrez un watch, traitez l’historique de manière incrémentale, forcez une reprise après point de reprise obsolète et vérifiez le renouvellement du watch. Sixièmement, ajoutez des files de travail par utilisateur, un backoff exponentiel borné, une classification structurée des erreurs et des logs d’audit qui omettent par défaut le corps des messages et les jetons. Avant le lancement, finalisez toute validation Google et revue de sécurité requises, publiez des informations exactes sur l’utilisation des données, et répétez la rotation des identifiants et la suppression des données utilisateur.

Anticiper les quotas, les nouvelles tentatives et les échecs partiels

Gmail mesure l’utilisation de l’API en unités de quota, et non seulement en nombre de requêtes. La page de quotas Google indique 1 200 000 unités par minute et par projet, ainsi que 6 000 unités par minute, par utilisateur et par projet. Elle indique que `messages.send`, `drafts.send` et `watch` coûtent chacun 100 unités, et une limite de 500 destinataires par message. Les limites d’envoi distinctes des utilisateurs Gmail s’appliquent toujours aux clients API, web et SMTP. Traitez la console Cloud et la documentation actuelle comme des entrées de configuration d’exécution plutôt que de coder en dur les limites publiées dans la logique métier. Sérialisez ou mettez équitablement les tâches en file d’attente par boîte aux lettres, limitez la concurrence et ne réessayez que les réponses transitoires avec un backoff exponentiel assorti d’un jitter et une échéance finie. Ne réessayez pas les erreurs d’autorisation, de politique, de destinataire non valide ou de message malformé comme s’il s’agissait de problèmes de capacité. Un lot multipart réduit la surcharge de connexion, mais chaque appel interne consomme toujours du quota et peut échouer indépendamment.

Distinguer acceptation, livraison et arrivée en boîte de réception

Un appel `messages.send` réussi signifie que Gmail a accepté la requête d’API autorisée et renvoyé une ressource Message Gmail. Il ne prouve pas que le serveur de messagerie de chaque destinataire a accepté le message, et ne permet pas de savoir comment un système destinataire a classé le message. La livraison au serveur destinataire signifie que le système de destination a accepté la responsabilité SMTP. L’arrivée en boîte de réception est un résultat de filtrage ultérieur : boîte principale, promotions, quarantaine ou spam. L’API de boîte aux lettres de Gmail ne remplace donc pas un flux d’événements de fournisseur lorsqu’un produit a besoin de télémétrie sur la livraison, les bounces ou les plaintes pour ses e-mails transactionnels. Conservez l’identifiant de message Gmail pour le rapprochement, mais décrivez l’état visible par l’utilisateur précisément comme « envoyé » ou « accepté par Gmail », sauf si une preuve distincte atteste la livraison. L’authentification, des destinataires qui attendent le message, la qualité du contenu, le comportement d’envoi et la politique de destination influent tous sur le traitement en aval. Une réponse d’API ne peut ni déterminer ni garantir le dossier final dans la boîte du destinataire.

Savoir quand une API d’e-mails transactionnels répond à un autre besoin

Utilisez Gmail API lorsque le produit a besoin d’un accès autorisé à la boîte aux lettres Gmail d’une personne ou d’une organisation, notamment aux fils de discussion, libellés, brouillons ou à la synchronisation de boîte aux lettres. Une API d’e-mails transactionnels convient à une architecture différente : des messages déclenchés par l’application et envoyés depuis des domaines contrôlés par l’organisation, sans autorité déléguée pour lire la boîte aux lettres Gmail d’un utilisateur. Un produit peut utiliser les deux types de systèmes lorsque les limites sont explicites, par exemple Gmail OAuth pour lire la boîte aux lettres connectée d’un agent de support et un fournisseur transactionnel vérifié séparément pour envoyer des reçus de produit. Conservez séparément les identifiants, le consentement, les magasins de messages, les politiques de nouvelle tentative et les enregistrements d’audit afin que l’autorité de la boîte aux lettres ne puisse pas s’étendre à l’envoi dans toute l’application et qu’un identifiant transactionnel ne puisse pas lire le Gmail d’un utilisateur.

Questions fréquentes

Un compte de service peut-il accéder à n’importe quelle boîte Gmail ?

Non. Un compte de service n’obtient pas automatiquement l’accès aux données utilisateur Gmail. Un super-administrateur Google Workspace doit accorder la délégation au niveau du domaine à son ID client numérique et aux scopes approuvés ; l’application emprunte ensuite explicitement l’identité d’un utilisateur de cette organisation. Pour les comptes Gmail grand public, utilisez plutôt le consentement OAuth de l’utilisateur.

Quel scope OAuth demander pour une intégration Gmail limitée à l’envoi ?

Commencez par évaluer `https://www.googleapis.com/auth/gmail.send`, qui permet d’envoyer au nom de l’utilisateur sans accorder de lecture générale de la boîte aux lettres. Vérifiez qu’aucune exigence produit ne nécessite réellement les brouillons, la lecture des messages, les libellés ou la modification avant de demander un scope plus large, et tenez compte des règles de validation de Google pour les scopes sensibles.

Un envoi réussi via l’API Gmail signifie-t-il que le message a été délivré ?

Non. Il confirme que Gmail a accepté l’opération d’API autorisée et renvoyé un enregistrement de message. L’acceptation par le serveur destinataire et l’arrivée en boîte de réception sont des états distincts en aval. N’indiquez pas que le message a été délivré et ne promettez pas son arrivée en boîte de réception, sauf si un autre signal fiable étaye cette conclusion.

Les notifications push Gmail contiennent-elles le nouveau message complet ?

Non. Une notification Pub/Sub signale que l’état de la boîte aux lettres a changé et inclut les informations nécessaires pour poursuivre la synchronisation. L’application doit interroger l’historique Gmail à partir de son ID d’historique enregistré, récupérer les données de message nécessaires, les traiter de façon idempotente, puis faire avancer son point de reprise.

À quelle fréquence faut-il renouveler un watch de boîte Gmail ?

Google exige d’appeler `watch` au moins une fois tous les sept jours et recommande un renouvellement quotidien. Stockez l’expiration renvoyée, renouvelez avant l’échéance, surveillez les échecs et gardez une tâche de synchronisation de secours, afin qu’un renouvellement manqué ne crée pas en silence un trou de données sans limite.

Quand une équipe doit-elle utiliser une API d’e-mails transactionnels plutôt que l’API Gmail ?

Utilisez une API d’e-mails transactionnels lorsqu’il s’agit d’e-mails déclenchés par l’application depuis des domaines contrôlés par l’organisation et qu’aucune fonctionnalité n’a besoin d’accéder à la boîte Gmail d’une personne. Utilisez l’API Gmail lorsque le produit a spécifiquement besoin, par délégation, des messages, fils de discussion, libellés, brouillons, paramètres ou du droit d’envoyer en tant que l’utilisateur.

Sources

Continuer à apprendre

Guide d’implémentation d’une API e-mail pour les équipes produitConcevez une intégration d’API e-mail sûre avec des domaines vérifiés, des envois mis en file d’attente, des identifiants stables, des nouvelles tentatives maîtrisées, des événements de livraison, la suppression et l’isolation entre tenants.