Gmail Automation via Rube MCP

Automate Gmail operations through Composio's Gmail toolkit via Rube MCP.

Toolkit docs: composio.dev/toolkits/gmail

Prerequisites

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Gmail connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
gmail
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

Setup

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
gmail
```
If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
Confirm connection status shows ACTIVE before running any workflows

Core Workflows

1. Send an Email

When to use: User wants to compose and send a new email

Tool sequence:

```
GMAIL_SEARCH_PEOPLE
```
- Resolve contact name to email address [Optional]
```
GMAIL_SEND_EMAIL
```
- Send the email [Required]

Key parameters:

```
recipient_email
```
: Email address or 'me' for self
```
subject
```
: Email subject line
```
body
```
: Email content (plain text or HTML)
```
is_html
```
: Must be
```
true
```
if body contains HTML markup
```
cc
```
/
```
bcc
```
: Arrays of email addresses
```
attachment
```
: Object with
```
{s3key, mimetype, name}
```
from prior download

Pitfalls:

At least one of
```
recipient_email
```
,
```
cc
```
, or
```
bcc
```
required
At least one of
```
subject
```
or
```
body
```
required
Attachment
```
mimetype
```
MUST contain '/' (e.g., 'application/pdf', not 'pdf')
Total message size limit ~25MB after base64 encoding
Use
```
from_email
```
only for verified aliases in Gmail 'Send mail as' settings

2. Reply to a Thread

When to use: User wants to reply to an existing email conversation

Tool sequence:

```
GMAIL_FETCH_EMAILS
```
- Find the email/thread to reply to [Prerequisite]
```
GMAIL_REPLY_TO_THREAD
```
- Send reply within the thread [Required]

Key parameters:

```
thread_id
```
: Hex string from FETCH_EMAILS (e.g., '169eefc8138e68ca')
```
message_body
```
: Reply content
```
recipient_email
```
: Reply recipient
```
is_html
```
: Set
```
true
```
for HTML content

Pitfalls:

```
thread_id
```
must be hex string; prefixes like 'msg-f:' are auto-stripped
Legacy Gmail web UI IDs (e.g., 'FMfcgz...') are NOT supported
Subject is inherited from original thread; setting it creates a new thread instead
Do NOT include subject parameter to stay within thread

3. Search and Filter Emails

When to use: User wants to find specific emails by sender, subject, date, label, etc.

Tool sequence:

```
GMAIL_FETCH_EMAILS
```
- Search with Gmail query syntax [Required]
```
GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID
```
- Get full message details for selected results [Optional]

Key parameters:

```
query
```
: Gmail search syntax (from:, to:, subject:, is:unread, has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD)
```
max_results
```
: 1-500 messages per page
```
label_ids
```
: System IDs like 'INBOX', 'UNREAD'
```
include_payload
```
: Set
```
true
```
to get full message content
```
ids_only
```
: Set
```
true
```
for just message IDs
```
page_token
```
: For pagination (from
```
nextPageToken
```
)

Pitfalls:

Returns max ~500 per page; follow
```
nextPageToken
```
via
```
page_token
```
until absent
```
resultSizeEstimate
```
is approximate, not exact count
Use 'is:' for states (is:unread, is:snoozed, is:starred)
Use 'label:' ONLY for user-created labels
Common mistake: 'label:snoozed' is WRONG — use 'is:snoozed'
```
include_payload=true
```
on broad searches creates huge responses; default to metadata
Custom labels require label ID (e.g., 'Label_123'), NOT label name

4. Manage Labels

When to use: User wants to create, modify, or organize labels

Tool sequence:

```
GMAIL_LIST_LABELS
```
- List all labels to find IDs and detect conflicts [Required]
```
GMAIL_CREATE_LABEL
```
- Create a new label [Optional]
```
GMAIL_PATCH_LABEL
```
- Rename or change label colors/visibility [Optional]
```
GMAIL_DELETE_LABEL
```
- Delete a user-created label (irreversible) [Optional]

Key parameters:

```
label_name
```
: Max 225 chars, no commas, '/' for nesting (e.g., 'Work/Projects')
```
background_color
```
/
```
text_color
```
: Hex values from Gmail's predefined palette
```
id
```
: Label ID for PATCH/DELETE operations

Pitfalls:

400/409 error if name is blank, duplicate, or reserved (INBOX, SPAM, CATEGORY_*)
Color specs must use Gmail's predefined palette of 102 hex values
DELETE is permanent and removes label from all messages
Cannot delete system labels (INBOX, SENT, DRAFT, etc.)

5. Apply/Remove Labels on Messages

When to use: User wants to label, archive, or mark emails as read/unread

Tool sequence:

```
GMAIL_LIST_LABELS
```
- Get label IDs for custom labels [Prerequisite]
```
GMAIL_FETCH_EMAILS
```
- Find target messages [Prerequisite]
```
GMAIL_BATCH_MODIFY_MESSAGES
```
- Bulk add/remove labels (up to 1000 messages) [Required]
```
GMAIL_ADD_LABEL_TO_EMAIL
```
- Single-message label changes [Fallback]

Key parameters:

```
messageIds
```
: Array of message IDs (max 1000)
```
addLabelIds
```
: Array of label IDs to add
```
removeLabelIds
```
: Array of label IDs to remove
```
message_id
```
: 15-16 char hex string for single operations

Pitfalls:

Max 1000 messageIds per BATCH call; chunk larger sets
Use 'CATEGORY_UPDATES' not 'UPDATES'; full prefix required for category labels
SENT, DRAFT, CHAT are immutable — cannot be added/removed
To mark as read: REMOVE 'UNREAD'. To archive: REMOVE 'INBOX'
```
message_id
```
must be 15-16 char hex, NOT UUIDs or web UI IDs

6. Handle Drafts and Attachments

When to use: User wants to create, edit, or send email drafts, possibly with attachments

Tool sequence:

```
GMAIL_CREATE_EMAIL_DRAFT
```
- Create a new draft [Required]
```
GMAIL_UPDATE_DRAFT
```
- Edit draft content [Optional]
```
GMAIL_LIST_DRAFTS
```
- List existing drafts [Optional]
```
GMAIL_SEND_DRAFT
```
- Send a draft (requires explicit user approval) [Optional]
```
GMAIL_GET_ATTACHMENT
```
- Download attachment from existing message [Optional]

Key parameters:

```
recipient_email
```
: Draft recipient
```
subject
```
: Draft subject (omit for reply drafts to stay in thread)
```
body
```
: Draft content
```
is_html
```
: Set
```
true
```
for HTML content
```
attachment
```
: Object with
```
{s3key, mimetype, name}
```
```
thread_id
```
: For reply drafts (leave subject empty to stay in thread)

Pitfalls:

Response includes
```
data.id
```
(draft_id) AND
```
data.message.id
```
; use
```
data.id
```
for draft operations
Setting subject on a thread reply draft creates a NEW thread instead
Attachment capped at ~25MB; base64 overhead can push near-limit files over
UPDATE_DRAFT replaces entire content, not patches; include all fields you want to keep
HTTP 429 on bulk draft creation; use exponential backoff

Common Patterns

ID Resolution

Label name → Label ID:

1. Call GMAIL_LIST_LABELS
2. Find label by name in response
3. Extract id field (e.g., 'Label_123')

Contact name → Email:

1. Call GMAIL_SEARCH_PEOPLE with query=contact_name
2. Extract emailAddresses from response

Thread ID from search:

1. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
2. Extract threadId (15-16 char hex string)

Pagination

Set
```
max_results
```
up to 500 per page
Check response for
```
nextPageToken
```
Pass token as
```
page_token
```
in next request
Continue until
```
nextPageToken
```
is absent or empty string
```
resultSizeEstimate
```
is approximate, not exact

Gmail Query Syntax

Operators:

```
from:sender@example.com
```
- Emails from sender
```
to:recipient@example.com
```
- Emails to recipient
```
subject:"exact phrase"
```
- Subject contains exact phrase
```
is:unread
```
- Unread messages
```
is:starred
```
- Starred messages
```
is:snoozed
```
- Snoozed messages
```
has:attachment
```
- Has attachments
```
after:2024/01/01
```
- After date (YYYY/MM/DD)
```
before:2024/12/31
```
- Before date
```
label:custom_label
```
- User-created label (use label ID)
```
in:sent
```
- In sent folder
```
category:primary
```
- Primary category

Combinators:

```
AND
```
- Both conditions (default)
```
OR
```
- Either condition
```
NOT
```
- Exclude condition
```
()
```
- Group conditions

Examples:

```
from:boss@company.com is:unread
```
- Unread emails from boss

subject:invoice has:attachment after:2024/01/01

- Invoices with attachments this year

```
(from:alice OR from:bob) is:starred
```
- Starred emails from Alice or Bob

Known Pitfalls

ID Formats:

Custom label operations require label IDs (e.g., 'Label_123'), not display names
Always call LIST_LABELS first to resolve names to IDs
Message IDs are 15-16 char hex strings
Do NOT use UUIDs, web UI IDs, or 'thread-f:' prefixes

Query Syntax:

Use 'is:' for states (unread, snoozed, starred)
Use 'label:' ONLY for user-created labels
System labels use 'is:' or 'in:' (e.g., 'is:sent', 'in:inbox')

Rate Limits:

BATCH_MODIFY_MESSAGES max 1000 messages per call
Heavy use triggers 403/429 rate limits
Implement exponential backoff for bulk operations

Response Parsing:

Response data may be nested under
```
data_preview
```
or
```
data.messages
```
Parse defensively with fallbacks
Timestamp
```
messageTimestamp
```
uses RFC3339 with 'Z' suffix
Normalize to '+00:00' for parsing if needed

Attachments:

Attachment
```
s3key
```
from prior download may expire
Use promptly after retrieval
Mimetype must include '/' separator

Quick Reference

Task	Tool Slug	Key Params
Send email	GMAIL_SEND_EMAIL	recipient_email, subject, body, is_html
Reply to thread	GMAIL_REPLY_TO_THREAD	thread_id, message_body, recipient_email
Search emails	GMAIL_FETCH_EMAILS	query, max_results, label_ids, page_token
Get message details	GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID	message_id
List labels	GMAIL_LIST_LABELS	(none)
Create label	GMAIL_CREATE_LABEL	label_name, background_color, text_color
Modify labels bulk	GMAIL_BATCH_MODIFY_MESSAGES	messageIds, addLabelIds, removeLabelIds
Create draft	GMAIL_CREATE_EMAIL_DRAFT	recipient_email, subject, body, thread_id
Send draft	GMAIL_SEND_DRAFT	draft_id
Get attachment	GMAIL_GET_ATTACHMENT	message_id, attachment_id
Search contacts	GMAIL_SEARCH_PEOPLE	query
Get profile	GMAIL_GET_PROFILE	(none)

gmail-automation

NPX Install

Tags

SKILL.md Content

Gmail Automation via Rube MCP

Prerequisites

Setup

Core Workflows

1. Send an Email

2. Reply to a Thread

3. Search and Filter Emails

4. Manage Labels

5. Apply/Remove Labels on Messages

6. Handle Drafts and Attachments

Common Patterns

ID Resolution

Pagination

Gmail Query Syntax

Known Pitfalls

Quick Reference