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_EMAILSreturns metadata only (subject, sender, date, snippet, labels, messageId). Use it to list, filter, and triage emails.GMAIL_FETCH_MESSAGE_BY_MESSAGE_IDreturns 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.