OpenParable
Skip to content
← Back to skills

Composio Gmail

Apps & Automation
composio-gmail

Composio Gmail is an Agent Skill for apps & automation published in the desplega-ai/agent-swarm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/desplega-ai/agent-swarm/blob/HEAD/plugin/skills/composio-gmail/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/composio-gmail, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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":"[email protected]","connected_account_id":"ca_…","arguments":{ … }}'

Headline tools

SlugWhatKey args
GMAIL_FETCH_EMAILSList/search emailsquery, max_results (def 1 — set it!), include_payload (def true), verbose (def true), ids_only, label_ids, page_token
GMAIL_FETCH_MESSAGE_BY_MESSAGE_IDFull single messagemessage_id, include_payload
GMAIL_FETCH_MESSAGE_BY_THREAD_IDAll messages in a threadthread_id
GMAIL_LIST_THREADSList threadsquery, max_results, page_token
GMAIL_SEND_EMAILSendrecipient_email, subject, body, is_html (def false), cc, bcc, extra_recipients, attachment
GMAIL_REPLY_TO_THREADReply in-threadthread_id, message_body, recipient_email
GMAIL_CREATE_EMAIL_DRAFT / GMAIL_SEND_DRAFTDraft then sendbody, subject, recipient_email / draft_id
GMAIL_GET_PROFILEWhose mailbox is this?—
GMAIL_LIST_LABELS / GMAIL_CREATE_LABEL / GMAIL_ADD_LABEL_TO_EMAILLabelsmessage_id, label_ids (use LIST_LABELS for custom IDs)
GMAIL_GET_CONTACTS / GMAIL_SEARCH_PEOPLEContactsquery
GMAIL_GET_ATTACHMENTDownload attachmentmessage_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:[email protected] 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":"[email protected]",
    "subject":"Hello",
    "body":"<p>Hi there</p>",
    "is_html":true,
    "cc":["[email protected]"]
  }}'
  • 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":"[email protected]","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).