> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/gmail.md).

# Gmail

{% hint style="info" %}
The following documentation is for **Gmail v2.10.1** *(BDK)*.
{% endhint %}

## Overview

Gmail is Google's comprehensive email service providing powerful messaging, organization, and collaboration features. This integration enables automated email sending, inbox management, message filtering, and email workflow automation. Streamline communication processes and enhance productivity through intelligent email automation.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Gmail**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

## Procedures

### to add a label to an (email)

Add a label to one or more emails.

**Input Concepts**

| Concept | Description                             | Type                                   | Required | Default Value |
| ------- | --------------------------------------- | -------------------------------------- | -------- | ------------- |
| `label` | The label to add.                       | `text`                                 | Yes      | (no default)  |
| `email` | the email or emails to add the label to | `gmail email` or `list of gmail email` | Yes      | (no default)  |

**Output Concepts**

| Concept | Description                                         | Type                                   |
| ------- | --------------------------------------------------- | -------------------------------------- |
| `email` | the email: The email or emails with the label added | `gmail email` or `list of gmail email` |

**Examples**

Add a label to emails

```generic
add a label to the email with
... the label is "IMPORTANT"
```

### to create a (draft email)

Create a draft email in Gmail without sending it.

Creates a new draft with the specified recipients, subject, and body. The draft is saved in the Drafts folder and can be sent later.

**Input Concepts**

| Concept                            | Description                                | Type                     | Required | Default Value |
| ---------------------------------- | ------------------------------------------ | ------------------------ | -------- | ------------- |
| `recipients`                       | The list of recipient email addresses.     | `list of text` or `text` | Yes      | (no default)  |
| `subject`                          | The subject line of the draft email.       | `text`                   | Yes      | (no default)  |
| `body`                             | The plain text content of the draft email. | `text`                   | No       | (no default)  |
| `html body`                        | The HTML content of the draft email.       | `text`                   | No       | (no default)  |
| `cc recipients`                    | Optional list of CC recipients.            | `list of text` or `text` | No       | (no default)  |
| `bcc recipients`                   | Optional list of BCC recipients.           | `list of text` or `text` | No       | (no default)  |
| [`attachments`](#gmail-attachment) | Optional list of file attachments.         | `gmail attachment`       | No       | (no default)  |

**Output Concepts**

| Concept                       | Description                               | Type          |
| ----------------------------- | ----------------------------------------- | ------------- |
| [`draft email`](#gmail-email) | the draft email: The created draft email. | `gmail email` |

**Examples**

Create a simple draft email

```generic
create a draft email with
... the recipients are ["recipient@example.com"]
... the subject is "Meeting Notes"
... the body is "Here are the notes from today's meeting."
```

Create a draft email with CC and BCC

```generic
create a draft email with
... the recipients are ["recipient@example.com"]
... the subject is "Project Update"
... the body is "Please review the project update."
... the cc recipients are ["manager@example.com"]
... the bcc recipients are ["archive@example.com"]
```

Create a draft email with an attachment

```generic
create a draft email with
... the recipients are ["recipient@example.com"]
... the subject is "Report"
... the body is "Please find the report attached."
... the attachments are [the attachment]
```

### to download an (email's attachments)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get an email attachment as an IO object.

**Input Concepts**

| Concept                 | Description                         | Type          | Required | Default Value |
| ----------------------- | ----------------------------------- | ------------- | -------- | ------------- |
| [`email`](#gmail-email) | The email containing the attachment | `gmail email` | Yes      | (no default)  |

**Output Concepts**

| Concept                                    | Description                    | Type               |
| ------------------------------------------ | ------------------------------ | ------------------ |
| [`email's attachments`](#gmail-attachment) | The attachment as an IO object | `gmail attachment` |

**Examples**

Download an attachment

```generic
download the attachment
```

### to forward an email

Forward an email to new recipients.

**Input Concepts**

| Concept                 | Description                                 | Type                     | Required | Default Value |
| ----------------------- | ------------------------------------------- | ------------------------ | -------- | ------------- |
| [`email`](#gmail-email) | The email to forward                        | `gmail email`            | Yes      | (no default)  |
| `recipients`            | The recipients to forward the email to      | `list of text` or `text` | Yes      | (no default)  |
| `body`                  | Optional additional message to include      | `text`                   | No       | (no default)  |
| `html body`             | Optional additional HTML message to include | `text`                   | No       | (no default)  |
| `cc recipients`         | Optional CC recipients                      | `list of text` or `text` | No       | (no default)  |
| `bcc recipients`        | Optional BCC recipients                     | `list of text` or `text` | No       | (no default)  |

**Output Concepts**

| Concept                  | Description    | Type          |
| ------------------------ | -------------- | ------------- |
| [`answer`](#gmail-email) | The sent email | `gmail email` |

**Examples**

Forward an email to someone

```generic
forward the email to "recipient@example.com"
```

Forward an email with additional message

```generic
forward the email to "recipient@example.com" with
... the body is "Please see the forwarded email below."
```

### to get some (label's emails)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get emails from a specified label in Gmail.

**Input Concepts**

| Concept            | Description                                          | Type     | Required | Default Value |
| ------------------ | ---------------------------------------------------- | -------- | -------- | ------------- |
| `label`            | The name of the label from which to retrieve emails. | `text`   | Yes      | (no default)  |
| `max result count` | Maximum number of emails to retrieve (default: 10).  | `number` | No       | 10            |

**Output Concepts**

| Concept                          | Description                                                                       | Type          |
| -------------------------------- | --------------------------------------------------------------------------------- | ------------- |
| [`label's emails`](#gmail-email) | the label's emails: List of GmailEmail objects representing the retrieved emails. | `gmail email` |

**Examples**

Retrieve all emails from inbox

```generic
get some "INBOX"'s emails
```

Retrieve emails with specific subject

```generic
get some "INBOX"'s emails whose subject is "Important Meeting"
```

### to get the (vacation responder)

Get the user's Gmail vacation responder (out-of-office auto-reply) configuration.

**Output Concepts**

| Concept                                     | Description                                                      | Type                 |
| ------------------------------------------- | ---------------------------------------------------------------- | -------------------- |
| [`vacation responder`](#vacation-responder) | the vacation responder: The current vacation responder settings. | `vacation responder` |

**Examples**

Check whether the out-of-office auto-reply is enabled

```generic
get the vacation responder
```

### to list (labels)

Get all labels from the user's Gmail account.

**Output Concepts**

| Concept  | Description           | Type   |
| -------- | --------------------- | ------ |
| `labels` | A list of all labels. | `text` |

**Examples**

List all labels

```generic
list labels
```

### to remove a label from an (email)

Remove a label from one or more emails.

**Input Concepts**

| Concept | Description                                   | Type                                   | Required | Default Value |
| ------- | --------------------------------------------- | -------------------------------------- | -------- | ------------- |
| `label` | The label to remove.                          | `text`                                 | Yes      | (no default)  |
| `email` | The email or emails to remove the label from. | `gmail email` or `list of gmail email` | Yes      | (no default)  |

**Output Concepts**

| Concept | Description                                           | Type                                   |
| ------- | ----------------------------------------------------- | -------------------------------------- |
| `email` | the email: The email or emails with the label removed | `gmail email` or `list of gmail email` |

**Examples**

Remove a label from an email

```generic
remove a label from the email with
... the label is "IMPORTANT"
```

### to reply an email

Reply to an email.

**Input Concepts**

| Concept                            | Description                                          | Type                     | Required | Default Value |
| ---------------------------------- | ---------------------------------------------------- | ------------------------ | -------- | ------------- |
| [`email`](#gmail-email)            | The email to reply to                                | `gmail email`            | Yes      | (no default)  |
| `body`                             | The body of the reply                                | `text`                   | No       | (no default)  |
| `html body`                        | The html body of the reply                           | `text`                   | No       | (no default)  |
| `additional recipients`            | Additional recipients to include in the reply        | `list of text` or `text` | No       | (no default)  |
| [`attachments`](#gmail-attachment) | Optional list of attachments to include in the reply | `gmail attachment`       | No       | (no default)  |

**Output Concepts**

| Concept                  | Description    | Type          |
| ------------------------ | -------------- | ------------- |
| [`answer`](#gmail-email) | The sent email | `gmail email` |

**Examples**

Reply to an email

```generic
reply to the email with
... the body is "This is a test reply"
```

### to send a (draft email)

Send an existing draft email.

Submits a previously saved draft for delivery. The draft is removed from the Drafts folder once sent. The input must be a draft email created by the create\_draft procedure.

**Input Concepts**

| Concept                       | Description                                      | Type          | Required | Default Value |
| ----------------------------- | ------------------------------------------------ | ------------- | -------- | ------------- |
| [`draft email`](#gmail-email) | The draft email to send (must have a draft\_id). | `gmail email` | Yes      | (no default)  |

**Output Concepts**

| Concept                       | Description                      | Type          |
| ----------------------------- | -------------------------------- | ------------- |
| [`draft email`](#gmail-email) | the draft email: The sent email. | `gmail email` |

**Examples**

Send a draft email

```generic
send a draft email with
... the draft email is the email
```

### to send an email

Send an email using Gmail API.

**Input Concepts**

| Concept                            | Description                            | Type                     | Required | Default Value |
| ---------------------------------- | -------------------------------------- | ------------------------ | -------- | ------------- |
| `recipients`                       | The list of recipient email addresses. | `list of text` or `text` | Yes      | (no default)  |
| `subject`                          | The subject line of the email.         | `text`                   | Yes      | (no default)  |
| `body`                             | The plain text content of the email.   | `text`                   | No       | (no default)  |
| `html body`                        | The HTML content of the email.         | `text`                   | No       | (no default)  |
| `cc recipients`                    | Optional list of CC recipients.        | `list of text` or `text` | No       | (no default)  |
| `bcc recipients`                   | Optional list of BCC recipients.       | `list of text` or `text` | No       | (no default)  |
| [`attachments`](#gmail-attachment) | Optional list of file attachments.     | `gmail attachment`       | No       | (no default)  |

**Output Concepts**

| Concept                  | Description    | Type          |
| ------------------------ | -------------- | ------------- |
| [`answer`](#gmail-email) | The sent email | `gmail email` |

**Examples**

Send a basic email

```generic
send an email with
... the recipients are ["recipient@example.com"]
... the subject is "Hello"
... the body is "This is a test email"
```

Send an email with CC and BCC

```generic
send an email with
... the recipients are ["recipient@example.com"]
... the subject is "Meeting Notes"
... the body is "Please find the meeting notes attached"
... the cc recipients are ["manager@example.com"]
... the bcc recipients are ["archive@example.com"]
```

### to update the (vacation responder)

Update the user's Gmail vacation responder (out-of-office auto-reply).

Set `enabled` to true to turn the auto-reply on, false to turn it off. Provide `subject` and `body` (and optionally `html body`) for the message. Optional `start time` and `end time` schedule when the responder is active. Optional `restrict to contacts` and `restrict to domain` limit who receives the auto-reply.

**Input Concepts**

| Concept                                     | Description                                    | Type                 | Required | Default Value |
| ------------------------------------------- | ---------------------------------------------- | -------------------- | -------- | ------------- |
| [`vacation responder`](#vacation-responder) | The vacation responder configuration to apply. | `vacation responder` | Yes      | (no default)  |

**Output Concepts**

| Concept                                     | Description                                                                           | Type                 |
| ------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------- |
| [`vacation responder`](#vacation-responder) | the vacation responder: The updated vacation responder settings as returned by Gmail. | `vacation responder` |

**Examples**

Turn on a simple out-of-office message

```generic
update the vacation responder with
... the enabled is true
... the subject is "Out of office"
... the body is "I am away and will reply when I am back."
```

Turn the vacation responder off

```generic
update the vacation responder with
... the enabled is false
```

## Concepts

### Gmail email

A Gmail Email represents an email message in Gmail.

| Field Name                                   | Description                                                | Type                                           |
| -------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `id`                                         | The unique identifier for the email.                       | `text`                                         |
| `thread_id`                                  | The unique identifier for the thread containing the email. | `text`                                         |
| [`labels`](#list-of-text)                    | The list of labels applied to the email.                   | `list of text`                                 |
| `state`                                      | The state of the email (draft, unread, or read).           | `text`                                         |
| `sender`                                     | The sender of the email.                                   | `text`                                         |
| [`recipients`](#list-of-text)                | The recipients of the email.                               | `list of text`                                 |
| `message_id`                                 | The unique identifier for the message.                     | `optional[text]`                               |
| `cc_recipients`                              | The cc recipients of the email.                            | `optional[list of text]`                       |
| `bcc_recipients`                             | The bcc recipients of the email.                           | `optional[list of text]`                       |
| [`attachments`](#gmail-attachment-reference) | The attachments of the email.                              | `optional[list of gmail attachment reference]` |
| `draft_id`                                   | The draft ID, if this email is a draft.                    | `optional[text]`                               |
| `subject`                                    | The subject of the email.                                  | `optional[text]`                               |
| `plain_body`                                 | The plain text body of the email.                          | `optional[text]`                               |
| `html_body`                                  | The html body of the email.                                | `optional[text]`                               |
| `sent_date_time`                             | The date and time the email was sent.                      | `optional[datetime]`                           |
| `received_date_time`                         | The date and time the email was received.                  | `optional[datetime]`                           |

### Gmail attachment reference

A Gmail Attachment Reference represents a reference to a file attached to an email in Gmail.

| Field Name  | Description                               | Type     |
| ----------- | ----------------------------------------- | -------- |
| `id`        | The unique identifier for the attachment. | `text`   |
| `email_id`  | The unique identifier for the email.      | `text`   |
| `file_name` | The name of the attachment.               | `text`   |
| `file_size` | The size of the file in bytes.            | `number` |

### Gmail attachment

A Gmail Attachment represents a file with name.

| Field Name  | Description                    | Type   |
| ----------- | ------------------------------ | ------ |
| `file_name` | The name of the attachment.    | `text` |
| `content`   | The content of the attachment. | `file` |

### Vacation responder

The Gmail vacation responder (out-of-office auto-reply) configuration.

| Field Name             | Description                                                           | Type                 |
| ---------------------- | --------------------------------------------------------------------- | -------------------- |
| `enabled`              | Whether the auto-reply is currently turned on.                        | `optional[boolean]`  |
| `subject`              | The subject line of the auto-reply.                                   | `optional[text]`     |
| `body`                 | The plain-text body of the auto-reply.                                | `optional[text]`     |
| `html_body`            | The HTML body of the auto-reply.                                      | `optional[text]`     |
| `restrict_to_contacts` | Whether to send the auto-reply only to people in the user's contacts. | `optional[boolean]`  |
| `restrict_to_domain`   | Whether to send the auto-reply only to people in the user's domain.   | `optional[boolean]`  |
| `start_time`           | When the auto-reply starts being active.                              | `optional[datetime]` |
| `end_time`             | When the auto-reply stops being active.                               | `optional[datetime]` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/reference/gmail.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.