Gmail
Service domainEMAIL
Arcade Optimized
Arcade.dev LLM tools for Gmail
31tools
The Gmail toolkit provides Arcade tools for interacting with a user's Gmail account via the Google Gmail API. It enables LLM agents to read, compose, organize, search, and manage email at both the message and thread level.
Capabilities
- Reading & searching: Fetch individual messages or full threads, list emails with optional body inclusion, search by raw Gmail query or header, list attachment metadata, and retrieve account/profile info. Automated/promotional mail is filtered by default.
- Composing & sending: Send new emails, reply to messages, forward messages (with inline-image and attachment handling), and send drafts — all supporting file attachments via
file://URIs resolved client-side. - Draft management: Create, read, update (subject, recipients, body, with fine-grained partial-update semantics), and delete drafts, including draft replies.
- Organization & labeling: Create, rename, delete, and list labels; add/remove user-created labels on individual messages or entire threads in bulk (up to 50 per call); change read/starred/important status; archive, trash, untrash, restore, or report spam on messages or threads.
- Bulk & thread-level operations: Apply label changes, status changes, trash/restore actions, and label sweeps across whole threads or paginated query-matched message sets, with
all_matches_processedand estimate fields for safe iteration. - Unsubscribe: Request removal from marketing mail via List-Unsubscribe headers and optionally trash the message, with explicit safety constraints on opaque HTTPS unsubscribe URLs.
OAuth
This toolkit uses OAuth 2.0 delegated access through Google. See the Arcade Google auth provider docs for setup details.
Available tools(31)
31 of 31 tools
Operations
Behavior
| Tool name | Description | Secrets | |
|---|---|---|---|
Archive exactly one email: remove inbox membership; email stays searchable. | |||
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. | |||
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. 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
file's bytes are read and substituted on the client before the request is sent, so
the contents never pass through this conversation. Do not read, encode, or inline
the bytes yourself. | |||
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
file's bytes are read and substituted on the client before the request is sent, so
the contents never pass through this conversation. Do not read, encode, or inline
the bytes yourself. | |||
Set whether an entire conversation is in Trash, affecting every message at once.
Setting the current status again succeeds without changing the conversation. | |||
Move exactly one email to Trash (recoverable; may be auto-purged later). |
Page 1 of 2(25 of 31)
Last updated on