Gmail Read (via Composio)

Read-only access to Gmail. This skill cannot send, reply, delete, or modify emails or labels.

How to Call

Run the broker script with Bash:

COMPOSIO_API_KEY="$COMPOSIO_API_KEY" node {baseDir}/dist/gmail-broker.js <ACTION> '<json-params>'

Replace {baseDir} with the absolute path to this skill directory (~/.agents/skills/gmail-read).

Available Actions

1. check-connection

Verify that Gmail is connected in Composio.

node {baseDir}/dist/gmail-broker.js check-connection

2. GMAIL_FETCH_EMAILS

Search or list emails. Returns message snippets and metadata.

Parameter	Type	Required	Description
query	string	no	Gmail search query (see syntax below)
max_results	number	no	Max emails to return (default 10)
label_ids	string	no	Comma-separated label IDs to filter

node {baseDir}/dist/gmail-broker.js GMAIL_FETCH_EMAILS '{"query":"is:unread","max_results":5}'

3. GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID

Fetch the full content of a single email by its message ID.

Parameter	Type	Required	Description
message_id	string	yes	The Gmail message ID

node {baseDir}/dist/gmail-broker.js GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID '{"message_id":"18e1a2b3c4d5e6f7"}'

4. GMAIL_LIST_LABELS

List all labels in the mailbox (INBOX, SENT, custom labels, etc.).

node {baseDir}/dist/gmail-broker.js GMAIL_LIST_LABELS '{}'

5. GMAIL_GET_PROFILE

Get the authenticated user's email address and message counts.

node {baseDir}/dist/gmail-broker.js GMAIL_GET_PROFILE '{}'

6. GMAIL_GET_ATTACHMENT

Download an attachment from a message.

Parameter	Type	Required	Description
message_id	string	yes	The Gmail message ID
attachment_id	string	yes	The attachment ID

node {baseDir}/dist/gmail-broker.js GMAIL_GET_ATTACHMENT '{"message_id":"18e1a2b3c4d5e6f7","attachment_id":"ANGjdJ8..."}'

Usage Patterns

Breaking change: GMAIL_FETCH_EMAILS no longer returns messageText (full body). This reduces response size from ~1.2 MB to ~50 KB for typical queries. Use GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID to get the full content of specific emails.

• GMAIL_FETCH_EMAILS returns metadata only (subject, sender, date, snippet, labels, messageId). Use it to list, filter, and triage emails.
• GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID returns the full email content including the body. Use it to read specific emails identified from the list.

A typical workflow: fetch a list with GMAIL_FETCH_EMAILS, scan subjects/snippets, then call GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID for the emails you need to read in full. This pattern works for cron alerting, triage, summarization, and any other email workflow.

Gmail Query Syntax

Use these in the query parameter for GMAIL_FETCH_EMAILS:

Query	Meaning
is:unread	Unread messages
is:starred	Starred messages
from:alice@example.com	From a specific sender
to:bob@example.com	Sent to a specific recipient
subject:invoice	Subject contains "invoice"
has:attachment	Has attachments
after:2025/01/01	After a date
before:2025/02/01	Before a date
newer_than:7d	Within last 7 days
label:important	Has a specific label
in:inbox	In inbox
"exact phrase"	Exact phrase match
is:unread from:boss@work.com	Combine with spaces (AND logic)

Pagination Pattern

If you need more results than max_results, increase the value. The API returns up to 500 results in a single call.

To browse through a large mailbox, narrow with date ranges:

node {baseDir}/dist/gmail-broker.js GMAIL_FETCH_EMAILS '{"query":"after:2025/02/01 before:2025/02/10","max_results":50}'

Read-Only Constraint

This skill only allows read operations. Any attempt to call send, reply, delete, draft, or label-modification actions will be rejected by the broker with an "Action not allowed" error. This is intentional and cannot be overridden.