このドキュメントでは、Gmail API を使用してスレッドとメッセージのラベルを管理する方法について説明します。
Gmail では、ラベルを使用してメールやスレッドにタグを付けたり、整理したり、分類したりできます。ラベルはメッセージやスレッドと多対多の関係にあります。1 つのメッセージやスレッドに複数のラベルを適用することも、複数のメッセージやスレッドに 1 つのラベルを適用することもできます。
ラベルの作成、取得、一覧表示、更新、削除の方法については、labels リソースをご覧ください。
ラベルを管理するには、https://www.googleapis.com/auth/gmail.labels の機密情報以外のスコープを使用する必要があります。スコープの詳細については、Gmail API のスコープを選択するをご覧ください。
ラベルの種類
ラベルには、予約済みの SYSTEM ラベルとカスタムの USER ラベルの 2 種類があります。
システムラベルは通常、Gmail ウェブ インターフェースの INBOX などの事前定義された要素に対応しています。システムラベル名は予約されています。SYSTEM ラベルと同じ名前の USER ラベルを作成することはできません。次の表に、最も一般的な Gmail システムラベルをいくつか示します。
| 名前 | 手動で適用可能 | メモ |
|---|---|---|
INBOX |
はい | |
SPAM |
はい | |
TRASH |
はい | |
UNREAD |
はい | |
STARRED |
はい | |
IMPORTANT |
はい | |
SENT |
× | 次のメッセージに自動的に適用されます。
|
DRAFT |
× | Gmail API または Gmail インターフェースで作成されたすべての draft メッセージに自動的に適用されます。 |
CATEGORY_PERSONAL |
はい | Gmail インターフェースの [個人] タブに表示されるメールに対応します。 |
CATEGORY_SOCIAL |
はい | Gmail インターフェースの [ソーシャル] タブに表示されるメールに対応します。 |
CATEGORY_PROMOTIONS |
はい | Gmail インターフェースの [プロモーション] タブに表示されるメールに対応します。 |
CATEGORY_UPDATES |
はい | Gmail インターフェースの [新着] タブに表示されるメッセージに対応します。 |
CATEGORY_FORUMS |
はい | Gmail インターフェースの [フォーラム] タブに表示されるメッセージに対応します。 |
スレッドとメッセージのラベルを管理する
ラベルはメッセージにのみ存在します。スレッドのラベルのリストを取得すると、スレッド内のメッセージに存在するラベルのリストが返されます。スレッド内のすべてのメッセージにラベルが付いているとは限りません。
下書きのメールにラベルを適用することはできません。
スレッドにラベルを追加または削除する
スレッドにラベルを追加または削除すると、スレッド内の既存のすべてのメッセージに対して指定したラベルが追加または削除されます。
ラベルを追加した後にメッセージがスレッドに追加された場合、新しいメッセージはスレッドに関連付けられている既存のラベルを継承しません。これらのメッセージにラベルを追加するには、スレッドに再度ラベルを追加します。
スレッドに関連付けられたラベルを追加または削除するには、threads.modify を使用します。
メールにラベルを追加または削除する
メッセージにラベルを追加すると、そのメッセージにラベルが追加され、メッセージが属するスレッドに関連付けられます。スレッド内の他のメッセージにはラベルは追加されません。
メールからラベルを削除したときに、そのラベルが付いたメールがスレッド内にそのメールしかなかった場合は、スレッドからもラベルが削除されます。
メッセージに適用されたラベルを追加または削除するには、messages.modify を使用します。