gmail-automation - Agent Skills

Gmail Automation via Rube MCP

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

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
Find label by name in response

Extract id field (e.g., 'Label_123')

Contact name → Email:

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

Thread ID from search:

1. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
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)