Pesquisar e filtrar mensagens

Este documento explica como consultar e encontrar mensagens usando a API Gmail.

Você pode pesquisar ou filtrar arquivos usando os métodos messages.list e threads.list. Esses métodos aceitam o parâmetro de consulta q, que é compatível com a maior parte da mesma sintaxe de pesquisa avançada da interface da Web do Gmail. Para conferir uma lista das diferenças de pesquisa e filtro entre a interface do Gmail e a API Gmail, consulte Diferenças da interface do Gmail.

Com essa sintaxe de pesquisa avançada, você pode usar consultas para filtrar mensagens por propriedades como remetente, data ou marcador. Por exemplo, a consulta do método messages.list a seguir recupera todas as mensagens enviadas pelo usuário em janeiro de 2014:

GET https://www.googleapis.com/gmail/v1/users/me/messages?q=in:sent after:2014/01/01 before:2014/02/01

Além das consultas de pesquisa, você também pode filtrar mensagens e conversas por marcador com o parâmetro labelIds[]. Assim, você pode pesquisar mensagens e conversas com os marcadores especificados do sistema ou do usuário. Para mais informações, consulte os métodos messages.list e threads.list. Para mais informações sobre rótulos, consulte Gerenciar rótulos.

Diferenças da interface do Gmail

Embora a API Gmail seja compatível com a maior parte da sintaxe de pesquisa avançada usada na interface do Gmail, há algumas diferenças:

  • A interface do Gmail realiza a expansão de alias, que permite inferir um alias de conta de uma conta do Google Workspace. Por exemplo, suponha que você tenha uma conta myprimary@cymbalgroup.com e seu administrador configure um alias myalias@cymbalgroup.com para ela. Se myalias@cymbalgroup.com enviar um e-mail, mas você pesquisar "from: myprimary@cymbalgroup.com", o e-mail enviado por myalias@cymbalgroup.com vai aparecer nos resultados da pesquisa na interface do Gmail, mas não na resposta da API.

  • A interface do Gmail permite que os usuários façam pesquisas em toda a conversa, mas a API não.