E‑Mail-Weiterleitung verwalten

In diesem Dokument wird beschrieben, wie Sie die E-Mail-Weiterleitung in der Gmail API konfigurieren.

Mit der Ressource settings können Sie die Weiterleitung für ein Konto konfigurieren. Damit eine E‑Mail-Adresse als Weiterleitungsadresse verwendet werden kann, muss sie eines der folgenden Kriterien erfüllen:

  • Die E‑Mail-Adresse wurde bestätigt. Weitere Informationen finden Sie unter Weiterleitungsadressen erstellen und bestätigen.
  • Die E-Mail-Adresse gehört zur selben Domain wie der Absender.
  • Die E-Mail-Adresse gehört zu einer Subdomain innerhalb derselben Domain des Absenders.
  • Die E-Mail-Adresse gehört zu einem Domainalias, der als Teil desselben Google Workspace-Kontos konfiguriert ist.

Wenn die Weiterleitungs-E-Mail-Adresse nicht einer dieser Regeln entspricht, schlägt die Einrichtung der Weiterleitung über die API fehl.

Informationen zum Erstellen, Auflisten, Abrufen> oder Löschen von Weiterleitungsadressen finden Sie in den Methoden für die Ressource settings.forwardingAddresses.

Informationen zum Abrufen oder Aktualisieren der Einstellungen für die automatische Weiterleitung finden Sie in den Methoden für die settings-Ressource.

Weiterleitungsadressen erstellen und bestätigen

Sie müssen Weiterleitungsadressen erstellen, bevor Sie sie verwenden können. In einigen Fällen müssen Nutzer auch nachweisen, dass sie Inhaber der Adresse sind.

Wenn in Gmail eine Nutzerbestätigung für eine Weiterleitungsadresse erforderlich ist, wird die Adresse mit einem VerificationStatus von pending zurückgegeben. Eine Bestätigungsnachricht wird automatisch an die Ziel-E-Mail-Adresse gesendet. Der Inhaber der E‑Mail-Adresse muss die Bestätigung abschließen, bevor sie verwendet werden kann.

Weiterleitungsadressen, für die keine Bestätigung erforderlich ist, haben den Bestätigungsstatus accepted.

Automatische Weiterleitung aktivieren

Sie können alle neuen Nachrichten an eine andere E-Mail-Adresse weiterleiten lassen.

Rufen Sie dazu die Methode updateAutoForwarding auf, um die automatische Weiterleitung für ein Konto zu aktivieren. Für den Aufruf ist eine registrierte und bestätigte Weiterleitungsadresse sowie eine Aktion erforderlich, die für weitergeleitete Nachrichten ausgeführt werden soll. Diese werden mit dem Objekt AutoForwarding festgelegt.

Mit dem Feld disposition wird der Nachrichtenstatus nach dem Weiterleiten der Nachricht festgelegt. Der Standardwert ist dispositionUnspecified, aber Sie können dieses Feld nicht auf dispositionUnspecified festlegen.

In den folgenden Codebeispielen wird gezeigt, wie Sie die automatische Weiterleitung aktivieren und weitergeleitete Nachrichten dann in den Papierkorb verschieben:

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()

Wenn Sie die automatische Weiterleitung deaktivieren möchten, rufen Sie die Methode updateAutoForwarding auf und setzen Sie das Feld enabled für das AutoForwarding-Objekt auf false.

Bestimmte Nachrichten weiterleiten

Bei der automatischen Weiterleitung werden alle empfangenen Gmail-Nachrichten an das Zielkonto gesendet. Wenn Sie bestimmte Nachrichten weiterleiten möchten, richten Sie einen Filter ein, um Regeln zu erstellen, mit denen Nachrichten basierend auf Nachrichtenattributen oder -inhalten weitergeleitet werden.

Wenn Sie Nachrichten an mehrere Konten weiterleiten möchten, erstellen Sie für jede Weiterleitungs-E-Mail-Adresse einen Filter.