Gerenciar encaminhamento de e-mail

Este documento explica como configurar o encaminhamento de e-mail na API Gmail.

Use o recurso settings para configurar o encaminhamento de uma conta. Para usar um endereço de e-mail no encaminhamento, ele precisa atender a um dos seguintes critérios:

  • O endereço de e-mail foi verificado. Para mais informações, consulte Criar e verificar endereços de encaminhamento.
  • O endereço de e-mail pertence ao mesmo domínio do remetente.
  • O endereço de e-mail pertence a um subdomínio no mesmo domínio do remetente.
  • O endereço de e-mail pertence a um alias de domínio configurado como parte da mesma conta do Google Workspace.

Se o endereço de e-mail de encaminhamento não obedecer a uma dessas regras, a configuração do encaminhamento usando a API vai falhar.

Para saber como criar, listar, receber ou excluir endereços de encaminhamento, consulte os métodos no recurso settings.forwardingAddresses.

Para saber como receber ou atualizar as configurações de encaminhamento automático, consulte os métodos no recurso settings.

Criar e verificar endereços de encaminhamento

É necessário criar endereços de encaminhamento antes de usá-los. Em alguns casos, os usuários também precisam verificar a propriedade do endereço.

Se o Gmail exigir a verificação do usuário para um endereço de encaminhamento, a API vai retornar o endereço com um VerificationStatus de pending. O Gmail envia automaticamente uma mensagem de verificação para o endereço de e-mail de destino. O proprietário do endereço de e-mail precisa concluir o processo de verificação antes que você possa usá-lo.

Os endereços de encaminhamento que não exigem verificação têm um status de accepted.

Ativar o encaminhamento automático

É possível encaminhar todas as novas mensagens para outro endereço de e-mail.

Para fazer isso, chame o método updateAutoForwarding para ativar o encaminhamento automático de uma conta. A chamada exige um endereço de encaminhamento registrado e verificado e uma ação a ser realizada nas mensagens encaminhadas. Defina esses valores no objeto AutoForwarding.

Use o campo disposition para definir o estado da mensagem depois que ela for encaminhada. Embora o valor padrão seja dispositionUnspecified, não é possível definir esse campo como dispositionUnspecified.

Os exemplos de código a seguir mostram como ativar o encaminhamento automático e mover mensagens encaminhadas para a lixeira:

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

Para desativar o encaminhamento automático, chame o método updateAutoForwarding e defina o campo enabled no objeto AutoForwarding como false.

Encaminhar mensagens específicas

O encaminhamento automático envia todas as mensagens recebidas do Gmail para a conta de destino. Para encaminhar mensagens específicas, configure um filtro e crie regras que encaminhem mensagens em resposta a atributos ou conteúdo.

Para encaminhar mensagens para várias contas, crie um filtro para cada endereço de e-mail de encaminhamento.