Gmail Automation

1---
2name: gmail-automation
3description: "Automate Gmail tasks via Rube MCP (Composio): send/reply, search, labels, drafts, attachments. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Gmail Automation via Rube MCP
9 
10Automate Gmail operations through Composio's Gmail toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Gmail connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `gmail`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**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.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `gmail`
253. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Send an Email
31 
32**When to use**: User wants to compose and send a new email
33 
34**Tool sequence**:
351. `GMAIL_SEARCH_PEOPLE` - Resolve contact name to email address [Optional]
362. `GMAIL_SEND_EMAIL` - Send the email [Required]
37 
38**Key parameters**:
39- `recipient_email`: Email address or 'me' for self
40- `subject`: Email subject line
41- `body`: Email content (plain text or HTML)
42- `is_html`: Must be `true` if body contains HTML markup
43- `cc`/`bcc`: Arrays of email addresses
44- `attachment`: Object with `{s3key, mimetype, name}` from prior download
45 
46**Pitfalls**:
47- At least one of `recipient_email`, `cc`, or `bcc` required
48- At least one of `subject` or `body` required
49- Attachment `mimetype` MUST contain '/' (e.g., 'application/pdf', not 'pdf')
50- Total message size limit ~25MB after base64 encoding
51- Use `from_email` only for verified aliases in Gmail 'Send mail as' settings
52 
53### 2. Reply to a Thread
54 
55**When to use**: User wants to reply to an existing email conversation
56 
57**Tool sequence**:
581. `GMAIL_FETCH_EMAILS` - Find the email/thread to reply to [Prerequisite]
592. `GMAIL_REPLY_TO_THREAD` - Send reply within the thread [Required]
60 
61**Key parameters**:
62- `thread_id`: Hex string from FETCH_EMAILS (e.g., '169eefc8138e68ca')
63- `message_body`: Reply content
64- `recipient_email`: Reply recipient
65- `is_html`: Set `true` for HTML content
66 
67**Pitfalls**:
68- `thread_id` must be hex string; prefixes like 'msg-f:' are auto-stripped
69- Legacy Gmail web UI IDs (e.g., 'FMfcgz...') are NOT supported
70- Subject is inherited from original thread; setting it creates a new thread instead
71- Do NOT include subject parameter to stay within thread
72 
73### 3. Search and Filter Emails
74 
75**When to use**: User wants to find specific emails by sender, subject, date, label, etc.
76 
77**Tool sequence**:
781. `GMAIL_FETCH_EMAILS` - Search with Gmail query syntax [Required]
792. `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID` - Get full message details for selected results [Optional]
80 
81**Key parameters**:
82- `query`: Gmail search syntax (from:, to:, subject:, is:unread, has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD)
83- `max_results`: 1-500 messages per page
84- `label_ids`: System IDs like 'INBOX', 'UNREAD'
85- `include_payload`: Set `true` to get full message content
86- `ids_only`: Set `true` for just message IDs
87- `page_token`: For pagination (from `nextPageToken`)
88 
89**Pitfalls**:
90- Returns max ~500 per page; follow `nextPageToken` via `page_token` until absent
91- `resultSizeEstimate` is approximate, not exact count
92- Use 'is:' for states (is:unread, is:snoozed, is:starred)
93- Use 'label:' ONLY for user-created labels
94- Common mistake: 'label:snoozed' is WRONG — use 'is:snoozed'
95- `include_payload=true` on broad searches creates huge responses; default to metadata
96- Custom labels require label ID (e.g., 'Label_123'), NOT label name
97 
98### 4. Manage Labels
99 
100**When to use**: User wants to create, modify, or organize labels
101 
102**Tool sequence**:
1031. `GMAIL_LIST_LABELS` - List all labels to find IDs and detect conflicts [Required]
1042. `GMAIL_CREATE_LABEL` - Create a new label [Optional]
1053. `GMAIL_PATCH_LABEL` - Rename or change label colors/visibility [Optional]
1064. `GMAIL_DELETE_LABEL` - Delete a user-created label (irreversible) [Optional]
107 
108**Key parameters**:
109- `label_name`: Max 225 chars, no commas, '/' for nesting (e.g., 'Work/Projects')
110- `background_color`/`text_color`: Hex values from Gmail's predefined palette
111- `id`: Label ID for PATCH/DELETE operations
112 
113**Pitfalls**:
114- 400/409 error if name is blank, duplicate, or reserved (INBOX, SPAM, CATEGORY_*)
115- Color specs must use Gmail's predefined palette of 102 hex values
116- DELETE is permanent and removes label from all messages
117- Cannot delete system labels (INBOX, SENT, DRAFT, etc.)
118 
119### 5. Apply/Remove Labels on Messages
120 
121**When to use**: User wants to label, archive, or mark emails as read/unread
122 
123**Tool sequence**:
1241. `GMAIL_LIST_LABELS` - Get label IDs for custom labels [Prerequisite]
1252. `GMAIL_FETCH_EMAILS` - Find target messages [Prerequisite]
1263. `GMAIL_BATCH_MODIFY_MESSAGES` - Bulk add/remove labels (up to 1000 messages) [Required]
1274. `GMAIL_ADD_LABEL_TO_EMAIL` - Single-message label changes [Fallback]
128 
129**Key parameters**:
130- `messageIds`: Array of message IDs (max 1000)
131- `addLabelIds`: Array of label IDs to add
132- `removeLabelIds`: Array of label IDs to remove
133- `message_id`: 15-16 char hex string for single operations
134 
135**Pitfalls**:
136- Max 1000 messageIds per BATCH call; chunk larger sets
137- Use 'CATEGORY_UPDATES' not 'UPDATES'; full prefix required for category labels
138- SENT, DRAFT, CHAT are immutable — cannot be added/removed
139- To mark as read: REMOVE 'UNREAD'. To archive: REMOVE 'INBOX'
140- `message_id` must be 15-16 char hex, NOT UUIDs or web UI IDs
141 
142### 6. Handle Drafts and Attachments
143 
144**When to use**: User wants to create, edit, or send email drafts, possibly with attachments
145 
146**Tool sequence**:
1471. `GMAIL_CREATE_EMAIL_DRAFT` - Create a new draft [Required]
1482. `GMAIL_UPDATE_DRAFT` - Edit draft content [Optional]
1493. `GMAIL_LIST_DRAFTS` - List existing drafts [Optional]
1504. `GMAIL_SEND_DRAFT` - Send a draft (requires explicit user approval) [Optional]
1515. `GMAIL_GET_ATTACHMENT` - Download attachment from existing message [Optional]
152 
153**Key parameters**:
154- `recipient_email`: Draft recipient
155- `subject`: Draft subject (omit for reply drafts to stay in thread)
156- `body`: Draft content
157- `is_html`: Set `true` for HTML content
158- `attachment`: Object with `{s3key, mimetype, name}`
159- `thread_id`: For reply drafts (leave subject empty to stay in thread)
160 
161**Pitfalls**:
162- Response includes `data.id` (draft_id) AND `data.message.id`; use `data.id` for draft operations
163- Setting subject on a thread reply draft creates a NEW thread instead
164- Attachment capped at ~25MB; base64 overhead can push near-limit files over
165- UPDATE_DRAFT replaces entire content, not patches; include all fields you want to keep
166- HTTP 429 on bulk draft creation; use exponential backoff
167 
168## Common Patterns
169 
170### ID Resolution
171 
172**Label name → Label ID**:
173```
1741. Call GMAIL_LIST_LABELS
1752. Find label by name in response
1763. Extract id field (e.g., 'Label_123')
177```
178 
179**Contact name → Email**:
180```
1811. Call GMAIL_SEARCH_PEOPLE with query=contact_name
1822. Extract emailAddresses from response
183```
184 
185**Thread ID from search**:
186```
1871. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
1882. Extract threadId (15-16 char hex string)
189```
190 
191### Pagination
192 
193- Set `max_results` up to 500 per page
194- Check response for `nextPageToken`
195- Pass token as `page_token` in next request
196- Continue until `nextPageToken` is absent or empty string
197- `resultSizeEstimate` is approximate, not exact
198 
199### Gmail Query Syntax
200 
201**Operators**:
202- `from:sender@example.com` - Emails from sender
203- `to:recipient@example.com` - Emails to recipient
204- `subject:"exact phrase"` - Subject contains exact phrase
205- `is:unread` - Unread messages
206- `is:starred` - Starred messages
207- `is:snoozed` - Snoozed messages
208- `has:attachment` - Has attachments
209- `after:2024/01/01` - After date (YYYY/MM/DD)
210- `before:2024/12/31` - Before date
211- `label:custom_label` - User-created label (use label ID)
212- `in:sent` - In sent folder
213- `category:primary` - Primary category
214 
215**Combinators**:
216- `AND` - Both conditions (default)
217- `OR` - Either condition
218- `NOT` - Exclude condition
219- `()` - Group conditions
220 
221**Examples**:
222- `from:boss@company.com is:unread` - Unread emails from boss
223- `subject:invoice has:attachment after:2024/01/01` - Invoices with attachments this year
224- `(from:alice OR from:bob) is:starred` - Starred emails from Alice or Bob
225 
226## Known Pitfalls
227 
228**ID Formats**:
229- Custom label operations require label IDs (e.g., 'Label_123'), not display names
230- Always call LIST_LABELS first to resolve names to IDs
231- Message IDs are 15-16 char hex strings
232- Do NOT use UUIDs, web UI IDs, or 'thread-f:' prefixes
233 
234**Query Syntax**:
235- Use 'is:' for states (unread, snoozed, starred)
236- Use 'label:' ONLY for user-created labels
237- System labels use 'is:' or 'in:' (e.g., 'is:sent', 'in:inbox')
238 
239**Rate Limits**:
240- BATCH_MODIFY_MESSAGES max 1000 messages per call
241- Heavy use triggers 403/429 rate limits
242- Implement exponential backoff for bulk operations
243 
244**Response Parsing**:
245- Response data may be nested under `data_preview` or `data.messages`
246- Parse defensively with fallbacks
247- Timestamp `messageTimestamp` uses RFC3339 with 'Z' suffix
248- Normalize to '+00:00' for parsing if needed
249 
250**Attachments**:
251- Attachment `s3key` from prior download may expire
252- Use promptly after retrieval
253- Mimetype must include '/' separator
254 
255## Quick Reference
256 
257| Task | Tool Slug | Key Params |
258|------|-----------|------------|
259| Send email | GMAIL_SEND_EMAIL | recipient_email, subject, body, is_html |
260| Reply to thread | GMAIL_REPLY_TO_THREAD | thread_id, message_body, recipient_email |
261| Search emails | GMAIL_FETCH_EMAILS | query, max_results, label_ids, page_token |
262| Get message details | GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID | message_id |
263| List labels | GMAIL_LIST_LABELS | (none) |
264| Create label | GMAIL_CREATE_LABEL | label_name, background_color, text_color |
265| Modify labels bulk | GMAIL_BATCH_MODIFY_MESSAGES | messageIds, addLabelIds, removeLabelIds |
266| Create draft | GMAIL_CREATE_EMAIL_DRAFT | recipient_email, subject, body, thread_id |
267| Send draft | GMAIL_SEND_DRAFT | draft_id |
268| Get attachment | GMAIL_GET_ATTACHMENT | message_id, attachment_id |
269| Search contacts | GMAIL_SEARCH_PEOPLE | query |
270| Get profile | GMAIL_GET_PROFILE | (none) |