Gmail
Service domainEMAIL
Arcade Optimized
Arcade.dev LLM tools for Gmail
32tools
The Gmail toolkit provides Arcade tools for interacting with Gmail via the Google API, enabling LLMs to read, compose, organize, and manage email on behalf of authenticated users.
Capabilities
- Reading & searching: Retrieve individual emails, threads, and drafts; search by query or header; list emails and threads with configurable detail levels (metadata-only, full body, count-only); filter or include automated/promotional mail; paginate large result sets.
- Composing & sending: Send new emails, replies, and forwards; compose and manage drafts (write, write-reply, forward-draft, update, send, delete); attach local files via
file://URIs; handle inline images and quoted history correctly across plain-text and HTML draft shapes. - Bulk email actions: Archive, restore, mark (read/starred/important), label, and report spam on up to 50 emails per call; selectors support individual IDs, query strings, or thread modes with chunked iteration and idempotency caveats.
- Label management: Create, rename, delete, and list user-created labels; apply or remove labels per-message or across an entire thread; system labels (INBOX, SPAM, TRASH) are protected from accidental mutation.
- Thread & conversation operations: Apply label changes, trash/untrash, and archive actions at the thread level to affect every message in a conversation atomically.
- Account & utility: Retrieve authenticated user profile and Gmail account stats; unsubscribe from marketing mail (with optional trash); surface close-match suggestions for misspelled label names.
OAuth
Authentication uses OAuth 2.0 via Google. See the Arcade Google auth provider docs for configuration details.
Available tools(32)
32 of 32 tools
Operations
Behavior
| Tool name | Description | Secrets | |
|---|---|---|---|
Archive up to 50 emails per call: take them out of the Inbox. Archived emails keep
their other labels and stay searchable. This is the only Gmail tool that removes emails
from the Inbox without trashing them or reporting them as spam; the label tools cannot
remove the Inbox label. Archived emails go back to the Inbox when unarchived.
An email already out of the Inbox is a noop, but the tool is not idempotent in query or
thread mode: repeated calls advance to the next chunk, so a blind retry can archive further
emails. A selection with zero Inbox messages returns requested=0, items=[], complete=true,
and all_matches_processed=true (vacuous completion). | |||
Add and remove labels on every message in a thread using the Gmail API.
Use this to change a whole conversation at once (for example, marking a
thread read by removing "UNREAD") instead of modifying each message.
Label names match case-insensitively when there is no exact match. The
confirmation reflects the labels actually present across the thread after
the change, not the requested input.
INBOX, SPAM, and TRASH are refused. Taking a thread out of the Inbox is archiving, a
separate action that selects by thread ID. | |||
Save a forward of one message as an unsent draft, as Gmail's Forward button writes it.
The draft quotes the original body, prefixes the subject with ``Fwd:``, keeps the
original's inline images inline, and carries filename-bearing attachments. | |||
Create a new label in the user's mailbox.
Gmail treats label names as case-insensitive-unique; creating a name that already
exists reports a conflict rather than a duplicate. Documented Gmail reserved SYSTEM
label names (INBOX, SPAM, TRASH, …) are rejected before calling Gmail. Google's
published list is non-exhaustive; upstream create errors remain the backstop for any
other reserved name. | |||
Delete a draft email using the Gmail API. | |||
Delete a user-created label, resolving it by the name the user says.
A misspelled name gets a close-match suggestion; a system label is rejected. Deleting a
label removes it from the mailbox and from every message it was applied to. | |||
Send a copy of one message to new recipients, as Gmail's Forward button does.
The forward quotes the original body, prefixes the subject with ``Fwd:``, keeps the
original's inline images inline, carries filename-bearing attachments, and prepends the
optional note. In the sender's mailbox it joins the original's conversation; recipients
who were not on that conversation receive it as a new one.
An inline image can't be included when the original's copy is no longer available or is
unreadable, when it would push the forward past Gmail's 25 MB limit, or when it is past
the 25-part limit. By default the forward then fails, nothing is sent, and the error names
each image and why it can't be included. An image that can no longer be retrieved can
only be included by attaching a copy of it; one the forward is too large to carry can
only be included by forwarding the message from Gmail directly. Before setting
``allow_missing_images``, ask the user whether to send without those images. With
``allow_missing_images`` true, the forward is sent with an ``[image: ...]`` placeholder
where each image was, and ``warning`` names what was left out. | |||
Read one message by ID without loading the rest of its thread.
Returns parsed sender and recipient headers, the subject, text and HTML bodies,
labels, dates, and attachment metadata. Attachment file bytes are not returned. | |||
Get the specified thread by ID. | |||
Add or remove one user-created label on at most 50 messages per call.
A message already in the requested state is a noop, but the tool is not idempotent in query
mode: repeated calls with the same query advance to the next chunk, so a blind retry can
label further messages.
This tool does not accept Gmail system labels or change read, starred, important, or
Inbox/Trash/Spam status. Taking emails out of the Inbox is archiving, a separate action
from labeling. Selector and label validation finish before mutation. Query selectors may
match more than 50 messages; each call processes up to 50 remaining actionable matches. A
query with zero matches returns requested=0, items=[], complete=true, and
all_matches_processed=true (vacuous completion). | |||
List draft emails in the user's draft mailbox using the Gmail API. | |||
List metadata for a message's real attachments without loading their contents.
Only genuine attachments are reported; unnamed body parts and body-embedded inline images
are excluded. Each row includes its filename, MIME type, size, and Gmail attachment id when
Gmail provides one. | |||
Read emails from a Gmail account.
By default returns metadata-only rows (no body/html_body) so high-volume
triage stays within the context budget. Pass include_body=True when full
message text is needed. Metadata rows still include routing headers
(to/cc/bcc/from/reply_to) and email_addresses.
Obvious automated emails are excluded from results using no-reply sender
patterns and Gmail's non-primary category filters (promotions, social,
updates, forums). Set exclude_automated=False to include all emails
regardless of source. | |||
Search for emails by header using the Gmail API.
By default returns metadata-only rows (no body/html_body). Pass include_body=True
when full message text is needed. Metadata rows still include routing headers
(to/cc/bcc/from/reply_to) and email_addresses. | |||
List all the labels in the user's mailbox. | |||
List threads in the user's mailbox.
By default, obvious automated threads are excluded from results using
no-reply sender patterns and Gmail's non-primary category filters
(promotions, social, updates, forums). Set exclude_automated=False to
include all threads regardless of source. | |||
Change the read, starred, or important status of up to 50 emails per call. Applies one
action to every selected email. Does not move emails into or out of the Inbox, Archive,
Trash, or Spam, or change user-created labels.
An email already in the requested state is a noop, but the tool is not idempotent in query
mode: repeated calls with the same query advance to the next chunk, so a blind retry can
change further emails. Query selectors may match more than 50 emails; each call processes up
to 50 remaining actionable matches. ``all_matches_processed`` and ``matched_estimate``
describe that desired-state-filtered selection, while ``complete`` describes only the
processed ledger. A query with zero matches returns requested=0, items=[], complete=true, and
all_matches_processed=true (vacuous completion). | |||
Send a reply to an email message, optionally with one or more file attachments.
To attach files, pass ``attachments`` and give each file's local path as a
``file://`` URI in ``source`` (formatted ``file:///absolute/path/to/file``). The
client reads each file and substitutes its bytes before the request is sent, so the
file contents are not part of the tool call. | |||
Report exactly one email as spam: move to Spam and remove from the inbox. | |||
Move up to 50 emails per call back out of Archive, Trash, or Spam and into the Inbox.
Applies one action to every selected email. Emails the user sent are restored out of Trash
but not into the Inbox. Does not archive, trash, or report spam, and does not change read,
starred, important, or user-created labels.
Untrash removes an email from Trash and then returns it to the Inbox. If the second step
does not land, the row is not complete and retrying untrash is a noop; finish it with
action=unarchive for that email, as the row's reason says.
An email that is not in the source location is a noop, but the tool is not idempotent in
query mode: repeated calls with the same query advance to the next chunk, so a blind retry
can restore further emails. Query selectors may match more than 50 emails; each call
processes up to 50 remaining actionable matches. ``all_matches_processed`` and
``matched_estimate`` describe that desired-state-filtered selection, while ``complete``
describes only the processed ledger. A query with zero matches returns requested=0,
items=[], complete=true, and all_matches_processed=true (vacuous completion). | |||
Search Gmail with a raw query and return one page in the requested detail mode.
Results follow Gmail's default newest-first order. The default ``lightweight`` mode is
metadata-only (routing/threading headers, no bodies). Count-only returns unhydrated
identifier stubs plus Gmail's approximate match total — useful to estimate how many emails
a query would affect before applying a bulk change. Full results add parsed plain and HTML
bodies. ``pagination.total_estimate`` is always approximate. | |||
Search for threads in the user's mailbox. | |||
Send a draft email using the Gmail API. | |||
Send an email using the Gmail API, optionally with one or more file attachments.
To attach files, pass ``attachments`` and give each file's local path as a
``file://`` URI in ``source`` (formatted ``file:///absolute/path/to/file``). The
client reads each file and substitutes its bytes before the request is sent, so the
file contents are not part of the tool call. | |||
Set whether an entire conversation is in Trash, affecting every message at once.
Setting the current status again succeeds without changing the conversation. |
Page 1 of 2(25 of 32)
Last updated on
Overview
Browse Arcade's catalog of pre-built MCP servers — integrations for GitHub, Slack, Google Workspace, Salesforce, and dozens of other services, ready to use with any MCP-compatible client via the Arcade Engine.
Nimble
Search, extract, crawl, and map the web. Nimble (Nimbleway) is available in Arcade as a Partner MCP server.