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

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

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

Gmailの「設定」 -> 「ラベル」 から確認・設定できます。
作成可能なラベルは10,000個までです。
<img width=480 src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/114621/e839e8e4-897b-863e-5279-667793b3f265.png">
ラベルにはシステムが用意したsystemとユーザーが作成したuserが存在します。
systemのラベルは作成したり削除することはできません。([5. システムラベル](#5-システムラベル))

:::note info
APIを利用する環境の準備から始める場合や、コードを実行する際は、
[⧉[Gmail API] JavaでGmail APIを使う](https://qiita.com/doran/items/a078e966bfd93c4b19c2)
を参照ください。
:::

|No||目次|
|---|---|---|
|1||[ラベルを作成](#1-ラベルを作成)|
||1|[スコープ](#11-スコープ)|
||2|[実行](#12-実行)|
||3|[レスポンスの内容](#13-レスポンスの内容)|
|2||[ラベルを上書き](#2-ラベルを上書き)|
||1|[スコープ](#21-スコープ)|
||2|[実行](#22-実行)|
||3|[レスポンスの内容](#23-レスポンスの内容)|
|3||[ラベルを更新](#3-ラベルを更新)|
||1|[スコープ](#31-スコープ)|
||2|[実行](#32-実行)|
||3|[レスポンスの内容](#33-レスポンスの内容)|
|4||[ラベルを削除](#4-ラベルを削除)|
||1|[スコープ](#41-スコープ)|
||2|[実行](#42-実行)|
||3|[レスポンスの内容](#43-レスポンスの内容)|
|5||[システムラベル](#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インスタンスを取得)](https://qiita.com/doran/items/a078e966bfd93c4b19c2#22-gmailインスタンスを取得)
でスコープを指定してください。

#### 1.2. 実行
ラベルを作成します。

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

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

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

```java
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|ラベルの表示名<br>階層で親がある場合は、「/」でつなげた名前になる<br>例："親/子/孫"|
|setMessageListVisibility|[MessageListVisibility(enum)](#messagelistvisibility)|「メール リストに表示」の設定|
|setLabelListVisibility|[LabelListVisibility(enum)](#labellistvisibility)|「ラベル リストに表示」の設定|
|setType|[Type(enum)](#type)|所有者タイプ|
|setMessagesTotal|Integer|メッセージの総数|
|setMessagesUnread|Integer|未読メッセージの数|
|setThreadsTotal|Integer|スレッドの総数|
|setThreadsUnread|Integer|未読のスレッドの数|
|setColor|[Color](#color)|ラベルに割り当てる色|

#### 1.3. レスポンスの内容

#### Label

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

#### MessageListVisibility
Gmailのラベル設定メニューの「メール リストに表示」の内容です。
|定義値|内容|
|---|---|
|show|メールリストに表示|
|hide|メールリストに非表示|

#### LabelListVisibility
Gmailのラベル設定メニューの「ラベル リストに表示」の内容です。
|定義値|内容|
|---|---|
|labelShow|ラベルリストに表示|
|labelShowIfUnread|未読の場合はラベルリストに表示|
|labelHide|ラベルリストに非表示|

#### Type

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

#### Color

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

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

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

#### 2.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS
```
[⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)](https://qiita.com/doran/items/a078e966bfd93c4b19c2#22-gmailインスタンスを取得)
でスコープを指定してください。

#### 2.2. 実行
指定したラベルを更新します。

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

```java
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. リクエストボディ](#123-リクエストボディ)と同じです。

#### 2.3. レスポンスの内容

#### Label

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

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

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

#### 3.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS
```
[⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)](https://qiita.com/doran/items/a078e966bfd93c4b19c2#22-gmailインスタンスを取得)
でスコープを指定してください。

#### 3.2. 実行
指定したラベルを更新します。

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

```java
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. リクエストボディ](#123-リクエストボディ)と同じです。

#### 2.3. レスポンスの内容

#### Label

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

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

#### 4.1. スコープ
このAPIを実行するには、以下のいずれかのスコープを指定してください。
```
GmailScopes.MAIL_GOOGLE_COM
GmailScopes.GMAIL_MODIFY
GmailScopes.GMAIL_LABELS
```
[⧉[Gmail API] JavaでGmail APIを使う(2.2 Gmailインスタンスを取得)](https://qiita.com/doran/items/a078e966bfd93c4b19c2#22-gmailインスタンスを取得)
でスコープを指定してください。

#### 4.2. 実行
指定したラベルを削除します。

[Type](#type)が「user」のラベルのみ削除できます。

```java
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|プロモーション(カテゴリ)|

<br>
<br>
おしまい。。