Ce document présente les principales différences entre l'API Email Settings et l'API Gmail. Vous pouvez utiliser ce guide pour migrer votre application vers l'API Gmail.
Autoriser les requêtes
Comme l'API Email Settings, l'API Gmail utilise le protocole OAuth 2.0 pour autoriser les requêtes. Une différence clé est que les autorisations de l'API Gmail sont limitées à un utilisateur individuel, et non à l'ensemble du domaine. Autrement dit, l'autorisation d'un compte administrateur de domaine ne vous permet pas de migrer les e-mails pour d'autres utilisateurs du domaine. À la place, vous devez utiliser des comptes de service standards disposant d'une autorité au niveau du domaine ajoutés à la liste blanche dans la console d'administration pour générer le jeton d'authentification approprié.
L'API Email Settings utilisait le champ d'application:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Les habilitations équivalentes dans l'API Gmail sont les suivantes:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
Modifications de protocole
L'API Email Settings utilise le protocole GDATA basé sur XML. L'API Gmail utilise le format JSON. Étant donné que les paramètres sont principalement constitués de paires clé/valeur, les charges utiles sont conceptuellement similaires d'une version à l'autre.
Exemple de création d'un libellé:
API Email Settings
POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name="label" value="status updates" />
</atom:entry>
API Gmail
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
Utilisez les bibliothèques clientes fournies au lieu d'implémenter directement le protocole.
Gérer les libellés
Pour gérer les libellés dans l'API Gmail, utilisez la ressource Labels (Libellés).
| Ancien paramètre | Nouveau paramètre | Remarques |
|---|---|---|
| labelId | id | |
| étiquette | nom | |
| unreadCount | messagesUnread | |
| visibilité | labelListVisibility | SHOW devient labelShowHIDE devient labelHide |
Autres modifications :
- Lorsque vous mettez à jour ou supprimez des libellés, l'API Gmail les référence par ID au lieu de par nom.
Gérer les filtres
Pour gérer les filtres dans l'API Gmail, utilisez la ressource Filtres.
| Ancien paramètre | Nouveau paramètre | Remarques |
|---|---|---|
| de | criteria.from | |
| pour | criteria.to | |
| objet | criteria.subject | |
| hasTheWord | criteria.query | |
| doesNotHaveTheWord | criteria.negatedQuery | |
| hasAttachment | criteria.hasAttachment | |
| shouldArchive | action.removeLabelIds | Utiliser INBOX comme ID de libellé |
| shouldMarkAsRead | action.removeLabelIds | Utiliser UNREAD comme ID de libellé |
| shouldStar | action.addLabelIds | Utiliser STARRED comme ID de libellé |
| étiquette | action.addLabelIds | Utilisez l'ID du libellé à ajouter. |
| forwardTo | action.forward | |
| shouldTrash | action.addLabelIds | Utiliser TRASH comme ID de libellé |
| neverSpam | action.removeLabelIds | Utiliser SPAM comme ID de libellé |
Autres modifications :
- Si vous ajoutez un libellé utilisateur qui n'existe pas déjà, vous devez le créer explicitement à l'aide de la méthode labels.create.
Gérer les alias d'envoi
Pour gérer les alias d'envoi dans l'API Gmail, utilisez la ressource SendAs.
| Ancien paramètre | Nouveau paramètre |
|---|---|
| nom | displayName |
| adresse | sendAsEmail |
| replyTo | replyToAddress |
| makeDefault | isDefault |
Gérer les extraits Web
Les paramètres des extraits Web ne sont plus disponibles via l'API.
Gérer les paramètres de transfert automatique
Pour gérer le transfert automatique dans l'API Gmail, utilisez la ressource Settings (Paramètres).
| Ancien paramètre | Nouveau paramètre | Remarques |
|---|---|---|
| activer | activé | |
| forwardTo | emailAddress | |
| action | disposition | KEEP est désormais leaveInInboxARCHIVE est désormais archiveDELETE est désormais trashMARK_READ est désormais markRead |
Autres modifications :
- Les adresses de transfert doivent être créées et validées avant d'être utilisées.
- Les adresses de transfert peuvent être gérées via la ressource ForwardingAddresses.
Gérer les paramètres POP
Pour gérer l'accès POP dans l'API Gmail, utilisez la ressource Settings (Paramètres).
| Ancien paramètre | Nouveau paramètre | Remarques |
|---|---|---|
| activer | accessWindow | Désactivé si défini sur disabled |
| enableFor | accessWindow | ALL_MAIL devient allMailMAIL_FROM_NOW_ON devient fromNowOn |
| action | disposition | KEEP est désormais leaveInInboxARCHIVE est désormais archiveDELETE est désormais trashMARK_READ est désormais markRead |
Gérer les paramètres IMAP
Pour gérer l'accès IMAP dans l'API Gmail, utilisez la ressource Settings (Paramètres).
| Ancien paramètre | Nouveau paramètre |
|---|---|
| activer | activé |
Gérer les paramètres de réponse automatique en cas de vacances
Pour gérer la réponse automatique en cas d'absence dans l'API Gmail, utilisez la ressource Settings (Paramètres).
| Ancien paramètre | Nouveau paramètre |
|---|---|
| contactsOnly | restrictToContacts |
| domainOnly | restrictToDomain |
| activer | enableAutoReply |
| endDate | endTime |
| message | responseBodyHtml responseBodyPlainText |
| startDate | startTime |
| objet | responseSubject |
Gérer les paramètres de signature
Pour gérer les signatures de messagerie dans l'API Gmail, utilisez la ressource SendAs.
| Ancien paramètre | Nouveau paramètre |
|---|---|
| signature | signature |
Autres modifications :
- Les signatures sont désormais gérées par alias.
Gérer les paramètres de langue
Pour gérer les paramètres linguistiques dans l'API Gmail, utilisez la ressource Settings (Paramètres).
| Ancien paramètre | Nouveau paramètre |
|---|---|
| language | displayLanguage |
Pour en savoir plus, consultez le guide de gestion des paramètres linguistiques.
Gérer les paramètres de délégation
Pour gérer la délégation dans l'API Gmail, utilisez la ressource Delegates (Délégués).
| Ancien paramètre | Nouveau paramètre |
|---|---|
| adresse | delegateEmail |
| état | verificationStatus |
Autres modifications :
- Général
- Pour utiliser l'une des méthodes de délégation (y compris delegates.create), l'utilisateur délégateur doit être activé pour Gmail. Cela signifie, par exemple, que l'utilisateur du délégant ne peut pas être suspendu dansGoogle Workspace.
- Un alias d'adresse e-mail ne peut pas être utilisé comme adresse e-mail de délégué pour aucune des nouvelles méthodes. Un utilisateur délégué doit être désigné par son adresse e-mail principale.
- delegates.create
- Cette méthode peut désormais être utilisée pour créer des relations de délégation entre plusieurs domaines appartenant à la même Google Workspace organisation.
- Cette méthode peut désormais être utilisée pour les utilisateurs qui doivent modifier leur mot de passe lors de leur prochaine connexion.
- Si la requête aboutit, cette méthode renvoie une ressource Users.settings.delegates dans le corps de la réponse, plutôt qu'un corps de réponse vide.
- Si l'un des utilisateurs délégués ou délégués est désactivé (par exemple, suspendu dans Google Workspace), cette méthode échoue avec une erreur HTTP 4XX au lieu d'une erreur HTTP 500.
- delegates.delete
- Cette méthode peut désormais être utilisée pour supprimer les délégués avec n'importe quel verificationStatus, et non seulement les délégués
acceptedouexpired.
- Cette méthode peut désormais être utilisée pour supprimer les délégués avec n'importe quel verificationStatus, et non seulement les délégués
- delegates.get
- Il s'agit d'une nouvelle méthode, qui peut être préférable à la méthode delegates.list selon les besoins.
Gérer les paramètres généraux
Les paramètres généraux ne sont plus disponibles via l'API.