Gmail — Email

Get profile — gmail.get_profile

Gets the Gmail profile for the connected account, including emailAddress and mailbox totals. Use this to confirm which mailbox is linked before reading or sending mail.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

No input.

Extra fields: ignored.

Output

Field	Type	Description
emailAddress	string
messagesTotal	integer
threadsTotal	integer
historyId	string

List labels — gmail.list_labels

Lists Gmail labels for the connected account (id, name, type, visibility). Call this before modify_message_labels or create_label to resolve label ids. System labels like INBOX and UNREAD are included.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

No input.

Extra fields: ignored.

Output

Field	Type	Description
labels	array of object
labels[].id	string
labels[].name	string
labels[].type	string
labels[].messageListVisibility	string
labels[].labelListVisibility	string

Fetch emails — gmail.fetch_emails

Fetches a list of Gmail messages for the connected account. Supports Gmail search q, max_results, page_token, and label_ids. Use this to find candidates; call get_message or get_thread for full content.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
q	string	no	Gmail search query, same syntax as the Gmail search box, e.g. "from:anna is:unread".
max_results	integer	no	Max messages to return (1-500). Defaults to 100.
page_token	string	no	Token for the next page. From nextPageToken of the previous gmail.fetch_emails call.
label_ids	array of string	no	Only return messages that have all of these label ids, e.g. ["INBOX", "UNREAD"]. From gmail.list_labels.

Extra fields: sent as query parameters.

Output

Field	Type	Description
messages	array of object	List entries contain only id + threadId; use get_message for full content.
messages[].id	string
messages[].threadId	string
nextPageToken	string
resultSizeEstimate	integer

Get message — gmail.get_message

Fetches a single Gmail message by message_id. Prefer get_thread when the agent needs the full conversation context. Obtain ids via fetch_emails or list_threads.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
message_id	string	yes	Id of the message to fetch. From gmail.fetch_emails or gmail.get_thread.
format	string	no	How much of the message to return; raw gives the base64url MIME in raw. Defaults to full. One of: minimal, full, raw, metadata.

Extra fields: sent as query parameters.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string
snippet	string
historyId	string
internalDate	string
sizeEstimate	integer
payload	object
raw	string

Get thread — gmail.get_thread

Fetches a Gmail thread by thread_id, including messages in that conversation. Prefer this over get_message when the agent needs full reply context. Use list_threads or fetch_emails first if the id is unknown.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
thread_id	string	yes	Id of the thread to fetch. From gmail.list_threads or gmail.fetch_emails (threadId).
format	string	no	How much of each message to return. Defaults to full. One of: full, metadata, minimal.

Extra fields: sent as query parameters.

Output

Field	Type	Description
id	string
snippet	string
historyId	string
messages	array of object
messages[].id	string
messages[].threadId	string
messages[].labelIds	array of string
messages[].snippet	string

List threads — gmail.list_threads

Lists Gmail conversation threads for the connected account. Supports Gmail search q, max_results, page_token, and label_ids. Listed threads omit messages — call get_thread for full conversation content.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
q	string	no	Gmail search query, same syntax as the Gmail search box, e.g. "from:anna is:unread".
max_results	integer	no	Max threads to return (1-500). Defaults to 100.
page_token	string	no	Token for the next page. From nextPageToken of the previous gmail.list_threads call.
label_ids	array of string	no	Only return threads that have all of these label ids, e.g. ["INBOX", "UNREAD"]. From gmail.list_labels.

Extra fields: sent as query parameters.

Output

Field	Type	Description
threads	array of object	List entries omit messages; use get_thread for full content.
threads[].id	string
threads[].snippet	string
threads[].historyId	string
nextPageToken	string
resultSizeEstimate	integer

Get attachment — gmail.get_attachment

Downloads a Gmail message attachment by message_id and attachment_id. Obtain attachment_id from get_message payload parts. Returns base64url-encoded data and byte size.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
message_id	string	yes	Id of the message that has the attachment. From gmail.fetch_emails or gmail.get_thread.
attachment_id	string	yes	Id of the attachment. From gmail.get_message (payload.parts[].body.attachmentId).

Extra fields: ignored.

Output

Field	Type	Description
attachmentId	string
size	integer
data	string

List drafts — gmail.list_drafts

Lists Gmail drafts for the connected account. Supports optional q, max_results, and page_token. Listed drafts only include message id/threadId — call get_draft for content.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
q	string	no	Only return drafts matching this Gmail search query, e.g. "subject:invoice".
max_results	integer	no	Max drafts to return (1-500). Defaults to 100.
page_token	string	no	Token for the next page. From nextPageToken of the previous gmail.list_drafts call.

Extra fields: sent as query parameters.

Output

Field	Type	Description
drafts	array of object
drafts[].id	string
drafts[].message	object
drafts[].message.id	string
drafts[].message.threadId	string
nextPageToken	string
resultSizeEstimate	integer

Get draft — gmail.get_draft

Fetches a single Gmail draft by draft_id, including its message payload. Use list_drafts to discover ids. Prefer get_draft before send_draft or update_draft so the agent reviews current content.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	https://www.googleapis.com/auth/gmail.readonly

Input

Field	Type	Required	Description
draft_id	string	yes	Id of the draft to fetch. From gmail.list_drafts.
format	string	no	How much of the draft message to return. Defaults to full. One of: minimal, full, raw, metadata.

Extra fields: sent as query parameters.

Output

Field	Type	Description
id	string
message	object
message.id	string
message.threadId	string
message.labelIds	array of string
message.snippet	string

Create draft — gmail.create_draft

Creates a Gmail draft with to, subject, and body. Does not send mail — use send_draft after review, or send_email for immediate send. Optional thread_id attaches the draft to an existing conversation.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	no	https://www.googleapis.com/auth/gmail.compose

Input

Field	Type	Required	Description
to	string	yes	Recipient email address; separate several with commas, e.g. "anna@example.com, bob@example.com".
subject	string	yes	Email subject line.
body	string	yes	Email body as plain text (HTML tags are not rendered).
thread_id	string	no	Thread to put this in; Subject must match the thread's subject. From gmail.list_threads or gmail.fetch_emails (threadId).
cc	string	no	CC email addresses, comma-separated.
bcc	string	no	BCC email addresses, comma-separated.

Extra fields: ignored.

Output

Field	Type	Description
id	string
message	object
message.id	string
message.threadId	string
message.labelIds	array of string
message.snippet	string

Approval card: shown as email (to → to, cc → cc, bcc → bcc, subject → subject, body → body).

Update draft — gmail.update_draft

Replaces an existing Gmail draft identified by draft_id with new to, subject, and body. Does not send mail. Call get_draft first if the agent needs the prior content.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	no	https://www.googleapis.com/auth/gmail.compose

Input

Field	Type	Required	Description
draft_id	string	yes	Id of the draft to replace. From gmail.list_drafts.
to	string	yes	New recipient email address; separate several with commas. Replaces the draft's recipients.
subject	string	yes	New subject line; replaces the draft's subject.
body	string	yes	New body as plain text; replaces the draft's whole body.
thread_id	string	no	Thread to put this in; Subject must match the thread's subject. From gmail.list_threads or gmail.fetch_emails (threadId).
cc	string	no	New CC email addresses, comma-separated. Leave empty to drop CC.
bcc	string	no	New BCC email addresses, comma-separated. Leave empty to drop BCC.

Extra fields: ignored.

Output

Field	Type	Description
id	string
message	object
message.id	string
message.threadId	string
message.labelIds	array of string
message.snippet	string

Approval card: shown as email (to → to, cc → cc, bcc → bcc, subject → subject, body → body).

Send draft — gmail.send_draft

Sends an existing Gmail draft as-is by draft_id. This delivers email to recipients already on the draft — irreversible from the agent. Prefer create_draft + human review before send_draft.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	https://www.googleapis.com/auth/gmail.send

Input

Field	Type	Required	Description
draft_id	string	yes	Id of the draft to send. From gmail.list_drafts or gmail.create_draft.

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Send email — gmail.send_email

Sends a new Gmail message with to, subject, and body immediately. This delivers mail to recipients — irreversible from the agent. Prefer create_draft + send_draft when human review is needed first.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	https://www.googleapis.com/auth/gmail.send

Input

Field	Type	Required	Description
to	string	yes	Recipient email address; separate several with commas, e.g. "anna@example.com, bob@example.com".
subject	string	yes	Email subject line.
body	string	yes	Email body as plain text (HTML tags are not rendered).
cc	string	no	CC email addresses, comma-separated.
bcc	string	no	BCC email addresses, comma-separated.
thread_id	string	no	Thread to put this in; Subject must match the thread's subject. From gmail.list_threads or gmail.fetch_emails (threadId).

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Approval card: shown as email (to → to, cc → cc, bcc → bcc, subject → subject, body → body).

Reply to thread — gmail.reply_to_thread

Sends a reply into an existing Gmail thread by thread_id with to, subject, and body. This delivers mail — irreversible from the agent; prefer draft review when unsure.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	https://www.googleapis.com/auth/gmail.send

Input

Field	Type	Required	Description
thread_id	string	yes	Id of the thread to reply in. From gmail.list_threads or gmail.fetch_emails (threadId).
body	string	yes	Reply text as plain text (HTML tags are not rendered).
to	string	yes	Who gets the reply, usually the original sender; separate several with commas.
subject	string	yes	Reply subject; match the thread's subject, e.g. "Re: Order 123", so Gmail keeps it in the thread.
cc	string	no	CC email addresses, comma-separated.
bcc	string	no	BCC email addresses, comma-separated.

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Approval card: shown as email (to → to, cc → cc, bcc → bcc, subject → subject, body → body).

Forward message — gmail.forward_message

Forwards an existing Gmail message identified by message_id to a new to recipient. Optional body adds forward commentary. This delivers mail — irreversible from the agent.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send

Input

Field	Type	Required	Description
message_id	string	yes	Id of the message to forward. From gmail.fetch_emails or gmail.get_thread.
to	string	yes	Recipient email address; separate several with commas, e.g. "anna@example.com, bob@example.com".
body	string	no	Optional plain-text note shown above the forwarded message.
subject	string	no	Subject of the forward. Defaults to "Fwd: " plus the original subject.
cc	string	no	CC email addresses, comma-separated.
bcc	string	no	BCC email addresses, comma-separated.

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Approval card: shown as email (to → to, cc → cc, bcc → bcc, subject → subject, body → body).

Modify message labels — gmail.modify_message_labels

Adds and/or removes Gmail labels on one message. Provide message_id and at least one of add_label_ids / remove_label_ids. Use list_labels to resolve custom label ids before calling.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	yes	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
message_id	string	yes	Id of the message to relabel. From gmail.fetch_emails or gmail.get_thread.
add_label_ids	array of string	no	Label ids to add, e.g. ["STARRED"]. From gmail.list_labels.
remove_label_ids	array of string	no	Label ids to remove, e.g. ["UNREAD"] marks it read. From gmail.list_labels.

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Modify thread labels — gmail.modify_thread_labels

Adds and/or removes Gmail labels on an entire thread (all messages). Provide thread_id and at least one of add_label_ids / remove_label_ids. Use list_labels to resolve custom label ids before calling.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	yes	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
thread_id	string	yes	Id of the thread to relabel. From gmail.list_threads or gmail.fetch_emails (threadId).
add_label_ids	array of string	no	Label ids to add to every message in the thread, e.g. ["STARRED"]. From gmail.list_labels.
remove_label_ids	array of string	no	Label ids to remove from every message, e.g. ["INBOX"] archives it. From gmail.list_labels.

Extra fields: ignored.

Output

Field	Type	Description
id	string
snippet	string
historyId	string
messages	array of object
messages[].id	string
messages[].threadId	string
messages[].labelIds	array of string
messages[].snippet	string

Create label — gmail.create_label

Creates a user Gmail label with the given name. Optional visibility fields control inbox list presentation. Use list_labels afterward to confirm the new label id before applying it.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	no	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
name	string	yes	Display name of the new label, e.g. "Customers/VIP" (a slash nests it under "Customers").
message_list_visibility	string	no	Whether messages with this label are shown in the message list. One of: show, hide.
label_list_visibility	string	no	Whether the label is shown in the label list; labelShowIfUnread shows it only when it has unread mail. One of: labelShow, labelShowIfUnread, labelHide.

Extra fields: ignored.

Output

Field	Type	Description
id	string
name	string
type	string
messageListVisibility	string
labelListVisibility	string
messagesTotal	integer
messagesUnread	integer
threadsTotal	integer
threadsUnread	integer
color	object

Trash message — gmail.trash_message

Moves a Gmail message to Trash by message_id. User-visible and recoverable via untrash_message until permanently deleted. Prefer trash over permanent delete for reversible cleanup.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	yes	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
message_id	string	yes	Id of the message to move to Trash. From gmail.fetch_emails or gmail.get_thread.

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Trash thread — gmail.trash_thread

Moves an entire Gmail thread (all messages) to Trash by thread_id. User-visible and recoverable via untrash_thread. Use when the whole conversation should leave the inbox.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	no	yes	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
thread_id	string	yes	Id of the thread to move to Trash. From gmail.list_threads or gmail.fetch_emails (threadId).

Extra fields: ignored.

Output

Field	Type	Description
id	string
snippet	string
historyId	string
messages	array of object
messages[].id	string
messages[].threadId	string
messages[].labelIds	array of string
messages[].snippet	string

Untrash message — gmail.untrash_message

Restores a Gmail message from Trash by message_id. Use after trash_message when the agent or user wants the message back. Low-risk write; does not permanently delete.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	low	no	yes	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
message_id	string	yes	Id of the trashed message to restore. From gmail.trash_message or gmail.fetch_emails with q "in:trash".

Extra fields: ignored.

Output

Field	Type	Description
id	string
threadId	string
labelIds	array of string

Untrash thread — gmail.untrash_thread

Restores an entire Gmail thread from Trash by thread_id. Use after trash_thread to bring the conversation back. Low-risk write; does not permanently delete.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	low	no	yes	https://www.googleapis.com/auth/gmail.modify

Input

Field	Type	Required	Description
thread_id	string	yes	Id of the trashed thread to restore. From gmail.trash_thread or gmail.list_threads with q "in:trash".

Extra fields: ignored.

Output

Field	Type	Description
id	string
snippet	string
historyId	string
messages	array of object
messages[].id	string
messages[].threadId	string
messages[].labelIds	array of string
messages[].snippet	string

Delete draft — gmail.delete_draft

Permanently deletes a Gmail draft by draft_id (not trash — irreversible). Prefer update_draft or leave drafts when unsure. Requires approval because the draft cannot be recovered.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	medium	yes	yes	https://www.googleapis.com/auth/gmail.compose

Input

Field	Type	Required	Description
draft_id	string	yes	Id of the draft to delete for good. From gmail.list_drafts.

Extra fields: ignored.

Output

Returns an empty object.