Gerenciar filtros do Gmail

Este documento explica como usar filtros na API Gmail.

Use o recurso settings.filters para configurar regras de filtragem avançada em uma conta. Os filtros podem adicionar ou remover marcadores automaticamente ou encaminhar e-mails para aliases verificados com base nos atributos ou no conteúdo da mensagem recebida.

Para informações sobre como criar, listar, receber ou excluir filtros do Gmail, consulte o recurso settings.filters.

Fazer a correspondência dos critérios

Filtre as mensagens por propriedades como remetente, assunto, data, tamanho e conteúdo da mensagem. Os filtros são aplicados apenas a mensagens específicas, não a toda a conversa por e-mail. Qualquer consulta que use a sintaxe de pesquisa avançada do Gmail também pode ser usada em um filtro. Por exemplo, padrões de filtro comuns incluem:

Filtro	Correspondências
`criteria.from='sender@example.com'`	E-mails de `sender@example.com`
`criteria.size=10485760` `criteria.sizeComparison='larger'`	E-mails com mais de 10 MB
`criteria.hasAttachment=true`	E-mails com um anexo
`criteria.subject='[People with Pets]'`	E-mails com `[People with Pets]` no assunto
`criteria.query='"my important project"'`	E-mails que contêm `my important project`
`criteria.negatedQuery='"secret knock"'`	E-mails que não contêm `secret knock`

Se um filtro tiver vários critérios, uma mensagem precisará atender a todos eles para que o filtro seja aplicado.

Ações

Aplicar um Action às mensagens que correspondem aos critérios do filtro. Com um Action, você pode encaminhar mensagens para um endereço de e-mail verificado ou adicionar e remover marcadores.

Adicione ou remova marcadores para mudar a disposição do e-mail. Por exemplo, algumas ações comuns incluem:

Ação	Efeito
`action.removeLabelIds=['INBOX']`	Arquivar o e-mail (ignorar a caixa de entrada)
`action.removeLabelIds=['UNREAD']`	Marcar como lida
`action.removeLabelIds=['SPAM']`	Nunca marcar como spam
`action.removeLabelIds=['IMPORTANT']`	Nunca marcar como importante
`action.addLabelIds=['IMPORTANT']`	Marcar como importante
`action.addLabelIds=['TRASH']`	Excluir o e-mail
`action.addLabelIds=['STARRED']`	Marcar como com estrela
`action.addLabelIds=['<user label id>']`	Adicione uma tag ao e-mail com um marcador definido pelo usuário. Apenas um rótulo definido pelo usuário é permitido por filtro.

Amostras de código

Os exemplos de código a seguir mostram como rotular e arquivar mensagens de uma lista de e-mails:

Java

gmail/snippets/src/main/java/CreateFilter.java

Ver no GitHub

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.Filter;
import com.google.api.services.gmail.model.FilterAction;
import com.google.api.services.gmail.model.FilterCriteria;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;

/* Class to demonstrate the use of Gmail Create Filter API */
public class CreateFilter {
  /**
   * Create a new filter.
   *
   * @param labelId - ID of the user label to add
   * @return the created filter id, {@code null} otherwise.
   * @throws IOException - if service account credentials file not found.
   */
  public static String createNewFilter(String labelId) 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_BASIC,
            GmailScopes.GMAIL_LABELS);
    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 {
      // Filter the mail from sender and archive them(skip the inbox)
      Filter filter = new Filter()
          .setCriteria(new FilterCriteria()
              .setFrom("gduser2@workspacesamples.dev"))
          .setAction(new FilterAction()
              .setAddLabelIds(Arrays.asList(labelId))
              .setRemoveLabelIds(Arrays.asList("INBOX")));

      Filter result = service.users().settings().filters().create("me", filter).execute();
      // Prints the new created filter ID
      System.out.println("Created filter " + result.getId());
      return result.getId();
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 403) {
        System.err.println("Unable to create filter: " + e.getDetails());
      } else {
        throw e;
      }
    }
    return null;
  }
}

Python

gmail/snippet/settings snippets/create_filter.py