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