[Gmail API] Javaでメールボックス内のラベルを作成・更新・削除する #OAuth2.0

Gmail API v1（Java）を使用して、
Gmailのラベルを作成・更新・削除する方法
についてご紹介します。

ラベルとは
メールにつける印みたいなものです。
ラベルを作ることでラベル毎に整理、管理することができます。

Gmailの「設定」 -> 「ラベル」から確認・設定できます。
作成可能なラベルは10,000個までです。

ラベルにはシステムが用意したsystemとユーザーが作成したuserが存在します。
systemのラベルは作成したり削除することはできません。(5. システムラベル)

APIを利用する環境の準備から始める場合や、コードを実行する際は、
⧉[Gmail API] JavaでGmail APIを使う
を参照ください。

No		目次
1		ラベルを作成
	1	スコープ
	2	実行
	3	レスポンスの内容
2		ラベルを上書き
	1	スコープ
	2	実行
	3	レスポンスの内容
3		ラベルを更新
	1	スコープ
	2	実行
	3	レスポンスの内容
4		ラベルを削除
	1	スコープ
	2	実行
	3	レスポンスの内容
5		システムラベル

本文中の引数にある「メールアドレス」の指定は、
OAuth 2.0使用の場合は「me」（自身）と指定してください。
「me」は認証されたユーザーを示します。

1. ラベルを作成

メールボックス内にラベルを作成します。
作成可能な最大数は10,000です。

1.1. スコープ

このAPIを実行するには、以下のいずれかのスコープを指定してください。

GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS

⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)
でスコープを指定してください。

1.2. 実行

ラベルを作成します。

setName、setLabelListVisibility、setMessageListVisibility
の3点は必須項目です。指定がないとエラーになります。

生成時は、Label.setId()でラベルIDを設定することはできません。
ラベルIDは自動で採番されます。

既に存在するラベル名(Label.setName())を指定することはできません。
同じ名前を指定するとエラーになります。

public static void main(String[] args) throws Exception{
    Gmail gmail = getGmail();
    Gmail.Users users = gmail.users();
    Gmail.Users.Labels labels = users.labels();
    
    Label content = new Label();
    content.setName("テストラベル");
    content.setLabelListVisibility("labelShow");
    content.setMessageListVisibility("show");
    Gmail.Users.Labels.Create create = labels.create("メールアドレス", content);
        
    Label res = create.execute();
    System.out.println(res);
}

1.2.1. HTTPリクエスト

POST:　https://gmail.googleapis.com/gmail/v1/users/{メールアドレス}/labels
が実行されます。

1.2.2. クエリパラメータ

クエリパラメータはありません。

1.2.3. リクエストボディ

Labelのsetメソッドにより、リクエストボディを設定できます。

メソッド	引数	説明
setId	String	ラベルID
setName	String	ラベルの表示名階層で親がある場合は、「/」でつなげた名前になる例："親/子/孫"
setMessageListVisibility	MessageListVisibility(enum)	「メールリストに表示」の設定
setLabelListVisibility	LabelListVisibility(enum)	「ラベルリストに表示」の設定
setType	Type(enum)	所有者タイプ
setMessagesTotal	Integer	メッセージの総数
setMessagesUnread	Integer	未読メッセージの数
setThreadsTotal	Integer	スレッドの総数
setThreadsUnread	Integer	未読のスレッドの数
setColor	Color	ラベルに割り当てる色

1.3. レスポンスの内容

Label

メソッド	戻り値	説明
getId	String	ラベルID
getName	String	ラベルの表示名階層で親がある場合は、「/」でつなげた名前になる例："親/子/孫"
getMessageListVisibility	MessageListVisibility(enum)	「メールリストに表示」の設定
getLabelListVisibility	LabelListVisibility(enum)	「ラベルリストに表示」の設定
getType	Type(enum)	所有者タイプ
getMessagesTotal	Integer	メッセージの総数
getMessagesUnread	Integer	未読メッセージの数
getThreadsTotal	Integer	スレッドの総数
getThreadsUnread	Integer	未読のスレッドの数
getColor	Color	ラベルに割り当てる色

MessageListVisibility

Gmailのラベル設定メニューの「メールリストに表示」の内容です。

定義値	内容
show	メールリストに表示
hide	メールリストに非表示

LabelListVisibility

Gmailのラベル設定メニューの「ラベルリストに表示」の内容です。

定義値	内容
labelShow	ラベルリストに表示
labelShowIfUnread	未読の場合はラベルリストに表示
labelHide	ラベルリストに非表示

Type

定義値	内容
system	Gmailで作成されたラベル
user	ユーザーまたはアプリケーションによって作成されたカスタムラベル

Color

メソッド	戻り値	説明
getTextColor	String	ラベルのテキスト色例："#684e07"
getBackgroundColor	String	背景色例："#fdedc1"

2. ラベルを上書き

指定したラベルを上書きします。

3. ラベルを更新と違うところは、
指定した存在するラベルを新しいラベルに置き換えます。

2.1. スコープ

このAPIを実行するには、以下のいずれかのスコープを指定してください。

GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS

⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)
でスコープを指定してください。

2.2. 実行

指定したラベルを更新します。

setId、setName、setLabelListVisibility、setMessageListVisibility
の4点は必須項目です。指定がないとエラーになります。

public static void main(String[] args) throws Exception{
    Gmail gmail = getGmail();
    Gmail.Users users = gmail.users();
    Gmail.Users.Labels labels = users.labels();
    
    Label content = new Label();
    content.setId("ラベルID");
    content.setName("上書きテスト");
    content.setLabelListVisibility("labelShow");
    content.setMessageListVisibility("show");
    Gmail.Users.Labels.Update update = labels.update("メールアドレス",content.getId(),content);
    
    Label res = update.execute();
    System.out.println(res);
}

2.2.1. HTTPリクエスト

PUT:　https://gmail.googleapis.com/gmail/v1/users/{メールアドレス}/labels/{ラベルID}
が実行されます。

2.2.2. クエリパラメータ

クエリパラメータはありません。

2.2.3. リクエストボディ

Labelのsetメソッドにより、リクエストボディを設定できます。

1.2.3. リクエストボディと同じです。

2.3. レスポンスの内容

Label

1.3. レスポンスの内容(Label)と同じです。

3. ラベルを更新

指定したラベルを更新します。

2. ラベルを上書きとの違いは、
指定した存在するラベルの設定内容を更新します。

3.1. スコープ

このAPIを実行するには、以下のいずれかのスコープを指定してください。

GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS

⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)
でスコープを指定してください。

3.2. 実行

指定したラベルを更新します。

ラベルIDの指定は必須です。指定がないとエラーになります。

public static void main(String[] args) throws Exception{
    Gmail gmail = getGmail();
    Gmail.Users users = gmail.users();
    Gmail.Users.Labels labels = users.labels();
    
    Label content = new Label();
    content.setId("ラベルID");
    content.setName("更新テスト");
    Gmail.Users.Labels.Patch patch = labels.patch("メールアドレス",content.getId(),content);
    
    Label res = patch.execute();
    System.out.println(res);
}

3.2.1. HTTPリクエスト

PATCH:　https://gmail.googleapis.com/gmail/v1/users/{メールアドレス}/labels/{ラベルID}
が実行されます。

3.2.2. クエリパラメータ

クエリパラメータはありません。

3.2.3. リクエストボディ

Labelのsetメソッドにより、リクエストボディを設定できます。

1.2.3. リクエストボディと同じです。

2.3. レスポンスの内容

Label

1.3. レスポンスの内容(Label)と同じです。

4. ラベルを削除

指定したラベルを削除します。

4.1. スコープ

このAPIを実行するには、以下のいずれかのスコープを指定してください。

GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS

⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)
でスコープを指定してください。

4.2. 実行

指定したラベルを削除します。

Typeが「user」のラベルのみ削除できます。

public static void main(String[] args) throws Exception{
    Gmail gmail = getGmail();
    Gmail.Users users = gmail.users();
    Gmail.Users.Labels labels = users.labels();

    Gmail.Users.Labels.Delete delete = labels.delete("メールアドレス","ラベルID");

    delete.execute();
}

4.2.1. HTTPリクエスト

DELETE:　https://gmail.googleapis.com/gmail/v1/users/{メールアドレス}/labels/{ラベルID}
が実行されます。

4.2.2. クエリパラメータ

クエリパラメータはありません。

4.2.3. リクエストボディ

リクエストボディはありません。

4.3. レスポンスの内容

レスポンスはありません。
削除に失敗した場合、例外が発生します。

5. システムラベル

typeが「system」であるラベル一覧を下記に示します。
(あくまで、筆者の環境でとれた情報です。)

id	name	説明
INBOX	INBOX	受信トレイ
STARRED	STARRED	スター付き
IMPORTANT	IMPORTANT	重要
CHAT	CHAT	チャット
SENT	SENT	送信済み
DRAFT	DRAFT	下書き
SPAM	SPAM	迷惑メール
TRASH	TRASH	ゴミ箱
CATEGORY_SOCIAL	CATEGORY_SOCIAL	ソーシャル(カテゴリ)
CATEGORY_UPDATES	CATEGORY_UPDATES	新着(カテゴリ)
CATEGORY_FORUMS	CATEGORY_FORUMS	フォーラム(カテゴリ)
CATEGORY_PROMOTIONS	CATEGORY_PROMOTIONS	プロモーション(カテゴリ)

おしまい。。