本文档介绍了如何使用 Gmail API 查询和查找邮件。
您可以使用 messages.list 和 threads.list 方法搜索或过滤文件。这些方法接受 q 查询参数，该参数支持与 Gmail 网页界面几乎相同的高级搜索语法。如需查看 Gmail 界面与 Gmail API 之间的搜索和过滤差异列表，请参阅与 Gmail 界面的差异。
借助这种高级搜索语法，您可以使用查询按发件人、日期或标签等属性过滤邮件。例如，以下 messages.list 方法查询会检索用户在 2014 年 1 月发送的所有消息：
GET https://www.googleapis.com/gmail/v1/users/me/messages?q=in:sent after:2014/01/01 before:2014/02/01
除了搜索查询之外，您还可以使用 labelIds[] 参数按标签过滤消息和会话。这样一来，您就可以搜索应用了指定系统标签或用户标签的邮件和会话。如需了解详情，请参阅 messages.list 和 threads.list 方法。如需详细了解标签，请参阅管理标签。
与 Gmail 界面的区别
虽然 Gmail API 支持 Gmail 界面中使用的大部分高级搜索语法，但仍存在一些差异：
Gmail 界面会执行别名扩展，从而能够从 Google Workspace 账号推断出账号别名。例如，假设您的账号为
myprimary@cymbalgroup.com，而您的管理员为该账号设置了别名myalias@cymbalgroup.com。如果myalias@cymbalgroup.com发送了一封电子邮件，但您搜索“from: myprimary@cymbalgroup.com”，则myalias@cymbalgroup.com发送的这封电子邮件会显示在 Gmail 界面的搜索结果中，但不会显示在 API 响应中。Gmail 界面允许用户执行整个会话的搜索，但 API 不允许。