gmail-integration

This skill enables Gmail integration via the Google Gmail API with OAuth 2.0 authentication. It provides scripts for searching emails, reading content, creating drafts, finding emails needing replies, and archiving messages.

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "gmail-integration" with this command: npx skills add letta-ai/skills/letta-ai-skills-gmail-integration

Gmail Integration

This skill enables Gmail integration via the Google Gmail API with OAuth 2.0 authentication. It provides scripts for searching emails, reading content, creating drafts, finding emails needing replies, and archiving messages.

Prerequisites

Before using this skill, ensure:

  • Python 3.10+ is available

  • A Google Cloud project with Gmail API enabled

  • OAuth 2.0 credentials (credentials.json ) downloaded

  • Required packages installed: google-api-python-client , google-auth-httplib2 , google-auth-oauthlib

OAuth Setup Walkthrough

If the user hasn't set up Gmail API access yet, guide them through these steps:

Step 1: Create Google Cloud Project

  • Go to https://console.cloud.google.com/

  • Create a new project or select existing one

  • Navigate to APIs & Services → Library

  • Search for "Gmail API" and click Enable

Step 2: Configure OAuth Consent Screen

Step 3: Create OAuth Credentials

  • Go to APIs & Services → Credentials

  • Click Create Credentials → OAuth client ID

  • Select Desktop app as application type

  • Download JSON and rename to credentials.json

  • Place in project directory

Step 4: Install Dependencies

uv add google-api-python-client google-auth-httplib2 google-auth-oauthlib

or

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

Step 5: First Authentication

Run any script (e.g., search_emails.py ) - it will open a browser for OAuth consent. After authorization, a token.json is saved for future use.

Email Operations

All scripts are in the scripts/ directory. They share authentication logic and expect credentials.json in the same directory (or path specified via --credentials ).

Search Emails

python scripts/search_emails.py "from:someone@example.com" --max-results 10 python scripts/search_emails.py "subject:meeting after:2024/01/01" python scripts/search_emails.py "is:unread" python scripts/search_emails.py "in:inbox" --json # Output as JSON

Read Email

python scripts/read_email.py <message_id> python scripts/read_email.py <message_id> --format full # includes attachments info

Create Draft

New email

python scripts/create_draft.py --to "recipient@example.com" --subject "Hello" --body "Message content" python scripts/create_draft.py --to "a@example.com" --cc "b@example.com" --subject "Update" --body-file message.txt

HTML email with links

python scripts/create_draft.py --to "recipient@example.com" --subject "Hello" --body "<a href='https://example.com'>link&#x3C;/a>" --html

IMPORTANT: Reply in same thread (required for proper threading!)

python scripts/create_draft.py --to "person@email.com" --subject "Re: Original Subject"
--reply-to "<message-id-header@mail.gmail.com>"
--thread-id "thread_id_here"
--body "Your reply"

⚠️ Threading replies: To reply in the same email thread (not create a new conversation), you MUST include:

  • --reply-to : The Message-ID header from the email you're replying to

  • --thread-id : The Gmail thread ID

To get these values, read the email with read_email.py and check the message metadata, or use this Python snippet:

msg_data = service.users().messages().get(userId="me", id=msg_id, format="metadata", metadataHeaders=["Message-ID"]).execute() thread_id = msg_data.get("threadId") message_id_header = next(h["value"] for h in msg_data["payload"]["headers"] if h["name"] == "Message-ID")

Find Emails Needing Reply

Identifies emails where you haven't replied, or your only reply is an unsent draft:

python scripts/needs_reply.py # Check inbox for emails needing reply python scripts/needs_reply.py --max-results 30 # Check more emails python scripts/needs_reply.py --query "is:important" # Filter to important emails python scripts/needs_reply.py --json # Output as JSON python scripts/needs_reply.py --include-automated # Include newsletters/notifications

Important: By default, needs_reply.py automatically filters out automated/notification emails:

  • Emails from noreply@ , notifications@ , alerts@ , etc.

  • Emails with List-Unsubscribe headers (newsletters)

  • Common SaaS notification patterns (monitoring, dev tools, finance, calendar, etc.)

Use --include-automated to see all emails including these.

Status indicators:

  • 🔴 UNREAD - New email you haven't read

  • 📝 DRAFT UNSENT - You started a reply but never sent it

  • ⏳ NEEDS REPLY - Read but not replied to

Archive Emails

Archive emails by removing the INBOX label (requires gmail.modify scope):

service.users().messages().modify( userId="me", id=msg_id, body={"removeLabelIds": ["INBOX"]} ).execute()

For bulk archiving, use batch requests (max 100 per batch):

batch = service.new_batch_http_request() for msg in messages[:50]: # Keep under 100 limit batch.add(service.users().messages().modify( userId="me", id=msg["id"], body={"removeLabelIds": ["INBOX"]} )) batch.execute()

Common Workflows

Find and reply to an email (properly threaded)

  • Search for the email: search_emails.py "from:person subject:topic" --json

  • Get the message ID from results, then read it: read_email.py <message_id>

  • Get threading info (thread_id and Message-ID header) from the email metadata

  • Create a threaded draft reply: create_draft.py --to "person@email.com" --subject "Re: topic"
    --reply-to "<Message-ID-header>" --thread-id "<thread_id>"
    --body "Your reply"

Find emails needing reply

  • Run: needs_reply.py --max-results 30

  • Review emails marked as 🔴 UNREAD, 📝 DRAFT UNSENT, or ⏳ NEEDS REPLY

  • For each email needing reply, get its thread_id and Message-ID, then draft a threaded response

Inbox triage (complete workflow)

  • Run needs_reply.py --max-results 50 to get all emails needing attention

  • Filter out noise - Identify and archive:

  • Newsletters (from: noreply, notifications, news@, etc.)

  • Receipts and invoices (from: receipts@, invoice@)

  • Automated alerts (from: alerts@, alert@)

  • Marketing emails (promotions, etc.)

  • Transaction notifications (banking, expense tools)

  • Categorize real emails:

  • 📝 DRAFT UNSENT - You started but didn't send (finish or delete draft)

  • 🔴 UNREAD from real people - Read and respond

  • ⏳ NEEDS REPLY - Prioritize by importance

  • Draft threaded responses (always use --reply-to and --thread-id)

  • Archive remaining notifications in bulk

Identifying newsletters vs real emails

Common newsletter/notification patterns to archive:

  • from:noreply or from:no-reply

  • from:notifications@ or from:alerts@

  • from:news@ or from:newsletter@

  • from:*@substack.com (newsletters)

  • from:receipts@ or from:invoice@

  • from:*@stripe.com (payment receipts)

  • Monitoring: Datadog, PlanetScale, Better Stack, etc.

Drafting Emails Best Practices

When drafting emails:

  • Always use HTML format (--html ) when including links

  • Hyperlink text like "here" rather than showing raw URLs

  • Include proper threading with --reply-to and --thread-id for replies

  • Consider creating a memory block to store the user's email style preferences (greeting, signature, tone)

Search Query Syntax

For complex searches, see reference/search_operators.md for Gmail search operators.

Common operators:

  • from: / to:

  • Filter by sender/recipient

  • subject:

  • Search in subject line

  • is:unread / is:read

  • Filter by read status

  • in:inbox / in:sent / in:drafts

  • Filter by location

  • after: / before:

  • Date filters (YYYY/MM/DD format)

  • has:attachment

  • Emails with attachments

  • larger: / smaller:

  • Filter by size

API Limits & Gotchas

  • Batch request limit: Max 100 requests per batch (use 50 to be safe)

  • Rate limits: Gmail API has daily quotas; batch operations help stay under limits

  • Threading gotcha: Drafts without --reply-to and --thread-id create NEW threads, not replies

  • Draft detection: Unsent drafts don't count as replies - needs_reply.py handles this correctly

  • Token expiry: Tokens auto-refresh, but if authentication fails, delete token.json and re-auth

Security Notes

  • credentials.json contains OAuth client secrets - do not commit to version control

  • token.json contains access tokens - do not share or commit

  • Add both to .gitignore

  • Tokens can be revoked at https://myaccount.google.com/permissions

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

extracting-pdf-text

No summary provided by upstream source.

Repository SourceNeeds Review
181-letta-ai
General

video-processing

No summary provided by upstream source.

Repository SourceNeeds Review
152-letta-ai
General

google-workspace

No summary provided by upstream source.

Repository SourceNeeds Review
101-letta-ai
General

portfolio-optimization

No summary provided by upstream source.

Repository SourceNeeds Review
96-letta-ai