# Gmail

{% hint style="info" %}
The following documentation is for **Gmail v2.0.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 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 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 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"]
```

## 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]` |
| `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` |