ファイルを検索またはフィルタするには、messages.list メソッドと threads.list メソッドを使用します。これらのメソッドは、Gmail ウェブ インターフェースと同じ高度な検索構文のほとんどをサポートする q パラメータを受け入れます。Gmail UI と Gmail API の検索とフィルタの違いの一覧については、検索フィルタの違い: Gmail UI と Gmail API をご覧ください。
この高度な構文を使用すると、検索クエリを使用して、送信者、日付、ラベルなどのプロパティでメールをフィルタできます。たとえば、次のクエリは、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 UI と Gmail API
Gmail UI はエイリアスの展開を行い、Google Workspace アカウントからアカウント エイリアスを推測します。たとえば、アカウントが
myprimary@mycompany.netで、管理者がそのアカウントのエイリアスをmyalias@mycompany.netに設定したとします。myalias@mycompany.netがメールを送信し、from: myprimary@mycompany.net)を検索した場合、myalias@mycompany.netから送信されたメールは Gmail UI の検索結果に表示されますが、API レスポンスには表示されません。Gmail UI ではスレッド全体の検索が可能です。API では、そうした検索はできません。