Gmail
Read, send, search, and organise emails in the authenticated user's Gmail account. Manage labels and filters to automate inbox organisation. All operations act on the authenticated user's mailbox only.
Quick start
Tools (10)
GETsearch-emails
Returns emails matching a Gmail search query. Supports the same query syntax as the Gmail search box — e.g. "from:jane@example.com", "subject:invoice", "has:attachment", "is:unread", "after:2024/01/01". Returns message IDs, subjects, senders, and dates. Use read-email to get the full content of a specific message. This is a read-only endpoint with no side effects.
GET /messages
Parameters
q
|
string required |
maxResults
|
integer |
pageToken
|
string |
POSTsend-email
Sends an email from the authenticated user's account. This WILL deliver the message to the recipients immediately. Use draft-email if you want to save without sending. Supports plain text and HTML bodies, CC/BCC, and replying to threads. DESTRUCTIVE OPERATION — the email will be sent immediately and cannot be unsent.
POST /messages/send
Parameters
to
|
array required |
subject
|
string required |
body
|
string required |
htmlBody
|
string |
cc
|
array |
bcc
|
array |
threadId
|
string |
inReplyTo
|
string |
POSTdraft-email
Creates a draft email in the user's Drafts folder. The draft can be reviewed and sent later from Gmail. Use this when the user wants to compose but not send immediately. This is a safe operation — nothing is sent to any recipient.
POST /drafts
Parameters
to
|
array required |
subject
|
string required |
body
|
string required |
htmlBody
|
string |
cc
|
array |
bcc
|
array |
GETread-email
Retrieves the complete content of an email including subject, sender, recipients, date, body text, and attachment metadata. Use search-emails first to find message IDs, then read-email to get the full content. Returns the decoded plain text body when available, falling back to HTML. This is a read-only endpoint with no side effects.
GET /messages/{messageId}
Parameters
messageId
|
string required |
DELETEdelete-email
Permanently deletes an email from the user's mailbox. This bypasses the Trash — the message cannot be recovered after deletion. DESTRUCTIVE OPERATION — this is irreversible. Consider using modify-email to move to Trash instead (add label TRASH) if the user might want it back.
DELETE /messages/{messageId}
Parameters
messageId
|
string required |
POSTmodify-email
Modifies the labels on an email. Use this to move messages between folders, mark as read/unread, star/unstar, archive, or apply custom labels. Common label operations: - Archive: remove INBOX label - Mark as read: remove UNREAD label - Star: add STARRED label - Move to Trash: add TRASH label This modifies metadata only — the email content is unchanged.
POST /messages/{messageId}/modify
Parameters
messageId
|
string required |
addLabelIds
|
array |
removeLabelIds
|
array |
GETlist-labels
Returns all labels in the user's mailbox, including system labels (INBOX, SENT, TRASH, SPAM, etc.) and user-created labels. Use the label IDs returned here with modify-email to move or tag messages. This is a read-only endpoint with no side effects.
GET /labels
POSTcreate-label
Creates a custom label in the user's mailbox. Labels can be used to organise emails — apply them with modify-email. The label name must be unique. Use nested names with "/" for sub-labels (e.g., "Work/Projects").
POST /labels
Parameters
name
|
string required |
messageListVisibility
|
string |
labelListVisibility
|
string |
GETlist-filters
Returns all filters configured in the user's Gmail settings. Filters automatically apply actions (labelling, archiving, forwarding) to incoming emails that match specified criteria. This is a read-only endpoint with no side effects.
GET /settings/filters
POSTcreate-filter
Creates a filter that automatically processes incoming emails matching the specified criteria. Can add/remove labels, archive, mark as read, star, or forward matching messages. This affects future incoming emails — it does not retroactively apply to existing messages.
POST /settings/filters
Parameters
criteria
|
object required |
action
|
object required |