Gmail
Give agents a real Gmail mailbox: list and search messages, read full bodies and attachments, manage labels, and draft or send mail as the connected account.
Every tool type on this page requires a Gmail connector — an OAuth connection to the Google account whose mailbox the agent should work in. The tool config points at the connector with connectorId, and Autessa refreshes the OAuth token automatically before each call. See Connectors for how to link an account.
Reading tools return decoded message bodies (not just snippets), so agents can act on full email content without extra round-trips.
List Unread TOOLGMAIL_LIST_UNREAD
Lists unread messages in the mailbox, optionally narrowed to specific label IDs, and fetches each result in full. The response contains totalResults plus a messages array where every entry carries id, threadId, the key headers (From, To, Subject, Date, Cc, Bcc, Reply-To, Message-ID), the snippet, and the decoded plain-text body. If an unread message already has a draft reply in progress, its draftId is included so the agent can update the existing draft instead of creating a duplicate. maxResults defaults to 10 when unset.
Example
{
"toolType": "GMAIL_LIST_UNREAD",
"connectorId": "V1StGXR8Z5",
"maxResults": 25,
"includeSpamTrash": false,
"labelIds": ["INBOX"]
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
maxResults- Type
- integer
- Description
- Required integer value.
- Name
includeSpamTrash- Type
- boolean
- Description
- Required boolean value.
- Name
labelIds- Type
- array<string> · optional
- Description
- Optional filter
Mark as Read TOOLGMAIL_MARK_AS_READ
Removes the UNREAD label from a single message, marking it read in the connected mailbox. Agents typically call this after processing a message surfaced by List Unread so the same email is not handled twice. The result confirms the messageId that was updated; no other labels are touched.
Example
{
"toolType": "GMAIL_MARK_AS_READ",
"connectorId": "V1StGXR8Z5",
"messageId": "@@{messageId}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
messageId- Type
- string
- Description
- Required string value.
Move to Label TOOLGMAIL_MOVE_TO_LABEL
Modifies the labels on a message in one call: every ID in addLabelIds is applied and every ID in removeLabelIds is stripped. Because Gmail folders are just labels, this is also how an agent archives or files mail — removing INBOX while adding a custom label moves the message out of the inbox and into that label. The result echoes the addedLabels and removedLabels that were applied.
Example
{
"toolType": "GMAIL_MOVE_TO_LABEL",
"connectorId": "V1StGXR8Z5",
"messageId": "@@{messageId}",
"addLabelIds": ["Label_1234567890"],
"removeLabelIds": ["INBOX"]
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
messageId- Type
- string
- Description
- Required string value.
- Name
addLabelIds- Type
- array<string>
- Description
- Required array<string> value.
- Name
removeLabelIds- Type
- array<string>
- Description
- Required array<string> value.
Create Draft Reply TOOLGMAIL_CREATE_DRAFT_REPLY
Drafts a threaded reply to an existing message: the executor reads the original's headers, sets In-Reply-To and References so the reply lands in the same conversation, prefixes the subject with Re:, and addresses the original sender — with replyAll unset or true, the original To and Cc recipients are included too (the connected account's own address is always filtered out). If the thread already ends in a draft, that draft is updated in place rather than duplicated, and the result carries updated: true. The result includes the draftId, threadId, and resolved recipient lists; at least one of replyBody or replyBodyHtml must be provided, and nothing is sent until a Send Draft call.
Example
{
"toolType": "GMAIL_CREATE_DRAFT_REPLY",
"connectorId": "V1StGXR8Z5",
"originalMessageId": "@@{messageId}",
"replyBody": "@@{replyText}",
"replyAll": true
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
originalMessageId- Type
- string
- Description
- Required string value.
- Name
replyBody- Type
- string
- Description
- Required string value.
- Name
replyBodyHtml- Type
- string · optional
- Description
- Optional
- Name
replyAll- Type
- boolean · optional
- Description
- Optional; null is treated as true (reply all)
- Name
attachments- Type
- array<object> · optional
- Description
- Optional; re-uploaded in full when the draft is updated
Create Draft TOOLGMAIL_CREATE_DRAFT
Creates a fresh draft (not attached to any thread) addressed from the connected account. Supply plain text in body, HTML in bodyHtml, or both — when HTML is present the draft is built as a multipart/alternative message so recipients without HTML rendering still see the text part; at least one of the two body fields is required. The result returns the draftId to pass to Send Draft, and the draft sits in the user's Gmail Drafts folder for human review before anything goes out.
Example
{
"toolType": "GMAIL_CREATE_DRAFT",
"connectorId": "V1StGXR8Z5",
"to": "@@{recipientEmail}",
"subject": "Your onboarding checklist",
"body": "@@{draftText}",
"cc": "success@acme.example"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
to- Type
- string
- Description
- Required string value.
- Name
subject- Type
- string
- Description
- Required string value.
- Name
body- Type
- string
- Description
- Required string value.
- Name
bodyHtml- Type
- string · optional
- Description
- Optional
- Name
cc- Type
- string · optional
- Description
- Optional
- Name
bcc- Type
- string · optional
- Description
- Optional
- Name
attachments- Type
- array<object> · optional
- Description
- Optional
Send Draft TOOLGMAIL_SEND_DRAFT
Sends an existing draft by its draftId — the counterpart to Create Draft and Create Draft Reply in a review-then-send workflow. Gmail delivers the draft exactly as it stands (including any human edits made in the meantime) and removes it from the Drafts folder. The result returns the sent message's messageId and threadId.
Example
{
"toolType": "GMAIL_SEND_DRAFT",
"connectorId": "V1StGXR8Z5",
"draftId": "@@{draftId}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
draftId- Type
- string
- Description
- Required string value.
Send Email TOOLGMAIL_SEND_EMAIL
Sends a message immediately from the connected account, with no draft step and no human checkpoint — reserve it for agents trusted to send autonomously, and prefer the draft tools when a review step is wanted. Like Create Draft it accepts body, bodyHtml, or both (sent as multipart/alternative), plus optional cc and bcc. The result returns the new messageId and threadId.
Example
{
"toolType": "GMAIL_SEND_EMAIL",
"connectorId": "V1StGXR8Z5",
"to": "@@{recipientEmail}",
"subject": "@@{subject}",
"body": "@@{messageText}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
to- Type
- string
- Description
- Required string value.
- Name
subject- Type
- string
- Description
- Required string value.
- Name
body- Type
- string
- Description
- Required string value.
- Name
bodyHtml- Type
- string · optional
- Description
- Optional
- Name
cc- Type
- string · optional
- Description
- Optional
- Name
bcc- Type
- string · optional
- Description
- Optional
- Name
attachments- Type
- array<object> · optional
- Description
- Optional
Get Message by ID TOOLGMAIL_GET_MESSAGE_BY_ID
Fetches one message in full and returns an email object with headers, labelIds, snippet, internalDate, sizeEstimate, and the decoded body (plain text preferred, falling back to HTML). It is also the richest way to reach attachments: each attachment is downloaded, staged, and listed with fileName, mimeType, attachmentId, and ready-to-use url and downloadUrl links that expire after 15 minutes. Use it after a list or search call when the agent needs the complete content of a specific message.
Example
{
"toolType": "GMAIL_GET_MESSAGE_BY_ID",
"connectorId": "V1StGXR8Z5",
"messageId": "@@{messageId}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
messageId- Type
- string
- Description
- Required string value.
Get Attachment Content TOOLGMAIL_GET_ATTACHMENT_CONTENT
Downloads a single attachment and runs it through Autessa's file-content extraction, returning the attachment's text content directly in the result (fileName, mimeType, content) — not a link and not base64. This lets an agent read a PDF invoice or Word document from an email in one step. Use the attachmentId values surfaced by Get Message by ID or Search Messages; if the file's content cannot be extracted the tool fails with EXTRACTION_FAILED rather than returning raw bytes.
Example
{
"toolType": "GMAIL_GET_ATTACHMENT_CONTENT",
"connectorId": "V1StGXR8Z5",
"messageId": "@@{messageId}",
"attachmentId": "@@{attachmentId}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
messageId- Type
- string
- Description
- Required string value.
- Name
attachmentId- Type
- string
- Description
- Required string value.
Get Attachment Download Link TOOLGMAIL_GET_ATTACHMENT_DOWNLOAD_LINK
Downloads an attachment, stages it, and returns links instead of content: a short downloadUrl on the Autessa domain plus the underlying presignedUrl, both valid for 15 minutes (expiresInSeconds: 900). The result also reports fileName, mimeType, and fileSizeBytes. Use this when the file should be handed to a person, another tool, or an AutessaDB FILE column rather than read as text.
Example
{
"toolType": "GMAIL_GET_ATTACHMENT_DOWNLOAD_LINK",
"connectorId": "V1StGXR8Z5",
"messageId": "@@{messageId}",
"attachmentId": "@@{attachmentId}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
messageId- Type
- string
- Description
- Required string value.
- Name
attachmentId- Type
- string
- Description
- Required string value.
- Name
saveToTableId- Type
- string (ID) · optional
- Description
- Optional: store the attachment as a file in this AutessaDB table (same company) instead of returning it; the result's `s3Uri` is what to write into that column's filePath. Lets a script (which has no IO) put email attachments into a table. Set together with saveToColumnName. References an AutessaDB table by ID.
- Name
saveToColumnName- Type
- string · optional
- Description
- Optional (required with saveToTableId): the FILE, IMAGE, VIDEO or AUDIO column the file is stored for. It must accept the file's type; a FILE column takes any type.
Search Messages TOOLGMAIL_SEARCH_MESSAGES
Searches the mailbox by combining the structured fields into a single Gmail query — from, to, and subject become their matching operators, hasAttachment adds has:attachment, after/before add date bounds, labelIds, isUnread, and isStarred add their filters, and anything in query is appended as free-form Gmail search syntax (so query alone can express any search Gmail supports). Each hit is returned in full: headers, labelIds, snippet, internalDate, the decoded body, and attachment metadata (fileName, mimeType, attachmentId — no download links; follow up with the attachment tools). maxResults defaults to 10.
Example
{
"toolType": "GMAIL_SEARCH_MESSAGES",
"connectorId": "V1StGXR8Z5",
"from": "@@{senderEmail}",
"query": "invoice",
"hasAttachment": true,
"after": "2026/06/01",
"isUnread": true,
"maxResults": 20
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
from- Type
- string
- Description
- Required string value.
- Name
to- Type
- string
- Description
- Required string value.
- Name
subject- Type
- string
- Description
- Required string value.
- Name
query- Type
- string
- Description
- Required string value.
- Name
hasAttachment- Type
- boolean
- Description
- Required boolean value.
- Name
after- Type
- string
- Description
- Required string value.
- Name
before- Type
- string
- Description
- Required string value.
- Name
labelIds- Type
- array<string>
- Description
- Required array<string> value.
- Name
isUnread- Type
- boolean
- Description
- Required boolean value.
- Name
isStarred- Type
- boolean
- Description
- Required boolean value.
- Name
maxResults- Type
- integer
- Description
- Required integer value.
- Name
includeSpamTrash- Type
- boolean
- Description
- Required boolean value.