Articles /

Présentation de l’API Gmail

L’API Gmail est une API RESTful qui peut être utilisée pour accéder aux boîtes aux lettres Gmail et envoyer du courrier. Pour la plupart des applications web (y compris les applications mobiles), l’API Gmail est le meilleur choix pour un accès autorisé aux données Gmail d’un utilisateur.

L’API Gmail vous donne un accès RESTful flexible à la boîte de réception de l’utilisateur, avec une interface naturelle àThreads,Messages,Labels,Drafts,History, et.Settings.Depuis le langage moderne de votre choix, votre application peut utiliser l’API pour ajouter des fonctionnalités deGmail comme :

  • Lire les messages de Gmail
  • Envoyer des messages électroniques
  • Modifier les étiquettes appliquées aux messages et aux fils
  • Rechercher des messages et des fils spécifiques
  • Créer des filtres pour étiqueter automatiquement, transférer, ou archiver des messages

Tout ce dont vous avez besoin pour utiliser l’API Gmail est la bibliothèqueclient pour votre choix de langue et une application qui peut s’authentifier comme un utilisateur Gmail.

Cas d’utilisation typiques

L’API Gmail peut être utilisée dans une variété d’applications différentes, dont,typiquement :

  • L’extraction, l’indexation et la sauvegarde du courrier en lecture seule
  • La gestion des étiquettes (ajouter/supprimer des étiquettes)
  • L’envoi automatisé ou programmé de messages
  • La migration de comptes de messagerie à partir d’autres fournisseurs
  • La définition de signatures de messagerie standardisées pour les utilisateurs d’un domaine

Comment en savoir plus ?

Utilisez cette documentation pour commencer à construire une application Gmail dès aujourd’hui :

  • Les bibliothèques client sont disponibles en téléchargement dans plusieurs langues et simplifient la réalisation des requêtes API.
  • Les sujets du guide du développeur vous aident à mieux comprendre comment mettre en œuvre des cas d’utilisation particuliers.
  • La référence API vous donne des détails sur chaqueresource et méthode de l’API Gmail.

Présentation de l’API

L’API Gmail est un service web : elle utilise une API RESTful avec une charge utile JSON.Cette section fournit un aperçu général des fonctionnalités de l’API et de leur utilisation. Pour des informations détaillées sur les ressources et les méthodes de l’API, reportez-vous à la référence GmailAPI.

Types de ressources clés

L’API Gmail fournit plusieurs types de ressources :

  • Messages
  • Étiquettes
  • Brouillons
  • Historique
  • Fils
  • Réglages

Les messages et les étiquettes sont les unités de base d’une boîte aux lettres. Les brouillons, l’historique et les fils de discussion contiennent tous un ou plusieurs messages avec des métadonnées supplémentaires.

Les messages sont immuables : ils peuvent seulement être créés et supprimés. Aucune propriété de message ne peut être modifiée, à l’exception des étiquettes appliquées à un message donné.

Les étiquettes servent de moyen principal pour catégoriser et organiser les messages et les fils de discussion. Une étiquette a une relation many-to-many avec les messages et les threads:un seul message peut avoir plusieurs étiquettes appliquées à lui et une seule étiquette peut être appliquée à plusieurs messages ou threads. Les étiquettes existent également en deux types:system et user. Les étiquettes système, telles que INBOX, TRASH, ou SPAM, sont créées en interne et ne peuvent pas être créées, supprimées ou modifiées. Cependant, certaines étiquettes système, telles que INBOX, peuvent être appliquées aux messages et aux fils de discussion ou en être retirées. Les étiquettes utilisateur peuvent être ajoutées, supprimées ou modifiées par l’utilisateur ou une application.

Les brouillons représentent les messages non envoyés. Les messages eux-mêmes ne peuvent pas être modifiés une fois créés, mais le message contenu dans le brouillon peut être remplacé.L’envoi d’un brouillon supprime automatiquement le brouillon et crée un message avec l’étiquette système SENT.

L’historique est une collection de messages récemment modifiés dans l’ordre chronologique.Bien que l’historique soit conçu comme une méthode légère de synchronisation d’un client,il ne contient généralement que les enregistrements des modifications des 30 derniers jours. Dans certains cas, comme lorsqu’un client devient trop obsolète, le client doit se synchroniser manuellement.

Les threads sont des collections de messages qui représentent une conversation. Comme les messages, les threads peuvent aussi avoir des étiquettes qui leur sont appliquées. Cependant, contrairement aux messages, les fils de discussion ne peuvent pas être créés, mais seulement supprimés. Les messages peuvent toutefois être insérés dans un fil de discussion.

Les paramètres contrôlent le comportement des fonctionnalités de Gmail pour un utilisateur. Les paramètres sont disponibles pour l’accès POP et IMAP, le transfert de courrier électronique, les filtres, la réponse automatique aux vacances, les alias d’envoi, les signatures, les délégués et la langue.

Auth et l’API Gmail

Comme les autres API REST de Google, l’API Gmail utiliseOAuth 2.0pour gérer l’authentification et l’autorisation. Votre application spécifiera un ou plusieurs scopes : des chaînes qui identifient les ressources auxquelles elle doit accéder. Ces scopes sont utilisés avec un ensemble de jetons pour sécuriser l’accès d’un utilisateur aux ressources.Une portée représente une forme particulière d’accès à une seule ressource ou à un groupe de ressources, par exemple :

  • Lire un message de Gmail (https://www.googleapis.com/auth/gmail.readonly)
  • Changer les étiquettes appliquées à un fil de discussion ou à un message(https://www.googleapis.com/auth/gmail.modify)
  • Envoyer un message au nom d’un utilisateur(https://www.googleapis.com/auth/gmail.compose)

Bien que vous puissiez coder explicitement les appels d’autorisation du service Web, vous devez normalement simplifier votre application en utilisant les bibliothèques client API de Google disponibles pour de nombreux langages de programmation.

Pour en savoir plus sur l’utilisation d’auth avec l’API Gmail, voirAutorisation de votre application avec Gmail.

Scopes

L’API Gmail prend en charge un certain nombre de scopes d’autorisation à granularité finepour n’autoriser que le niveau d’accès requis. En demandant le niveau d’accès minimum requis, les utilisateurs se sentent plus confiants en accordant l’accès à leur boîte aux lettres.

Exemple de cas d’utilisation

Envisagez le cas d’utilisation suivant : imprimer une page de fils pour l’utilisateur actuellement authentifié (par exemple, dans un panneau de messages récents).Pour y parvenir, votre application effectuerait les étapes suivantes :

  1. Authentifiez-vous en tant qu’utilisateur, en utilisant le scopehttps://www.googleapis.com/auth/gmail.readonly.
  2. Appeler la méthode API.GET https://www.googleapis.com/gmail/v1/users/<userId>/threads
  3. Traiter la liste retournée des threads dans votre application.

Pour un exemple de code réel, reportez-vous au Quickstart pour la langue de votre choix.

Utilisations courantes

Cette section fournit une vue de très haut niveau de la façon dont certains cas d’utilisation courants peuvent êtreimplémentés. Pour plus de détails, reportez-vous aux guides du développeur.

Envoi de messages Gmail

Les courriers électroniques sont envoyés sous forme de chaînes codées en base64url dans la propriété rawd’un message. Pour créer et envoyer un message :

  1. Créer le contenu du courriel d’une manière pratique, qui peut dépendre du langage de programmation que vous utilisez.
  2. Créer une représentation sous forme de chaîne encodée base64url de ce contenu.
  3. Créer une nouvelle ressource de message et définir sa propriété raw à la chaîne base64url que vous venez de créer.
  4. Appeler messages.sendpour envoyer le message.

Récupérer les emails reçus

Donné l’ID d’un email, vous pouvez récupérer le contenu en utilisant la méthodegetde la ressource Users.messages.

Lorsque vous récupérez un message, vous pouvez spécifier le format de charge utile pour la réponse.FULL (le format par défaut) renvoie l’intégralité du message analysé dans le champ payload.MINIMAL renvoie uniquement les métadonnées telles que les identifiants et les étiquettes.RAW renvoie les données sous la forme d’une chaîne encodée base64url dans la propriété raw.

Historique des modifications du courrier

Les modifications du message sont représentées parHistory objects. La propriétéstart_history_id vous permet de définir à partir de quel point vous voulez que les changements soient retournés. Certains changements peuvent affecter plus d’un message et l’historique représentant ce changement contiendra plusieurs messages.

Gestion des étiquettes

Les étiquettes appliquées à un fil sont également appliquées à tous les messages du fil.Si une étiquette est supprimée, elle est supprimée de tous les fils et messages auxquels elle était appliquée. La propriété messageListVisibility est utilisée pour déterminer si les messages avec cette étiquette apparaissent dans la liste des messages. De même, la propriétélabelListVisibility est utilisée pour déterminer si l’étiquette apparaît dans la liste des étiquettes. Vous pouvez utiliser la méthodemessages.modify outhreads.modify pour modifier les étiquettes appliquées aux messages ou aux threads, respectivement.

Leave a Reply