AgentSkillsCN

google-gmail-integration

通过 Gmail API 管理 Gmail。搜索和读取邮件、发送消息、管理标签和过滤器、处理附件和自动化邮件工作流。适用于处理 Gmail、读取/发送邮件、搜索收件箱、管理邮件组织或处理邮件数据时使用。

SKILL.md
--- frontmatter
name: google-gmail-integration
description: Manages Gmail through the Gmail API. Search and read emails, send messages, manage labels and filters, handle attachments, and automate email workflows. Use when working with Gmail, reading/sending emails, searching inbox, managing email organization, or processing email data.

Gmail Integration

Comprehensive Gmail integration enabling email search, message management, sending, label organization, attachment handling, and workflow automation through the Gmail API v1.

Quick Start

When asked to work with Gmail:

  1. •Authenticate: Set up OAuth2 credentials (one-time setup)
  2. •Search emails: Find messages by sender, subject, date, or content
  3. •Read messages: Get email content and attachments
  4. •Send emails: Compose and send messages
  5. •Organize: Create labels, apply filters, archive messages
  6. •Automate: Process emails based on rules

Prerequisites

One-Time Setup

1. Enable Gmail API:

bash
# Visit Google Cloud Console
# https://console.cloud.google.com/

# Enable Gmail API for your project
# APIs & Services > Enable APIs and Services > Gmail API

2. Create OAuth2 Credentials:

bash
# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json

3. Install Dependencies:

bash
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client --break-system-packages

4. Initial Authentication:

bash
python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use

See reference/setup-guide.md for detailed setup instructions.

Core Operations

Search Emails

Basic search:

bash
# Search by keyword
python scripts/search_emails.py --query "project update"

# Search by sender
python scripts/search_emails.py --from "boss@company.com"

# Search by subject
python scripts/search_emails.py --subject "Weekly Report"

# Search unread
python scripts/search_emails.py --unread

# Search with label
python scripts/search_emails.py --label "Important"

Advanced search queries:

python
# Combination search
query = "from:boss@company.com subject:urgent is:unread"

# Date ranges
query = "after:2025/01/01 before:2025/01/31"

# Has attachment
query = "has:attachment filename:pdf"

# Size filters
query = "larger:10M"

# Categories
query = "category:primary"
query = "category:social"
query = "category:promotions"

# Boolean operators
query = "(from:alice@company.com OR from:bob@company.com) subject:meeting"

See reference/search-syntax.md for complete search reference.

Read Messages

Get message content:

bash
# Read email
python scripts/read_email.py --message-id MESSAGE_ID

# Get specific format
python scripts/read_email.py --message-id MESSAGE_ID --format full
python scripts/read_email.py --message-id MESSAGE_ID --format minimal
python scripts/read_email.py --message-id MESSAGE_ID --format raw

Extract information:

bash
# Get headers
python scripts/get_headers.py --message-id MESSAGE_ID

# Get body text
python scripts/get_body.py --message-id MESSAGE_ID --format text
python scripts/get_body.py --message-id MESSAGE_ID --format html

# List attachments
python scripts/list_attachments.py --message-id MESSAGE_ID

Download attachments:

bash
# Download all attachments
python scripts/download_attachments.py --message-id MESSAGE_ID --output ./downloads/

# Download specific attachment
python scripts/download_attachments.py --message-id MESSAGE_ID --filename "report.pdf"

Send Emails

Simple send:

bash
# Send plain text
python scripts/send_email.py \
  --to "recipient@example.com" \
  --subject "Hello" \
  --body "Email content here"

# Send to multiple recipients
python scripts/send_email.py \
  --to "user1@example.com,user2@example.com" \
  --cc "manager@example.com" \
  --subject "Team Update" \
  --body "Content here"

Send with attachments:

bash
python scripts/send_email.py \
  --to "recipient@example.com" \
  --subject "Report" \
  --body "Please see attached" \
  --attachments "./report.pdf,./data.xlsx"

Send HTML email:

bash
python scripts/send_email.py \
  --to "recipient@example.com" \
  --subject "Newsletter" \
  --html-body "./newsletter.html"

Reply to message:

bash
python scripts/reply_email.py \
  --message-id MESSAGE_ID \
  --body "Thanks for your email..."

Forward message:

bash
python scripts/forward_email.py \
  --message-id MESSAGE_ID \
  --to "colleague@example.com" \
  --body "FYI"

Label Management

Create labels:

bash
# Create label
python scripts/create_label.py --name "Project Alpha"

# Create nested label
python scripts/create_label.py --name "Projects/Alpha"

# Create with settings
python scripts/create_label.py \
  --name "Important" \
  --label-list-visibility show \
  --message-list-visibility show

Apply labels:

bash
# Add label to message
python scripts/add_label.py --message-id MESSAGE_ID --label "Important"

# Add multiple labels
python scripts/add_label.py --message-id MESSAGE_ID --labels "Work,Urgent"

# Remove label
python scripts/remove_label.py --message-id MESSAGE_ID --label "Inbox"

List labels:

bash
# Get all labels
python scripts/list_labels.py

# Get label ID
python scripts/get_label_id.py --name "Project Alpha"

Message Management

Mark as read/unread:

bash
# Mark as read
python scripts/mark_read.py --message-id MESSAGE_ID

# Mark as unread
python scripts/mark_unread.py --message-id MESSAGE_ID

Archive/Trash:

bash
# Archive message (remove from Inbox)
python scripts/archive_email.py --message-id MESSAGE_ID

# Move to trash
python scripts/trash_email.py --message-id MESSAGE_ID

# Delete permanently
python scripts/delete_email.py --message-id MESSAGE_ID

Batch operations:

bash
# Archive all read emails older than 30 days
python scripts/batch_archive.py --days 30 --read-only

# Delete all emails from sender
python scripts/batch_delete.py --from "spam@example.com"

# Mark all as read
python scripts/batch_mark_read.py --label "Inbox"

Common Workflows

Workflow 1: Process Unread Emails

Scenario: Read unread emails and categorize

bash
# Get unread emails
python scripts/process_unread.py \
  --label-rules rules.json \
  --mark-read

# rules.json example:
{
  "rules": [
    {
      "condition": "from:boss@company.com",
      "action": "add_label",
      "label": "Important"
    },
    {
      "condition": "subject:invoice",
      "action": "add_label",
      "label": "Finance"
    }
  ]
}

Workflow 2: Email to Task Conversion

Scenario: Convert emails into task format

bash
# Extract tasks from emails
python scripts/email_to_tasks.py \
  --query "label:To-Do" \
  --output tasks.json \
  --mark-done

Workflow 3: Automated Responses

Scenario: Send auto-replies based on conditions

bash
# Auto-respond to specific emails
python scripts/auto_respond.py \
  --query "from:client@company.com subject:urgent" \
  --template response_template.txt \
  --label "Auto-Responded"

Workflow 4: Email Backup

Scenario: Download emails for backup

bash
# Backup all emails
python scripts/backup_emails.py \
  --output ./email_backup/ \
  --format mbox

# Backup specific label
python scripts/backup_emails.py \
  --label "Important" \
  --output ./important_backup/ \
  --include-attachments

Workflow 5: Email Analytics

Scenario: Analyze email patterns

bash
# Generate email statistics
python scripts/email_stats.py \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --output stats.json

# Top senders
python scripts/top_senders.py --limit 10

# Email volume by day
python scripts/email_volume.py --days 30

Search Query Syntax

Operators

python
# Sender/Recipient
"from:sender@example.com"
"to:recipient@example.com"
"cc:person@example.com"
"bcc:person@example.com"

# Subject
"subject:meeting"
"subject:(status report)"

# Date
"after:2025/01/01"
"before:2025/12/31"
"older_than:2d"  # days
"newer_than:7d"

# Status
"is:unread"
"is:read"
"is:starred"
"is:important"

# Has
"has:attachment"
"has:drive"
"has:document"
"has:spreadsheet"
"has:presentation"
"has:youtube"

# Size
"larger:10M"
"smaller:1M"
"size:5M"

# Category
"category:primary"
"category:social"
"category:promotions"
"category:updates"
"category:forums"

# Label
"label:important"
"label:work"
"-label:inbox"  # exclude inbox

# Filename
"filename:pdf"
"filename:report.xlsx"

# In
"in:inbox"
"in:trash"
"in:spam"
"in:anywhere"  # includes spam and trash

# Boolean
"OR"  # Must be uppercase
"AND"  # Implied, can be explicit
"-"   # NOT operator
"()"  # Grouping

Example Queries

python
# Unread emails from boss
"from:boss@company.com is:unread"

# Large emails with attachments
"has:attachment larger:5M"

# Recent important unread
"is:important is:unread newer_than:7d"

# Specific sender, subject, with PDF
"from:client@company.com subject:invoice has:attachment filename:pdf"

# Multiple senders
"(from:alice@company.com OR from:bob@company.com) subject:meeting"

# Date range with keyword
"after:2025/01/01 before:2025/01/31 project update"

# Exclude categories
"-category:promotions -category:social is:unread"

Message Format Options

Format Types

python
# Minimal - IDs and labels only
format = 'minimal'

# Full - Complete message with body and headers
format = 'full'

# Raw - Raw MIME message (for forwarding)
format = 'raw'

# Metadata - Headers and labels without body
format = 'metadata'

Accessing Message Parts

python
# Get headers
headers = message['payload']['headers']
for header in headers:
    if header['name'] == 'Subject':
        subject = header['value']
    elif header['name'] == 'From':
        sender = header['value']

# Get body (plain text)
parts = message['payload'].get('parts', [])
for part in parts:
    if part['mimeType'] == 'text/plain':
        body = base64.urlsafe_b64decode(part['body']['data']).decode()

# Get attachments
for part in parts:
    if part.get('filename'):
        attachment_id = part['body']['attachmentId']

Sending Email Formats

Plain Text

python
from email.mime.text import MIMEText
import base64

message = MIMEText('Email body')
message['to'] = 'recipient@example.com'
message['subject'] = 'Test Email'

raw = base64.urlsafe_b64encode(message.as_bytes()).decode()

HTML Email

python
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

message = MIMEMultipart('alternative')
message['to'] = 'recipient@example.com'
message['subject'] = 'HTML Email'

text = "Plain text version"
html = "<html><body><h1>HTML Version</h1></body></html>"

part1 = MIMEText(text, 'plain')
part2 = MIMEText(html, 'html')

message.attach(part1)
message.attach(part2)

With Attachments

python
from email.mime.base import MIMEBase
from email import encoders
import os

message = MIMEMultipart()
message['to'] = 'recipient@example.com'
message['subject'] = 'With Attachment'

# Add body
body = MIMEText('Please see attached')
message.attach(body)

# Add attachment
with open('file.pdf', 'rb') as f:
    part = MIMEBase('application', 'octet-stream')
    part.set_payload(f.read())
    encoders.encode_base64(part)
    part.add_header(
        'Content-Disposition',
        f'attachment; filename={os.path.basename("file.pdf")}'
    )
    message.attach(part)

Label Visibility

Label list visibility:

  • •labelShow - Show in label list
  • •labelHide - Hide from label list

Message list visibility:

  • •show - Show label in message list
  • •hide - Hide label in message list

API Rate Limits

Gmail API quotas:

  • •Queries per day: 1,000,000,000
  • •Queries per 100 seconds per user: 250
  • •Send message: 100 per day per user (can request increase)

Best practices:

  • •Batch requests when possible
  • •Use partial responses to reduce data
  • •Implement exponential backoff
  • •Cache message IDs and metadata

OAuth Scopes

python
# Full access (read, send, delete)
'https://www.googleapis.com/auth/gmail.modify'

# Read-only
'https://www.googleapis.com/auth/gmail.readonly'

# Send only
'https://www.googleapis.com/auth/gmail.send'

# Labels only
'https://www.googleapis.com/auth/gmail.labels'

# Compose (draft and send)
'https://www.googleapis.com/auth/gmail.compose'

# Insert (add messages)
'https://www.googleapis.com/auth/gmail.insert'

# Metadata only
'https://www.googleapis.com/auth/gmail.metadata'

Choose the minimal scope needed for your use case.

Scripts Reference

Authentication:

  • •authenticate.py - Initial OAuth setup
  • •refresh_token.py - Refresh token

Search:

  • •search_emails.py - Search with queries
  • •find_by_sender.py - Quick sender search
  • •find_unread.py - Get unread messages

Read:

  • •read_email.py - Read message content
  • •get_headers.py - Extract headers
  • •get_body.py - Get message body
  • •list_attachments.py - List attachments
  • •download_attachments.py - Download files

Send:

  • •send_email.py - Send new email
  • •reply_email.py - Reply to message
  • •forward_email.py - Forward message
  • •send_bulk.py - Send to multiple recipients

Labels:

  • •create_label.py - Create new label
  • •list_labels.py - Get all labels
  • •add_label.py - Apply label to message
  • •remove_label.py - Remove label

Manage:

  • •mark_read.py - Mark as read
  • •mark_unread.py - Mark as unread
  • •archive_email.py - Archive message
  • •trash_email.py - Move to trash
  • •delete_email.py - Permanent delete

Batch:

  • •batch_archive.py - Archive multiple
  • •batch_delete.py - Delete multiple
  • •batch_mark_read.py - Mark multiple read

Automation:

  • •process_unread.py - Process unread emails
  • •auto_respond.py - Automated responses
  • •email_to_tasks.py - Extract tasks
  • •apply_filters.py - Apply rule-based filters

Analytics:

  • •email_stats.py - Usage statistics
  • •top_senders.py - Most frequent senders
  • •email_volume.py - Volume over time

Best Practices

  1. •Use specific queries: Narrow searches reduce processing time
  2. •Batch operations: Process multiple messages in single API call
  3. •Cache data: Store message IDs and metadata locally
  4. •Handle pagination: Use pageToken for large result sets
  5. •Respect quotas: Monitor API usage
  6. •Error handling: Implement retry logic with backoff
  7. •Secure tokens: Never commit token.json to version control
  8. •Minimal scopes: Request only needed permissions

Integration Examples

See examples/ for complete workflows:

Troubleshooting

"Token expired"

bash
rm token.json
python scripts/authenticate.py

"Insufficient permissions"

  • •Check SCOPES in authenticate.py
  • •Delete token.json and re-auth with new scopes

"Message not found"

  • •Message may have been deleted
  • •Check if in trash or spam

"Rate limit exceeded"

  • •Implement delays between requests
  • •Use batch operations
  • •Request quota increase if needed

Reference Documentation