Ce document décrit 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
Tout comme l'API Email Settings, l'API Gmail utilise le protocole OAuth 2.0 pour autoriser les requêtes. L'une des principales différences est que les autorisations de l'API Gmail s'appliquent à un utilisateur individuel, et non à l'ensemble du domaine. Cela signifie qu'autoriser un compte administrateur de domaine ne vous permet pas de transférer la messagerie des autres utilisateurs du domaine. Pour générer le jeton d'authentification approprié, vous devez utiliser des comptes de service standards dotés d'une autorité à l'échelle du domaine et figurant sur la liste blanche de la console d'administration.
L'API Email Settings utilisait le champ d'application suivant:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Dans l'API Gmail, les champs d'application équivalents sont les suivants:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
Modifications apportées au protocole
L'API Email Settings utilise le protocole GDATA basé sur XML. L'API Gmail utilise du format JSON. Étant donné que les paramètres sont principalement composés de paires clé/valeur, les charges utiles sont conceptuellement similaires entre les versions.
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 Étiquettes.
| Ancien paramètre | Nouveau paramètre | Remarques |
|---|---|---|
| labelId | id | |
| étiquette | name | |
| unreadCount | messagesUnread | |
| visibilité | labelListVisibility | SHOW est maintenant labelShowHIDE est maintenant labelHide |
Autres modifications :
- Lors de la mise à jour ou de la suppression de libellés, l'API Gmail les référence par ID plutôt que par nom.
Gestion des filtres
Pour gérer les filtres dans l'API Gmail, utilisez la ressource Filtres.
| Ancien paramètre | Nouveau paramètre | Remarques |
|---|---|---|
| Source : | criteria.from | |
| pour | criteria.to | |
| objet | criteria.subject | |
| hasTheWord | criteria.query | |
| doesNotHaveTheWord | criteria.negatedQuery | |
| hasAttachment | criteria.hasAttachment | |
| shouldArchive | action.removeLabelIds | Utiliser INBOX comme ID du libellé |
| shouldMarkAsRead | action.removeLabelIds | Utiliser UNREAD comme ID du libellé |
| shouldStar | action.addLabelIds | Utiliser STARRED comme ID du libellé |
| étiquette | action.addLabelIds | Utilisez l'ID du libellé à ajouter |
| forwardTo | action.forward | |
| shouldTrash | action.addLabelIds | Utiliser TRASH comme ID du libellé |
| neverSpam | action.removeLabelIds | Utiliser SPAM comme ID du libellé |
Autres modifications :
- Si l'ajout d'un libellé utilisateur n'existe pas encore, vous devez le créer explicitement à l'aide de la méthode labels.create.
Gérer les alias d'envoi en tant que
Pour gérer les alias d'envoi en tant que dans l'API Gmail, utilisez la ressource SendAs.
| Ancien paramètre | Nouveau paramètre |
|---|---|
| name | displayName |
| adresse | sendAsEmail |
| replyTo | replyToAddress |
| makeDefault | isDefault |
Gérer les extraits du 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 |
|---|---|---|
| enable | activé | |
| forwardTo | emailAddress | |
| action | disposition | KEEP est maintenant leaveInInboxARCHIVE est maintenant archiveDELETE est maintenant trashMARK_READ est maintenant markRead |
Autres modifications :
- Les adresses de transfert doivent être créées et validées avant utilisation
- Les adresses de transfert peuvent être gérées via la ressource ForwardingAddresses.
Gestion des 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 |
|---|---|---|
| enable | accessWindow | Désactivé lorsque la règle est définie sur disabled |
| enableFor | accessWindow | ALL_MAIL est maintenant allMailMAIL_FROM_NOW_ON est maintenant fromNowOn |
| action | disposition | KEEP est maintenant leaveInInboxARCHIVE est maintenant archiveDELETE est maintenant trashMARK_READ est maintenant markRead |
Gestion des 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 |
|---|---|
| enable | activé |
Gestion des paramètres de réponse automatique du destinataire
Pour gérer la réponse automatique dans l'API Gmail, utilisez la ressource Settings (Paramètres).
| Ancien paramètre | Nouveau paramètre |
|---|---|
| contactsOnly | restrictToContacts |
| domainOnly | restrictToDomain |
| enable | enableAutoReply |
| endDate | endTime |
| message | réponseBodyHTML responseBodyPlainText |
| startDate | startTime |
| objet | responseSubject |
Gérer les paramètres de signature
Pour gérer les signatures d'e-mail 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 linguistiques
Pour gérer les paramètres de langue 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 Délégués.
| Ancien paramètre | Nouveau paramètre |
|---|---|
| adresse | delegateEmail |
| status | verificationStatus |
Autres modifications :
- Généralités
- Pour utiliser l'une des méthodes de délégation (y compris delegates.create), le délégateur doit être activé pour Gmail. Cela signifie, par exemple, que l'utilisateur délégateur ne peut pas être suspendu dansGoogle Workspace.
- Un alias d'adresse e-mail ne peut pas être utilisé comme adresse e-mail déléguée pour l'une des nouvelles méthodes. L'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 déléguées sur plusieurs domaines appartenant à la même Google Workspaceorganisation.
- Cette méthode peut désormais être utilisée pour les utilisateurs ayant besoin de changer de mot de passe lors de leur prochaine connexion.
- Lorsque cette méthode fonctionne, elle renvoie une ressource Users.settings.delegates dans le corps de la réponse plutôt qu'un corps de réponse vide.
- Si le délégateur ou le délégué est désactivé (par exemple, s'il est 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 des délégués avec n'importe quel verificationStatus, plutôt que simplement des délégués qui sont
acceptedouexpired.
- Cette méthode peut désormais être utilisée pour supprimer des délégués avec n'importe quel verificationStatus, plutôt que simplement des délégués qui sont
- delegates.get
- Il s'agit d'une nouvelle méthode, qui peut être préférable à la méthode delegates.list selon les besoins.
Gestion des paramètres généraux
Les paramètres généraux ne sont plus disponibles via l'API.