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