Migrer depuis l'API Email Settings

Ce document peut vous aider à 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. L'une des principales différences est que les autorisations de l'API Gmail sont limitées à un utilisateur individuel, plutôt qu'à 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 plutôt utiliser des comptes de service standards avec une autorité à l'échelle 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 champs d'application équivalents dans l'API Gmail sont les suivants :

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing

Changements de 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 libellés

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

Ancien paramètre Nouveau paramètre Remarques
labelId id
label name
unreadCount messagesUnread
visibility labelListVisibility SHOW devient labelShow
HIDE devient labelHide

Autres modifications :

  • Lors de la mise à jour ou de la suppression de 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 settings.filters ressource.

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é.
libellé action.addLabelIds Utilisez 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 l'ajout d'un libellé utilisateur n'existe pas déjà, il doit être créé explicitement à l'aide de la labels.create méthode.

Gérer les alias d'envoi

Pour gérer les alias d'envoi dans l'API Gmail, utilisez la settings.sendAs ressource.

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 settings ressource.

Ancien paramètre Nouveau paramètre Remarques
activer activé
forwardTo emailAddress
action disposition KEEP devient leaveInInbox
devient archive
devient trash
devient markReadARCHIVEDELETEMARK_READ

Autres modifications :

  • Les adresses de transfert doivent être créées et validées avant utilisation.
  • Les adresses de transfert peuvent être gérées à l'aide de la settings.forwardingAddresses ressource.

Gérer les paramètres POP

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

Ancien paramètre Nouveau paramètre Remarques
activer accessWindow Désactivé lorsque défini sur disabled
enableFor accessWindow ALL_MAIL devient allMail
MAIL_FROM_NOW_ON devient fromNowOn
action disposition KEEP devient leaveInInbox
devient archive
devient trash
devient markReadARCHIVEDELETEMARK_READ

Gérer les paramètres IMAP

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

Ancien paramètre Nouveau paramètre
activer activé

Gérer les paramètres de réponse automatique en cas d'absence

Pour gérer la réponse automatique en cas d'absence dans l'API Gmail, utilisez la settings ressource.

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

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 de langue dans l'API Gmail, utilisez la settings ressource.

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 settings.delegates ressource.

Ancien paramètre Nouveau paramètre
adresse delegateEmail
état verificationStatus

Autres modifications :

  • Généralités
    • Pour utiliser l'une des méthodes de délégation (y compris settings.delegates.create) l'utilisateur délégant doit être activé pour Gmail. Cela signifie, par exemple, que l'utilisateur délégant ne peut pas être suspendu dans Google Workspace.
    • Un alias d'adresse e-mail ne peut pas être utilisé comme entrée d'adresse e-mail du délégué pour l'une des nouvelles méthodes. Un utilisateur délégué doit être référencé par son adresse e-mail principale.
  • settings.delegates.create
    • Cette méthode peut désormais être utilisée pour créer des relations de délégation sur plusieurs domaines appartenant à la même organisation Google Workspace.
    • Cette méthode peut désormais être utilisée pour les utilisateurs qui doivent changer leur mot de passe lors de leur prochaine connexion.
    • En cas de succès, cette méthode renvoie une settings.delegates ressource 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 avec une erreur HTTP 4XX au lieu d'une erreur HTTP 500.
  • settings.delegates.delete
    • Cette méthode peut désormais être utilisée 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 settings.delegates.list méthode 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.