Gmail | Composio Docs

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

OAuth2

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

Bearer Token

token

stringRequired

Tools

Delete Draft

SLUG: GMAIL_DELETE_DRAFT

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

Delete message

SLUG: GMAIL_DELETE_MESSAGE

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

Fetch emails

SLUG: GMAIL_FETCH_EMAILS

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

Fetch message by message ID

SLUG: GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID

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

Get Gmail attachment

SLUG: GMAIL_GET_ATTACHMENT

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

Get contacts

SLUG: GMAIL_GET_CONTACTS

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

List drafts

SLUG: GMAIL_LIST_DRAFTS

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

Move to Trash

SLUG: GMAIL_MOVE_TO_TRASH

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

Patch Label

SLUG: GMAIL_PATCH_LABEL

Patches the specified label.

Action Parameters

color

object

stringRequired

labelListVisibility

string

messageListVisibility

string

name

string

userId

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

Reply to email thread

SLUG: GMAIL_REPLY_TO_THREAD

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

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

Search People

SLUG: GMAIL_SEARCH_PEOPLE

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

Send Draft

SLUG: GMAIL_SEND_DRAFT

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

Send Email

SLUG: GMAIL_SEND_EMAIL

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

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

Modify email labels

SLUG: GMAIL_ADD_LABEL_TO_EMAIL

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

Create email draft

SLUG: GMAIL_CREATE_EMAIL_DRAFT

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

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

Create label

SLUG: GMAIL_CREATE_LABEL

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

Fetch Message by Thread ID

SLUG: GMAIL_FETCH_MESSAGE_BY_THREAD_ID

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

Get People

SLUG: GMAIL_GET_PEOPLE

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

Get Profile

SLUG: GMAIL_GET_PROFILE

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

List Gmail labels

SLUG: GMAIL_LIST_LABELS

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

List threads

SLUG: GMAIL_LIST_THREADS

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

Modify thread labels

SLUG: GMAIL_MODIFY_THREAD_LABELS

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

Remove label

SLUG: GMAIL_REMOVE_LABEL

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