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 selfsubject: Email subject linebody: Email content (plain text or HTML)is_html: Must be true if body contains HTML markupcc/bcc: Arrays of email addressesattachment: 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 contentrecipient_email: Reply recipientis_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 pagelabel_ids: System IDs like 'INBOX', 'UNREAD'include_payload: Set true to get full message contentids_only: Set true for just message IDspage_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 paletteid: 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 addremoveLabelIds: Array of label IDs to removemessage_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 recipientsubject: Draft subject (omit for reply drafts to stay in thread)body: Draft contentis_html: Set true for HTML contentattachment: 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 senderto:[email protected] - Emails to recipientsubject:"exact phrase" - Subject contains exact phraseis:unread - Unread messagesis:starred - Starred messagesis:snoozed - Snoozed messageshas:attachment - Has attachmentsafter:2024/01/01 - After date (YYYY/MM/DD)before:2024/12/31 - Before datelabel:custom_label - User-created label (use label ID)in:sent - In sent foldercategory:primary - Primary category
Combinators:
AND - Both conditions (default)OR - Either conditionNOT - Exclude condition() - Group conditions
Examples:
from:[email protected] is:unread - Unread emails from bosssubject: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
