GmailLabel

A user-created label in a user's Gmail account.

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#addToThread(GmailThread)` | `https://developers.google.com/apps-script/reference/gmail/gmail-label#` | Adds this label to the given thread and forces the thread to refresh (`https://developers.google.com/apps-script/reference/gmail/gmail-thread#refresh()`). |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#addToThreads(GmailThread)` | `https://developers.google.com/apps-script/reference/gmail/gmail-label#` | Adds this label to the given threads and forces the threads to refresh. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#deleteLabel()` | `void` | Deletes this label. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#getId()` | `String` | Gets the id of this label. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#getName()` | `String` | Gets the name of this label. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#getThreads()` | `https://developers.google.com/apps-script/reference/gmail/gmail-thread` | Gets the threads that are marked with this label. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#getThreads(Integer,Integer)` | `https://developers.google.com/apps-script/reference/gmail/gmail-thread` | Gets a range of threads marked with this label. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#getUnreadCount()` | `Integer` | Gets the number of unread threads tagged with this label. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#removeFromThread(GmailThread)` | `https://developers.google.com/apps-script/reference/gmail/gmail-label#` | Removes this label from the given thread and forces the thread to refresh. |
| `https://developers.google.com/apps-script/reference/gmail/gmail-label#removeFromThreads(GmailThread)` | `https://developers.google.com/apps-script/reference/gmail/gmail-label#` | Removes this label from the given threads and forces the threads to refresh. |

## Detailed documentation

### `addToThread(thread)`

Adds this label to the given thread and forces the thread to refresh (`https://developers.google.com/apps-script/reference/gmail/gmail-thread#refresh()`).

```javascript
// label the first thread in the inbox with the label MyLabel
const label = GmailApp.getUserLabelByName('MyLabel');
const firstThread = GmailApp.getInboxThreads(0, 1)[0];
label.addToThread(firstThread);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `thread` | `https://developers.google.com/apps-script/reference/gmail/gmail-thread` | The thread to be labeled. |

#### Return


`https://developers.google.com/apps-script/reference/gmail/gmail-label#` --- This label, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

#### See also

- `https://developers.google.com/apps-script/reference/gmail/gmail-label#removeFromThread(GmailThread)`

*** ** * ** ***

### `addToThreads(threads)`

Adds this label to the given threads and forces the threads to refresh. You can add labels for
up to 100 threads per batch.

```javascript
// label the first three threads in the inbox with the label MyLabel
const label = GmailApp.getUserLabelByName('MyLabel');
const threads = GmailApp.getInboxThreads(0, 3);
label.addToThreads(threads);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `threads` | `https://developers.google.com/apps-script/reference/gmail/gmail-thread` | An array of threads to be labeled. |

#### Return


`https://developers.google.com/apps-script/reference/gmail/gmail-label#` --- This label, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

#### See also

- `https://developers.google.com/apps-script/reference/gmail/gmail-label#removeFromThreads(GmailThread)`

*** ** * ** ***

### `deleteLabel()`

Deletes this label.

```javascript
const label = GmailApp.getUserLabelByName('MyLabel');
label.deleteLabel();
```

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) --- if the label can't be deleted

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

#### See also

- `https://developers.google.com/apps-script/reference/gmail/gmail-label#getName()`

*** ** * ** ***

### `getId()`

Gets the id of this label.

```javascript
const label = GmailApp.getUserLabelByName('MyLabel');
console.log(label.getId());
```

#### Return


`String` --- The id of the label.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

*** ** * ** ***

### `getName()`

Gets the name of this label.

```javascript
const label = GmailApp.getUserLabelByName('MyLabel');
Logger.log(label.getName());  // logs MyLabel
```

#### Return


`String` --- The name of the label.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

*** ** * ** ***

### `getThreads()`

Gets the threads that are marked with this label.

This calls fail when the size of all threads is too large for the system to handle. Where
the thread size is unknown, and potentially very large, please use `https://developers.google.com/apps-script/reference/gmail/gmail-label#getThreads(Integer,Integer)` and specify ranges of the threads to retrieve in each call.

```javascript
// Log the subject lines of the threads labeled with MyLabel
const label = GmailApp.getUserLabelByName('MyLabel');
const threads = label.getThreads();
for (let i = 0; i < threads.length; i++) {
  Logger.log(threads[i].getFirstMessageSubject());
}
```

#### Return


`https://developers.google.com/apps-script/reference/gmail/gmail-thread` --- An array of threads marked with this label.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

*** ** * ** ***

### `getThreads(start, max)`

Gets a range of threads marked with this label.

```javascript
// log the subject lines of up to the first 30 threads with the label MyLabel
const label = GmailApp.getUserLabelByName('MyLabel');
const threads = label.getThreads(0, 30);
for (let i = 0; i < threads.length; i++) {
  Logger.log(threads[i].getFirstMessageSubject());
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `start` | `Integer` | The index of the starting thread. |
| `max` | `Integer` | The maximum number of threads to return. |

#### Return


`https://developers.google.com/apps-script/reference/gmail/gmail-thread` --- An array of threads marked with this label.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

*** ** * ** ***

### `getUnreadCount()`

Gets the number of unread threads tagged with this label.

```javascript
// log the number of unread threads labeled with MyLabel
const label = GmailApp.getUserLabelByName('MyLabel');
Logger.log(label.getUnreadCount());
```

#### Return


`Integer` --- The number of unread labeled threads.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

*** ** * ** ***

### `removeFromThread(thread)`

Removes this label from the given thread and forces the thread to refresh.

```javascript
// remove the label MyLabel from the first thread in the inbox
const label = GmailApp.getUserLabelByName('MyLabel');
const firstThread = GmailApp.getInboxThreads(0, 1)[0];
label.removeFromThread(firstThread);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `thread` | `https://developers.google.com/apps-script/reference/gmail/gmail-thread` | The thread be unlabeled. |

#### Return


`https://developers.google.com/apps-script/reference/gmail/gmail-label#` --- This label, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

#### See also

- `https://developers.google.com/apps-script/reference/gmail/gmail-label#addToThread(GmailThread)`

*** ** * ** ***

### `removeFromThreads(threads)`

Removes this label from the given threads and forces the threads to refresh. You can remove
labels for up to 100 threads per batch.

```javascript
// remove the label MyLabel from the first three threads in the inbox
const label = GmailApp.getUserLabelByName('MyLabel');
const threads = GmailApp.getInboxThreads(0, 3);
label.removeFromThreads(threads);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `threads` | `https://developers.google.com/apps-script/reference/gmail/gmail-thread` | An array of threads to be unlabeled. |

#### Return


`https://developers.google.com/apps-script/reference/gmail/gmail-label#` --- This label, for chaining.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes) or appropriate scopes from the [related REST API](https://developers.google.com/identity/protocols/googlescopes#gmailv1):

- `https://mail.google.com/`

#### See also

- `https://developers.google.com/apps-script/reference/gmail/gmail-label#addToThreads(GmailThread)`