Migrer depuis l'API Email Settings

Ce document vous aide à migrer votre application de l'API Email Settings obsolète 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 essentielle est que les autorisations de l'API Gmail sont limitées à un utilisateur individuel, et non à l'ensemble du domaine. Cela signifie que l'autorisation d'un compte administrateur de domaine ne vous permet pas de migrer les e-mails d'autres utilisateurs du domaine. Vous devez utiliser des comptes de service standards avec une autorité au niveau du domaine qui sont ajoutés à une liste d'autorisation dans la console d'administration Google pour générer le jeton d'authentification approprié.

L'API Email Settings utilisait le champ d'application suivant :

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 du protocole

L'API Email Settings utilise le protocole GDATA basé sur XML. L'API Gmail utilise JSON. Étant donné que les paramètres sont principalement constitué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 étiquettes

Pour gérer les libellés dans l'API Gmail, utilisez la ressource labels.

Ancien paramètre Nouveau paramètre Remarques
labelId id
étiquette nom
unreadCount messagesUnread
visibility labelListVisibility SHOW devient labelShow
HIDE devient labelHide

Autres modifications :

  • Lorsque vous mettez à jour ou supprimez des libellés, l'API Gmail fait référence aux libellés par ID plutôt que par nom.

Gérer les filtres

Pour gérer les filtres dans l'API Gmail, utilisez la ressource settings.filters.

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 Utilisez INBOX comme ID de libellé.
shouldMarkAsRead action.removeLabelIds Utilisez UNREAD comme ID de libellé.
shouldStar action.addLabelIds Utilisez STARRED comme ID de libellé.
étiquette action.addLabelIds Utiliser l'ID du libellé à ajouter
forwardTo action.forward
shouldTrash action.addLabelIds Utilisez TRASH comme ID de libellé.
neverSpam action.removeLabelIds Utilisez SPAM comme ID de libellé.

Autres modifications :

  • Si un libellé utilisateur que vous souhaitez ajouter n'existe pas déjà, vous devez le créer explicitement à l'aide de la méthode labels.create.

Gérer les alias "Envoyer sous"

Pour gérer les alias "Envoyer en tant que" dans l'API Gmail, utilisez la ressource settings.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 pas disponibles dans l'API Gmail.

Gérer le transfert automatique

Pour gérer le transfert automatique dans l'API Gmail, utilisez la ressource settings.

Ancien paramètre Nouveau paramètre Remarques
activer activé
forwardTo emailAddress
action disposition KEEP devient leaveInInbox
ARCHIVE devient archive
DELETE devient trash
MARK_READ devient markRead

Autres modifications :

  • Vous devez créer et valider les adresses de transfert avant de les utiliser.
  • Pour gérer les adresses de transfert, utilisez la ressource settings.forwardingAddresses.

Gérer les paramètres POP

Pour gérer l'accès POP dans l'API Gmail, utilisez la ressource settings.

Ancien paramètre Nouveau paramètre Remarques
activer accessWindow Désactivé lorsque la valeur est définie sur disabled
enableFor accessWindow ALL_MAIL devient allMail
MAIL_FROM_NOW_ON devient fromNowOn
action disposition KEEP devient leaveInInbox
ARCHIVE devient archive
DELETE devient trash
MARK_READ devient markRead

Gérer les paramètres IMAP

Pour gérer l'accès IMAP dans l'API Gmail, utilisez la ressource settings.

Ancien paramètre Nouveau paramètre
activer activé

Gérer les paramètres de réponse automatique pour les vacances

Pour gérer la réponse automatique pour les vacances dans l'API Gmail, utilisez la ressource settings.

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 d'e-mails dans l'API Gmail, utilisez la ressource settings.sendAs.

Ancien paramètre Nouveau paramètre
signature signature

Autres modifications :

  • Vous gérez désormais les signatures par alias.

Gérer les paramètres linguistiques

Pour gérer les paramètres linguistiques dans l'API Gmail, utilisez la ressource settings.

Ancien paramètre Nouveau paramètre
language displayLanguage

Pour en savoir plus, consultez Gérer les paramètres de langue.

Gérer les paramètres de délégation

Pour gérer la délégation dans l'API Gmail, utilisez la ressource settings.delegates.

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 settings.delegates.create), l'utilisateur délégant doit avoir activé Gmail. Cela signifie, par exemple, que l'utilisateur délégant ne peut pas être suspendu dans Google Workspace.
    • Vous ne pouvez pas utiliser d'alias d'adresse e-mail comme adresse e-mail du délégué pour les nouvelles méthodes. Vous devez faire référence à un utilisateur délégué en utilisant son adresse e-mail principale.
  • settings.delegates.create
    • Vous pouvez désormais utiliser cette méthode pour créer des relations de délégation entre plusieurs domaines appartenant à la même organisation Google Workspace.
    • Vous pouvez désormais utiliser cette méthode pour les utilisateurs qui doivent changer de mot de passe lors de leur prochaine connexion.
    • En cas de succès, cette méthode renvoie une ressource settings.delegates dans le corps de la réponse, plutôt qu'un corps de réponse vide.
    • Si l'utilisateur délégant ou délégué est désactivé (par exemple, suspendu dans Google Workspace), cette méthode échoue et renvoie une erreur HTTP 4XX au lieu d'une erreur HTTP 500.
  • settings.delegates.delete
    • Vous pouvez désormais utiliser cette méthode pour supprimer des délégués avec n'importe quel VerificationStatus, et pas seulement les délégués accepted ou expired.
  • settings.delegates.get
    • Il s'agit d'une nouvelle méthode qui peut être préférable à la méthode settings.delegates.list selon les besoins.

Gérer les paramètres généraux

Les paramètres généraux ne sont pas disponibles dans l'API Gmail.