gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator/skills/gmail-assistant/references/api-reference.md

gmaillm API Reference

Complete reference for gmaillm Python library and CLI.

Table of Contents

• Python Library API
• CLI Commands
• Models & Types
• Gmail Search Syntax

---

Python Library API

GmailClient

from gmaillm import GmailClient

client = GmailClient(
    credentials_file="/Users/wz/.gmail-mcp/credentials.json",  # optional
    oauth_keys_file="/Users/wz/Desktop/OAuth2/gcp-oauth.keys.json"  # optional
)

Core Operations

verify_setup()

Verify authentication and basic functionality.

result = client.verify_setup()
# Returns: {
#     'auth': bool,
#     'folders': int,
#     'inbox_accessible': bool,
#     'errors': List[str]
# }

list_emails()

List emails with pagination.

result = client.list_emails(
    folder='INBOX',        # Gmail label/folder
    max_results=10,        # 1-50, default 10
    page_token=None,       # For pagination
    query=None             # Gmail search query
)
# Returns: SearchResult

Example:

# First page
result = client.list_emails(folder='INBOX', max_results=10)
for email in result.emails:
    print(email.to_markdown())

# Next page
if result.next_page_token:
    next_result = client.list_emails(
        folder='INBOX',
        max_results=10,
        page_token=result.next_page_token
    )

read_email()

Read a specific email.

email = client.read_email(
    message_id,           # Required: message ID
    format="summary"      # "summary" | "full"
)
# Returns: EmailSummary | EmailFull

Formats:

• "summary" (default): ID, from, to, subject, date, snippet, labels
• "full": Everything + body (plain text & HTML), attachments

Example:

# Get summary first (minimal context)
summary = client.read_email(msg_id, format="summary")
print(summary.to_markdown())

# Get full if body needed
full = client.read_email(msg_id, format="full")
print(full.body_plain)

search_emails()

Search emails using Gmail query syntax.

result = client.search_emails(
    query,                # Gmail search query
    folder='INBOX',       # Optional: limit to folder
    max_results=10        # 1-50, default 10
)
# Returns: SearchResult

Example:

result = client.search_emails(
    query="from:professor@university.edu has:attachment after:2024/10/01",
    max_results=20
)

get_thread()

Get all emails in a conversation thread.

messages = client.get_thread(message_id)
# Returns: List[EmailSummary] (chronologically sorted)

Example:

thread = client.get_thread(msg_id)
print(f"Thread has {len(thread)} messages")
for i, msg in enumerate(thread, 1):
    print(f"[{i}] {msg.from_.email} → {msg.to[0].email if msg.to else 'unknown'}")
    print(f"    {msg.subject}")

send_email()

Send a new email.

from gmaillm import SendEmailRequest

request = SendEmailRequest(
    to=["user@example.com"],           # Required: list of recipients
    subject="Subject",                  # Required: string
    body="Email body",                  # Required: string
    cc=["cc@example.com"],             # Optional: list
    attachments=["/path/to/file.pdf"]  # Optional: list of file paths
)

response = client.send_email(request)
# Returns: SendEmailResponse

Example:

request = SendEmailRequest(
    to=["friend@gmail.com"],
    subject="Quick Question",
    body="Hey, are you free tomorrow?\n\nBest,\nWarren"
)
response = client.send_email(request)
if response.success:
    print(f"Sent! Message ID: {response.message_id}")

reply_email()

Reply to an existing email.

response = client.reply_email(
    message_id,           # Required: original message ID
    body,                 # Required: reply body text
    reply_all=False       # Optional: reply to all recipients
)
# Returns: SendEmailResponse

Example:

response = client.reply_email(
    message_id="19abc123",
    body="Thanks for the update!",
    reply_all=False
)

get_folders()

List all Gmail labels/folders.

folders = client.get_folders()
# Returns: List[Folder]

Example:

folders = client.get_folders()
for folder in folders:
    print(f"{folder.name}: {folder.unread_count} unread")

modify_labels()

Add or remove labels from an email.

client.modify_labels(
    message_id,                    # Required: message ID
    add_labels=['STARRED'],        # Optional: labels to add
    remove_labels=['UNREAD']       # Optional: labels to remove
)

Common operations:

# Mark as read
client.modify_labels(msg_id, remove_labels=['UNREAD'])

# Star email
client.modify_labels(msg_id, add_labels=['STARRED'])

# Archive (remove from inbox)
client.modify_labels(msg_id, remove_labels=['INBOX'])

# Move to trash
client.modify_labels(msg_id, add_labels=['TRASH'])

delete_email()

Delete a single email.

success = client.delete_email(
    message_id,           # Required: message ID
    permanent=False       # Optional: True = permanent, False = trash
)
# Returns: bool

---

CLI Commands

All commands use the mail entry point. For now, use:

python3 -m gmaillm.cli <command>

Or create an alias:

alias gmail='python3 -m gmaillm.cli'

gmail verify

Check authentication and setup.

gmail verify

gmail list

List emails from a folder.

gmail list                          # Default: INBOX, 10 results
gmail list --folder SENT            # List from SENT folder
gmail list --max 20                 # Get 20 results
gmail list --query "is:unread"     # With search query

Options:

• --folder FOLDER - Folder/label to list from (default: INBOX)
• --max N - Maximum results (1-50, default: 10)
• --query QUERY - Gmail search query

gmail read

Read a specific email.

gmail read <message_id>        # Summary (default)
gmail read <message_id> --full # Full body

Options:

• --full - Show full email body (instead of summary)

gmail thread

Show entire email conversation.

gmail thread <message_id>

gmail search

Search emails.

gmail search "from:example@gmail.com"
gmail search "has:attachment" --max 20
gmail search "is:unread after:2024/10/01" --folder INBOX

Options:

• --folder FOLDER - Limit search to folder (default: INBOX)
• --max N - Maximum results (1-50, default: 10)

gmail reply

Reply to an email.

gmail reply <message_id> --body "Thanks!"
gmail reply <message_id> --body "Sounds good" --reply-all

Options:

• --body TEXT - Required: reply body text
• --reply-all - Reply to all recipients (default: reply to sender only)

Confirmation: Always shows preview and asks "Send? (y/n/yolo)"

gmail send

Send a new email.

gmail send \
  --to user@example.com \
  --subject "Subject" \
  --body "Body text"

# With multiple recipients
gmail send \
  --to user1@example.com user2@example.com \
  --cc boss@example.com \
  --subject "Report" \
  --body "See attached" \
  --attachments report.pdf data.xlsx

# Skip confirmation with YOLO mode
gmail send --to user@example.com --subject "Test" --body "Hi" --yolo

Options:

• --to EMAIL [EMAIL...] - Required: recipient email(s)
• --subject TEXT - Required: email subject
• --body TEXT - Required: email body
• --cc EMAIL [EMAIL...] - Optional: CC recipient(s)
• --attachments FILE [FILE...] - Optional: file path(s) to attach
• --yolo - Skip confirmation, send immediately

gmail folders

List all available folders/labels.

gmail folders

---

Models & Types

EmailSummary

Brief email overview (minimal context).

Fields:

• message_id: str - Unique message ID
• thread_id: str - Thread/conversation ID
• from_: EmailAddress - Sender
• to: List[EmailAddress] - Recipients
• subject: str - Email subject
• date: datetime - Sent date/time
• snippet: str - Short preview (~100 chars)
• labels: List[str] - Gmail labels
• has_attachments: bool - Has files attached
• is_unread: bool - Unread status

Methods:

• to_markdown() -> str - Formatted output

EmailFull

Complete email with body (use sparingly).

Fields: (All EmailSummary fields plus:)

• body_plain: str - Plain text body
• body_html: str - HTML body (if exists)
• attachments: List[Attachment] - Attached files
• headers: Dict[str, str] - All email headers

EmailAddress

Email address with optional name.

Fields:

• email: str - Email address
• name: Optional[str] - Display name

SearchResult

Paginated search results.

Fields:

• emails: List[EmailSummary] - Email summaries
• total_count: int - Total matching emails
• query: str - Search query used
• next_page_token: Optional[str] - Token for next page

Methods:

• to_markdown() -> str - Formatted output

Folder

Gmail label/folder info.

Fields:

• id: str - Label ID
• name: str - Label name
• type: str - 'system' or 'user'
• message_count: Optional[int] - Total messages
• unread_count: Optional[int] - Unread messages

SendEmailRequest

Email sending parameters.

Fields:

• to: List[str] - Required: recipient emails
• subject: str - Required: subject line
• body: str - Required: email body
• cc: Optional[List[str]] - CC recipients
• attachments: Optional[List[str]] - File paths

SendEmailResponse

Email send result.

Fields:

• success: bool - Send succeeded
• message_id: str - Sent message ID
• thread_id: str - Thread ID
• error: Optional[str] - Error message if failed

---

Gmail Search Syntax

Basic Operators

From/To:

from:user@example.com       # Emails from user
to:user@example.com         # Emails to user
cc:user@example.com         # CC'd to user
bcc:user@example.com        # BCC'd to user

Subject:

subject:invoice             # Subject contains "invoice"
subject:(invoice payment)   # Subject contains both words

Dates:

after:2024/10/01           # After date
before:2024/10/31          # Before date
older_than:7d              # Older than 7 days
newer_than:2d              # Newer than 2 days

Status:

is:unread                  # Unread emails
is:read                    # Read emails
is:starred                 # Starred emails
is:important               # Marked important

Content:

has:attachment             # Has attachments
has:drive                  # Has Google Drive attachment
has:document               # Has document attachment
has:spreadsheet            # Has spreadsheet
has:presentation           # Has presentation

Size:

size:1000000              # Larger than 1MB
larger:10M                # Larger than 10MB
smaller:5M                # Smaller than 5MB

Labels:

label:inbox               # In INBOX
label:sent                # In SENT
-label:inbox              # NOT in inbox (archived)

Boolean Operators

AND     # Both conditions (implicit, can be omitted)
OR      # Either condition
-       # NOT (exclude)
()      # Grouping

Examples:

from:professor@edu AND has:attachment
from:alice OR from:bob
subject:report -from:manager
(from:alice OR from:bob) has:attachment

Advanced Examples

Unread emails from specific person with attachments:

from:john@example.com is:unread has:attachment

Recent emails about project:

subject:project after:2024/10/01 -label:trash

Important emails not yet read:

is:important is:unread -from:noreply

Large emails with PDFs:

has:attachment filename:pdf larger:5M

Emails in thread:

in:thread_id

---

Quick Reference Card

Python Library Cheat Sheet

from gmaillm import GmailClient, SendEmailRequest

client = GmailClient()

# List
result = client.list_emails(folder='INBOX', max_results=10)

# Read
email = client.read_email(msg_id, format="summary")
email = client.read_email(msg_id, format="full")

# Search
result = client.search_emails("from:user@example.com has:attachment")

# Thread
thread = client.get_thread(msg_id)

# Send
request = SendEmailRequest(to=["user@example.com"], subject="Hi", body="Hello")
response = client.send_email(request)

# Reply
response = client.reply_email(msg_id, body="Thanks!", reply_all=False)

# Labels
client.modify_labels(msg_id, add_labels=['STARRED'], remove_labels=['UNREAD'])

CLI Cheat Sheet

gmail verify                                    # Check setup
gmail list --folder INBOX --max 10             # List emails
gmail read <id> --full                         # Read email
gmail thread <id>                              # View conversation
gmail search "is:unread" --max 20              # Search
gmail reply <id> --body "Thanks!"              # Reply
gmail send --to user@example.com \            # Send
  --subject "Test" --body "Hi"
gmail folders                                  # List folders

---

Authentication

Uses existing Gmail MCP OAuth2 credentials:

• Credentials: /Users/wz/.gmail-mcp/credentials.json
• OAuth Keys: /Users/wz/Desktop/OAuth2/gcp-oauth.keys.json

Tokens auto-refresh. If authentication fails:

1. Check credential files exist
2. Verify OAuth tokens not expired
3. Run gmail verify to diagnose

---

Common Patterns

Progressive Disclosure

# Always start with summary
summaries = client.list_emails(max_results=10)

# Only get full content when needed
for summary in summaries.emails:
    if "important keyword" in summary.subject.lower():
        full = client.read_email(summary.message_id, format="full")
        # Process full email

Pagination

all_emails = []
page_token = None

while True:
    result = client.list_emails(max_results=50, page_token=page_token)
    all_emails.extend(result.emails)

    if not result.next_page_token:
        break
    page_token = result.next_page_token

Error Handling

try:
    response = client.send_email(request)
    if response.success:
        print(f"Sent: {response.message_id}")
    else:
        print(f"Failed: {response.error}")
except RuntimeError as e:
    print(f"Error: {e}")

---

Style Guide System

Located at references/email-styles/:

• STYLE.md - Precise writing guidelines
• CLEAR.md - Brevity guidelines
• learned/patterns.md - User-specific patterns (grows over time)

When drafting emails, Claude:

1. Searches sent emails to recipient
2. Extracts patterns (greeting, tone, sign-off)
3. Applies STYLE + CLEAR + learned patterns
4. Shows preview for confirmation

---

Additional Resources

• SKILL.md - Complete usage guide with workflows
• README.md - Quick start and installation
• references/usage_examples.md - 16 detailed examples
• references/gmail_search_syntax.md - Complete search reference