> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agent-auth`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Gmail

<div class="grid grid-cols-5 gap-4 items-center">
 <div class="col-span-4">
  Gmail is Google's cloud based email service that allows you to access your messages from any computer or device with just a web browser.
 </div>
 <div class="flex justify-center">
  <img src="https://cdn.scalekit.com/sk-connect/assets/provider-icons/gmail.svg" width="64" height="64" alt="Gmail logo" />
 </div>
</div>

Supports authentication: OAuth 2.0

## Set up the agent connector

<SetupGmailSection />

## Usage

<UsageGmailSection />

## Tool list

## `gmail_fetch_mails`

Fetch emails from a connected Gmail account using search filters. Requires a valid Gmail OAuth2 connection.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | No | Format of the returned message. |
| `include_spam_trash` | boolean | No | Whether to fetch emails from spam and trash folders |
| `label_ids` | `array<string>` | No | Gmail label IDs to filter messages |
| `max_results` | integer | No | Maximum number of emails to fetch |
| `page_token` | string | No | Page token for pagination |
| `query` | string | No | Search query string using Gmail's search syntax (e.g., 'is:unread from:user@example.com') |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_get_attachment_by_id`

Retrieve a specific attachment from a Gmail message using the message ID and attachment ID.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `attachment_id` | string | Yes | Unique Gmail attachment ID |
| `file_name` | string | No | Preferred filename to use when saving/returning the attachment |
| `message_id` | string | Yes | Unique Gmail message ID that contains the attachment |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_get_contacts`

Fetch a list of contacts from the connected Gmail account. Supports pagination and field filtering.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `max_results` | integer | No | Maximum number of contacts to fetch |
| `page_token` | string | No | Token to retrieve the next page of results |
| `person_fields` | `array<string>` | No | Fields to include for each person |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_get_message_by_id`

Retrieve a specific Gmail message using its message ID. Optionally control the format of the returned data.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | No | Format of the returned message. |
| `message_id` | string | Yes | Unique Gmail message ID |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_get_thread_by_id`

Retrieve a specific Gmail thread by thread ID. Optionally control message format and metadata headers. Requires a valid Gmail OAuth2 connection with read access.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | No | Format of messages in the returned thread. |
| `metadata_headers` | `array<string>` | No | Specific email headers to include when format is metadata |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `thread_id` | string | Yes | Unique Gmail thread ID |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_list_drafts`

List draft emails from a connected Gmail account. Requires a valid Gmail OAuth2 connection.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `max_results` | integer | No | Maximum number of drafts to fetch |
| `page_token` | string | No | Page token for pagination |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_list_threads`

List threads in a connected Gmail account using optional search and label filters. Requires a valid Gmail OAuth2 connection with read access.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `include_spam_trash` | boolean | No | Whether to include threads from Spam and Trash |
| `label_ids` | `array<string>` | No | Gmail label IDs to filter threads (threads must match all labels) |
| `max_results` | integer | No | Maximum number of threads to return |
| `page_token` | string | No | Page token for pagination |
| `query` | string | No | Search query string using Gmail search syntax (for example, 'is:unread from:user@example.com') |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

## `gmail_search_people`

Search people or contacts in the connected Google account using a query. Requires a valid Google OAuth2 connection with People API scopes.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `other_contacts` | boolean | No | Whether to include people not in the user's contacts (from 'Other Contacts'). |
| `page_size` | integer | No | Maximum number of people to return. |
| `person_fields` | `array<string>` | No | Fields to retrieve for each person. |
| `query` | string | Yes | Text query to search people (e.g., name, email address). |
| `schema_version` | string | No | Optional schema version to use for tool execution |
| `tool_version` | string | No | Optional tool version to use for execution |

---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |