Gérer le transfert d'e-mails

Ce document explique comment configurer le transfert d'e-mails dans l'API Gmail.

Vous pouvez utiliser la ressource settings pour configurer le transfert pour un compte. Pour qu'une adresse e-mail puisse être utilisée comme adresse e-mail de transfert, elle doit répondre à l'un des critères suivants :

  • L'adresse e-mail est validée. Pour en savoir plus, consultez Créer et valider des adresses de transfert.
  • L'adresse e-mail appartient au même domaine que l'expéditeur.
  • L'adresse e-mail appartient à un sous-domaine du même domaine que celui de l'expéditeur.
  • L'adresse e-mail appartient à un alias de domaine configuré dans le même compte Google Workspace.

Si l'adresse e-mail de transfert ne respecte pas l'une de ces règles, la configuration du transfert à l'aide de l'API échoue.

Pour savoir comment créer, lister, obtenir ou supprimer des adresses de transfert, consultez les méthodes de la ressource settings.forwardingAddresses.

Pour savoir comment obtenir ou mettre à jour les paramètres de transfert automatique, consultez les méthodes de la ressource settings.

Créer et valider des adresses de transfert

Vous devez créer des adresses de transfert avant de les utiliser. Dans certains cas, les utilisateurs doivent également valider la propriété de l'adresse.

Si Gmail exige une validation de l'utilisateur pour une adresse de transfert, l'adresse est renvoyée avec un VerificationStatus de pending. Un message de validation est automatiquement envoyé à l'adresse e-mail cible. Le propriétaire de l'adresse e-mail doit terminer la procédure de validation avant de pouvoir l'utiliser.

Les adresses de transfert qui ne nécessitent pas de validation ont l'état de validation accepted.

Activer le transfert automatique

Vous pouvez choisir de transférer tous vos nouveaux messages vers une autre adresse e-mail.

Pour ce faire, appelez la méthode updateAutoForwarding afin d'activer le transfert automatique pour un compte. L'appel nécessite une adresse de transfert enregistrée et validée, ainsi qu'une action à effectuer sur les messages transférés. Ils sont définis à l'aide de l'objet AutoForwarding.

Le champ disposition permet de définir l'état du message après son transfert. La valeur par défaut est dispositionUnspecified, mais vous ne pouvez pas définir ce champ sur dispositionUnspecified.

Les exemples de code suivants montrent comment activer le transfert automatique, puis déplacer les messages transférés vers la corbeille :

Java

gmail/snippets/src/main/java/EnableForwarding.java
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.gmail.Gmail;
import com.google.api.services.gmail.GmailScopes;
import com.google.api.services.gmail.model.AutoForwarding;
import com.google.api.services.gmail.model.ForwardingAddress;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;

/* Class to demonstrate the use of Gmail Enable Forwarding API */
public class EnableForwarding {
  /**
   * Enable the auto-forwarding for an account.
   *
   * @param forwardingEmail - Email address of the recipient whose email will be forwarded.
   * @return forwarding id and metadata, {@code null} otherwise.
   * @throws IOException - if service account credentials file not found.
   */
  public static AutoForwarding enableAutoForwarding(String forwardingEmail) throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(GmailScopes.GMAIL_SETTINGS_SHARING);
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

    // Create the gmail API client
    Gmail service = new Gmail.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Gmail samples")
        .build();

    try {
      // Enable auto-forwarding and move forwarded messages to the trash
      ForwardingAddress address = new ForwardingAddress()
          .setForwardingEmail(forwardingEmail);
      ForwardingAddress createAddressResult = service.users().settings().forwardingAddresses()
          .create("me", address).execute();
      if (createAddressResult.getVerificationStatus().equals("accepted")) {
        AutoForwarding autoForwarding = new AutoForwarding()
            .setEnabled(true)
            .setEmailAddress(address.getForwardingEmail())
            .setDisposition("trash");
        autoForwarding =
            service.users().settings().updateAutoForwarding("me", autoForwarding).execute();
        System.out.println(autoForwarding.toPrettyString());
        return autoForwarding;
      }
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 403) {
        System.err.println("Unable to enable forwarding: " + e.getDetails());
      } else {
        throw e;
      }
    }
    return null;
  }
}

Python

gmail/snippet/settings snippets/enable_forwarding.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def enable_forwarding():
  """Enable email forwarding.
  Returns:Draft object, including forwarding id and result meta data.

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create gmail api client
    service = build("gmail", "v1", credentials=creds)

    address = {"forwardingEmail": "gduser1@workspacesamples.dev"}

    # pylint: disable=E1101
    result = (
        service.users()
        .settings()
        .forwardingAddresses()
        .create(userId="me", body=address)
        .execute()
    )
    if result.get("verificationStatus") == "accepted":
      body = {
          "emailAddress": result.get("forwardingEmail"),
          "enabled": True,
          "disposition": "trash",
      }
      # pylint: disable=E1101
      result = (
          service.users()
          .settings()
          .updateAutoForwarding(userId="me", body=body)
          .execute()
      )
      print(f"Forwarding is enabled : {result}")

  except HttpError as error:
    print(f"An error occurred: {error}")
    result = None

  return result


if __name__ == "__main__":
  enable_forwarding()

Pour désactiver le transfert automatique, appelez la méthode updateAutoForwarding et définissez le champ enabled de l'objet AutoForwarding sur false.

Transférer des messages spécifiques

Le transfert automatique envoie tous les messages Gmail reçus vers le compte cible. Pour transférer des messages spécifiques, configurez un filtre afin de créer des règles qui transfèrent les messages en fonction de leurs attributs ou de leur contenu.

Pour transférer des messages vers plusieurs comptes, créez un filtre pour chaque adresse e-mail de transfert.