Gmail Automation

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