composio-gmail

name	composio-gmail
description	Per-app playbook for driving Gmail through Composio (toolkit slug `gmail`). Verified GMAIL_* tool slugs and argument shapes for reading, searching, sending, drafts, labels, and threads. Use alongside the `composio` hub skill whenever a task reads or sends Gmail for a connected user. Covers the metadata-first reads, the GMAIL_SEND_EMAIL HTML flag, and reply-to-thread.

Composio · Gmail

Toolkit slug: gmail. Read the [[composio]] hub first for the call model (agent-swarm x composio …, user_id, connected accounts, the 4302 gotcha). Tool arguments go inside the request body; user_id defaults to "me" (the authorized account) — you usually don't need to set it.

# Direct execute (reliable path — pin the ACTIVE ca_… from the hub Recipe B)
agent-swarm x composio POST /tools/execute/<SLUG> \
  --body '{"user_id":"[e-mail]","connected_account_id":"ca_…","arguments":{ … }}'

Headline tools

Slug	What	Key args
GMAIL_FETCH_EMAILS	List/search emails	query, max_results (def 1 — set it!), include_payload (def true), verbose (def true), ids_only, label_ids, page_token
GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID	Full single message	message_id, include_payload
GMAIL_FETCH_MESSAGE_BY_THREAD_ID	All messages in a thread	thread_id
GMAIL_LIST_THREADS	List threads	query, max_results, page_token
GMAIL_SEND_EMAIL	Send	recipient_email, subject, body, is_html (def false), cc, bcc, extra_recipients, attachment
GMAIL_REPLY_TO_THREAD	Reply in-thread	thread_id, message_body, recipient_email
GMAIL_CREATE_EMAIL_DRAFT / GMAIL_SEND_DRAFT	Draft then send	body, subject, recipient_email / draft_id
GMAIL_GET_PROFILE	Whose mailbox is this?	—
GMAIL_LIST_LABELS / GMAIL_CREATE_LABEL / GMAIL_ADD_LABEL_TO_EMAIL	Labels	message_id, label_ids (use LIST_LABELS for custom IDs)
GMAIL_GET_CONTACTS / GMAIL_SEARCH_PEOPLE	Contacts	query
GMAIL_GET_ATTACHMENT	Download attachment	message_id, attachment_id

Full set: 63 tools — list with agent-swarm x composio GET "/tools?toolkit_slug=gmail&limit=100" | jq -r '.items[]|"\(.slug)\t\(.name)"'. Avoid the ones marked Deprecated (GMAIL_LIST_MESSAGES, GMAIL_REMOVE_LABEL).

Read recipe (metadata-first)

agent-swarm x composio POST /tools/execute/GMAIL_FETCH_EMAILS \
  --body '{"connected_account_id":"ca_…","arguments":{"max_results":5,"include_payload":false,"verbose":false}}'

• Always set max_results — the default is 1.
• Use Gmail query syntax: "is:unread", "from:[e-mail] newer_than:7d", "subject:invoice has:attachment".
• Keep include_payload:false + verbose:false unless the user needs full bodies (token-heavy). Use ids_only:true for the cheapest listing.

Send recipe

agent-swarm x composio POST /tools/execute/GMAIL_SEND_EMAIL \
  --body '{"connected_account_id":"ca_…","arguments":{
    "recipient_email":"[e-mail]",
    "subject":"Hello",
    "body":"<p>Hi there</p>",
    "is_html":true,
    "cc":["[e-mail]"]
  }}'

• Set is_html:true when body contains HTML, otherwise it sends as literal text.
• recipient_email is the primary; add more via extra_recipients / cc / bcc.
• Sending is a write action — only do it when the task explicitly asks.

Reply in a thread

agent-swarm x composio POST /tools/execute/GMAIL_REPLY_TO_THREAD \
  --body '{"connected_account_id":"ca_…","arguments":{
    "thread_id":"<thread_id>","recipient_email":"[e-mail]","message_body":"thanks!"
  }}'

Gotchas

• Default max_results is 1 — forgetting it makes "list my emails" return a single message.
• Bodies/attachments are token-heavy and may contain secrets — default to metadata; the secret-scrubber doesn't run on Composio tool output.
• If you get ToolRouterV2_NoActiveConnection, switch to direct execute with the pinned connected_account_id (hub Gotchas).