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)

Powered by Composio