Important

Gmail

Learn how to use Gmail with Composio

Overview

SLUG: GMAIL

Description

Gmail is Google’s email service, featuring spam protection, search functions, and seamless integration with other G Suite apps for productivity

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
stringDefaults to https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/userinfo.profile,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/contacts.readonly,https://www.googleapis.com/auth/profile.language.read,https://www.googleapis.com/auth/user.addresses.read,https://www.googleapis.com/auth/user.birthday.read,https://www.googleapis.com/auth/user.emails.read,https://www.googleapis.com/auth/user.phonenumbers.read,https://www.googleapis.com/auth/profile.emails.read
bearer_token
string
token
stringRequired

Connecting to Gmail

Create an auth config

Use the dashboard to create an auth config for the Gmail toolkit. This allows you to connect multiple Gmail accounts to Composio for agents to use.

1

Select App

Navigate to the Gmail toolkit page and click “Setup Integration”.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Integration”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2
3# Replace these with your actual values
4gmail_auth_config_id = "ac_YOUR_GMAIL_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000"  # UUID from database/application
6
7composio = Composio()
8
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11    connection_request = composio.connected_accounts.initiate(
12        user_id=user_id,
13        auth_config_id=auth_config_id,
14    )
15
16    print(
17        f"Visit this URL to authenticate Gmail: {connection_request.redirect_url}"
18    )
19
20    # This will wait for the auth flow to be completed
21    connection_request.wait_for_connection(timeout=15)
22    return connection_request.id
23
24
25connection_id = authenticate_toolkit(user_id, gmail_auth_config_id)
26
27# You can also verify the connection status using:
28connected_account = composio.connected_accounts.get(connection_id)
29print(f"Connected account: {connected_account}")

Using Bearer Token

1from composio import Composio
2
3# Auth config ID created above
4gmail_auth_config_id = "ac_YOUR_GMAIL_CONFIG_ID" 
5
6# UUID from database/application
7user_id = "0000-0000-0000"
8
9composio = Composio()
10
11
12def authenticate_toolkit(user_id: str, auth_config_id: str):
13    # Replace this with a method to retrieve the Bearer Token from the user.
14    bearer_token = input("[!] Enter bearer token")
15    connection_request = composio.connected_accounts.initiate(
16        user_id=user_id,
17        auth_config_id=auth_config_id,
18        config={"auth_scheme": "BEARER_TOKEN", "val": bearer_token}
19    )
20    print(f"Successfully connected Gmail for user {user_id}")
21    print(f"Connection status: {connection_request.status}")
22    
23    return connection_request.id
24
25
26connection_id = authenticate_toolkit(user_id, gmail_auth_config_id)
27
28# You can verify the connection using:
29connected_account = composio.connected_accounts.get(connection_id)
30print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Gmail toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["GMAIL"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Create email draft

Description

Creates a gmail email draft, supporting to/cc/bcc, subject, plain/html body (ensure `is html=true` for html), attachments, and threading.

Action Parameters

attachment
object
bcc
array
body
stringRequired
cc
array
extra_recipients
array
is_html
boolean
recipient_email
stringRequired
subject
stringRequired
thread_id
string
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Draft

Description

Permanently deletes a specific gmail draft using its id; ensure the draft exists and the user has necessary permissions for the given `user id`.

Action Parameters

draft_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete message

Description

Permanently deletes a specific email message by its id from a gmail mailbox; for `user id`, use 'me' for the authenticated user or an email address to which the authenticated user has delegated access.

Action Parameters

message_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch emails

Description

Fetches a list of email messages from a gmail account, supporting filtering, pagination, and optional full content retrieval.

Action Parameters

ids_only
boolean
include_payload
booleanDefaults to True
include_spam_trash
boolean
label_ids
array
max_results
integerDefaults to 1
page_token
string
query
string
user_id
stringDefaults to me
verbose
booleanDefaults to True

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch message by message ID

Description

Fetches a specific email message by its id, provided the `message id` exists and is accessible to the authenticated `user id`.

Action Parameters

format
stringDefaults to full
message_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Gmail attachment

Description

Retrieves a specific attachment by id from a message in a user's gmail mailbox, requiring valid message and attachment ids.

Action Parameters

attachment_id
stringRequired
file_name
stringRequired
message_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get contacts

Description

Fetches contacts (connections) for the authenticated google account, allowing selection of specific data fields and pagination.

Action Parameters

page_token
string
person_fields
stringDefaults to emailAddresses,names,birthdays,genders
resource_name
stringDefaults to people/me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List drafts

Description

Retrieves a paginated list of email drafts from a user's gmail account. use verbose=true to get full draft details including subject, body, sender, and timestamp.

Action Parameters

max_results
integerDefaults to 1
page_token
string
user_id
stringDefaults to me
verbose
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Move to Trash

Description

Moves an existing, non-deleted email message to the trash for the specified user.

Action Parameters

message_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Patch Label

Description

Patches the specified label.

Action Parameters

color
object
id
stringRequired
labelListVisibility
string
messageListVisibility
string
name
string
userId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Reply to email thread

Description

Sends a reply within a specific gmail thread using the original thread's subject, requiring a valid `thread id` and correctly formatted email addresses. supports attachments via the `attachment` parameter with valid `s3key`, `mimetype`, and `name`.

Action Parameters

attachment
object
bcc
array
cc
array
extra_recipients
array
is_html
boolean
message_body
stringRequired
recipient_email
stringRequired
thread_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search People

Description

Searches contacts by matching the query against names, nicknames, emails, phone numbers, and organizations, optionally including 'other contacts'.

Action Parameters

other_contacts
boolean
pageSize
integerDefaults to 10
person_fields
stringDefaults to emailAddresses,names,phoneNumbers
query
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send Draft

Description

Sends the specified, existing draft to the recipients in the to, cc, and bcc headers.

Action Parameters

draft_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send Email

Description

Sends an email via gmail api using the authenticated user's google profile display name, requiring `is html=true` if the body contains html and valid `s3key`, `mimetype`, `name` for any attachment.

Action Parameters

attachment
object
bcc
array
body
stringRequired
cc
array
extra_recipients
array
is_html
boolean
recipient_email
stringRequired
subject
string
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Modify email labels

Description

Adds and/or removes specified gmail labels for a message; ensure `message id` and all `label ids` are valid (use 'listlabels' for custom label ids).

Action Parameters

add_label_ids
array
message_id
stringRequired
remove_label_ids
array
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create label

Description

Creates a new label with a unique name in the specified user's gmail account.

Action Parameters

label_list_visibility
stringDefaults to labelShow
label_name
stringRequired
message_list_visibility
stringDefaults to show
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Fetch Message by Thread ID

Description

Retrieves messages from a gmail thread using its `thread id`, where the thread must be accessible by the specified `user id`.

Action Parameters

page_token
string
thread_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get People

Description

Retrieves either a specific person's details (using `resource name`) or lists 'other contacts' (if `other contacts` is true), with `person fields` specifying the data to return.

Action Parameters

other_contacts
boolean
page_size
integerDefaults to 10
page_token
string
person_fields
stringDefaults to emailAddresses,names,birthdays,genders
resource_name
stringDefaults to people/me
sync_token
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Profile

Description

Retrieves key gmail profile information (email address, message/thread totals, history id) for a user.

Action Parameters

user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Gmail labels

Description

Retrieves a list of all system and user-created labels for the specified gmail account.

Action Parameters

user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List threads

Description

Retrieves a list of email threads from a gmail account, identified by `user id` (email address or 'me'), supporting filtering and pagination.

Action Parameters

max_results
integerDefaults to 10
page_token
string
query
string
user_id
stringDefaults to me
verbose
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Modify thread labels

Description

Adds or removes specified existing label ids from a gmail thread, affecting all its messages; ensure the thread id is valid.

Action Parameters

add_label_ids
array
remove_label_ids
array
thread_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Remove label

Description

Permanently deletes a specific, existing user-created gmail label by its id for a user; cannot delete system labels.

Action Parameters

label_id
stringRequired
user_id
stringDefaults to me

Action Response

data
objectRequired
error
string
successful
booleanRequired