> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail integration

[Back to list of integrations](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems.md)

Use the Gmail integration to let agents send, reply to, draft, find, and read email, and request approvals by email, through Action Tools.

| Authentication | Actions | Triggers |
| - | - | - |
| OAuth 2.0 | ([7](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems/gmail-integrations#supported-actions)) | ([4](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems/gmail-integrations#triggers)) |

## Supported actions

| Action | Use it to |
| - | - |
| [Send Email](#send-email) | Send an email, or save it as a draft. |
| [Request Approval in Email](#request-approval-in-email) | Send an approval request and wait for the recipient to approve or reject it. |
| [Reply to Email](#reply-to-email) | Reply to the sender or to all recipients of a message. |
| [Create Draft Reply](#create-draft-reply) | Save a reply as a draft without sending it. |
| [Get Email](#get-email) | Read a message by its ID. |
| [Find Email](#find-email) | Search messages by sender, recipient, subject, content, label, category, date, or attachment. |
| [Custom API Call](#custom-api-call) | Call any Gmail API endpoint the other actions don't cover. |

## Triggers

| Trigger | Fires when |
| - | - |
| New Email | New mail arrives in the inbox. |
| New Labeled Email | A label is added to an email. |
| New Attachment | An email with an attachment arrives. |
| New Label | A new label is created. |

## Prerequisites

* A Google Cloud project with the **Gmail API** enabled and an OAuth consent screen. In **Testing** status, only test users can authorize and refresh tokens expire after seven days.

## Set up the integration

**1. Create a Google OAuth client**

Create an OAuth client ID of type **Web application**, add the Artemis **Callback URL** to **Authorized redirect URIs**, and copy the **Client ID** and **Client Secret**. See [Using OAuth 2.0 to access Google APIs](https://developers.google.com/identity/protocols/oauth2).

**2. Create the auth profile**

In **Integrations**, select **Gmail** > **Connect**. On **Project Auth Profiles**, select **New Profile** > **Integration Profile** > **Gmail** > **Continue**. Enter the **Client ID** and **Client Secret**, select **Create Profile**, and then select **Authorize**.

Artemis pre-fills the Google endpoints, the `access_type=offline` and `prompt=consent` parameters, and these scopes: `gmail.send`, `gmail.readonly`, `gmail.compose`, and `email`. Add the same scopes to the consent screen.

**Usage Mode**: **Preconfigured** shares one authorization across users; **JIT** and **Preflight** ask each user to authorize, during or before the session. See [Auth profiles](https://koreai.mintlify.site/agent-platform/administration/integrations-settings.md#auth-profiles).

**3. Create the action tool**

In **Tools**, select **New Tool** > **Action** > **Gmail** > **Continue**. Select the **Action** and **Auth Profile**, set parameter defaults (leave a value empty for the agent to supply at runtime), and select **Create Tool**. Then [assign the tool to an agent](https://koreai.mintlify.site/agent-platform/tools/actions.md#assign-an-action-to-an-agent).

## Action reference

> [accordion] Send Email
>
> | Parameter | Type | Description |
> | - | - | - |
> | `receiver` | array | Recipient addresses (To). |
> | `cc` | array | Carbon copy recipients. |
> | `bcc` | array | Blind carbon copy recipients. |
> | `subject` | string | Subject line. |
> | `body_type` | enum | Body type. Default: `plain text`. |
> | `body` | string | Message body. |
> | `reply_to` | array | Addresses for the Reply-To header. |
> | `sender_name` | string | Display name of the sender. |
> | `from` | string | Sender address. Must be listed in the Gmail account's **Send mail as** settings. |
> | `attachments` | array | Attachments. |
> | `in_reply_to` | string | Message-ID to reply to, which threads the message. |
> | `draft` | boolean | Saves a draft without sending. Default: `False`. |

> [accordion] Request Approval in Email
>
> Sends the request and pauses the tool until the recipient approves or rejects it.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `receiver` | string | Approver's email address. |
> | `cc` | array | Carbon copy recipients. |
> | `bcc` | array | Blind carbon copy recipients. |
> | `subject` | string | Subject of the approval request. |
> | `body` | string | Message body. |
> | `reply_to` | array | Addresses for the Reply-To header. |
> | `sender_name` | string | Display name of the sender. |
> | `from` | string | Sender address. Must be listed in the Gmail account's settings. |
> | `in_reply_to` | string | Message-ID to reply to. |

> [accordion] Reply to Email
>
> | Parameter | Type | Description |
> | - | - | - |
> | `message_id` | enum | Message to reply to. Select from the list or enter an ID. |
> | `reply_type` | enum | Reply to the sender only or to all recipients. Default: `Reply (to sender only)`. |
> | `body_type` | enum | Body type. Default: `Plain text`. |
> | `body` | string | Reply content. |
> | `sender_name` | string | Optional sender display name. |
> | `attachment` | string | Optional file to attach. |
> | `attachment_name` | string | Custom name for the attachment. |

> [accordion] Create Draft Reply
>
> | Parameter | Type | Description |
> | - | - | - |
> | `message_id` | enum | Message to reply to. Select from the list or enter an ID. |
> | `reply_type` | enum | Reply to the sender only or to all recipients. Default: `Reply (to sender only)`. |
> | `body_type` | enum | Body type. Default: `Plain text`. |
> | `body` | string | Draft reply content. |
> | `include_original_message` | boolean | Quotes the original message in the draft. Default: `True`. |
> | `sender_name` | string | Optional sender display name. |
> | `attachment` | string | Optional file to attach. |
> | `attachment_name` | string | Custom name for the attachment. |

> [accordion] Get Email
>
> | Parameter | Type | Description |
> | - | - | - |
> | `message_id` | string | ID of the message to read. |

> [accordion] Find Email
>
> Provide at least one search filter.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `from` | string | Sender filter. |
> | `to` | string | Recipient filter. |
> | `subject` | string | Subject filter. |
> | `content` | string | Text in the message body. |
> | `has_attachment` | boolean | Returns only messages with attachments. Default: `False`. |
> | `attachment_name` | string | Attachment file name. |
> | `label` | enum | Label filter. |
> | `category` | enum | Category filter. |
> | `after_date` | string | Returns messages sent after this date. |
> | `before_date` | string | Returns messages sent before this date. |
> | `include_spam_trash` | boolean | Includes Spam and Trash. Default: `False`. |
> | `max_results` | number | Maximum results, from 1 to 500. |

> [accordion] Custom API Call
>
> Sends a request to any Gmail API endpoint. Artemis injects the authorization header from the auth profile.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `url` | object | Endpoint URL. |
> | `method` | enum | HTTP method. |
> | `headers` | object | Additional request headers. |
> | `queryParams` | object | Query parameters. |
> | `body_type` | enum | Body type. Default: `None`. |
> | `body` | object | Request body. |
> | `response_is_binary` | boolean | Turn on for binary responses, such as PDFs or images. Default: `False`. |
> | `failsafe` | boolean | Returns no error when the call fails. |
> | `timeout` | number | Timeout, in seconds. |
> | `followRedirects` | boolean | Follows HTTP redirects. Default: `False`. |

## Troubleshoot common issues

| Issue | Resolution |
| - | - |
| `redirect_uri_mismatch` during authorization | Add the exact **Callback URL** to the OAuth client's **Authorized redirect URIs**. |
| `access_denied` or the app isn't verified | Add the user as a test user, or publish the consent screen. |
| The profile stops working after seven days | The consent screen is in **Testing** status. Publish the app, and then authorize again. |
| `403 Insufficient Permission` | Confirm the profile's scopes cover the action, and then authorize again. |
| Email sends from the wrong address | Set `from` to an address listed in the account's **Send mail as** settings. |
| **Find Email** returns an error | Provide at least one search filter. |

## Related articles

* [Auth profiles](https://koreai.mintlify.site/agent-platform/administration/integrations-settings.md#auth-profiles)
* [Action Tools](https://koreai.mintlify.site/agent-platform/tools/actions.md)
* [Gmail API documentation](https://developers.google.com/gmail/api/guides)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.