gmail-automation

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.

1. Verify Rube MCP is available by confirming RUBE_SEARCH_TOOLS responds
2. Call RUBE_MANAGE_CONNECTIONS with toolkit gmail
3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
4. 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:

1. GMAIL_SEARCH_PEOPLE - Resolve contact name to email address [Optional]
2. 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:

1. GMAIL_FETCH_EMAILS - Find the email/thread to reply to [Prerequisite]
2. 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:

1. GMAIL_FETCH_EMAILS - Search with Gmail query syntax [Required]
2. 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:

1. GMAIL_LIST_LABELS - List all labels to find IDs and detect conflicts [Required]
2. GMAIL_CREATE_LABEL - Create a new label [Optional]
3. GMAIL_PATCH_LABEL - Rename or change label colors/visibility [Optional]
4. 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:

1. GMAIL_LIST_LABELS - Get label IDs for custom labels [Prerequisite]
2. GMAIL_FETCH_EMAILS - Find target messages [Prerequisite]
3. GMAIL_BATCH_MODIFY_MESSAGES - Bulk add/remove labels (up to 1000 messages) [Required]
4. 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:

1. GMAIL_CREATE_EMAIL_DRAFT - Create a new draft [Required]
2. GMAIL_UPDATE_DRAFT - Edit draft content [Optional]
3. GMAIL_LIST_DRAFTS - List existing drafts [Optional]
4. GMAIL_SEND_DRAFT - Send a draft (requires explicit user approval) [Optional]
5. 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:[email protected] - Emails from sender
• to:[email protected] - 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:[email protected] 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

Powered by Composio