gmail-adapter

name	gmail-adapter
description	Gmail email sending adapter for the 100X Outreach System. Use this skill to send emails via Gmail using the user's own OAuth2 credentials. This is a core skill for email campaigns and workflow email steps.
allowed-tools	["Bash","Read","Write","Glob","Grep","TodoWrite","AskUserQuestion"]

Gmail Adapter Skill

Send emails via Gmail API using the user's own OAuth2 credentials.

IMPORTANT: User's Own Gmail Account

This skill uses the user's Gmail account with their own OAuth2 credentials:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• SENDER_EMAIL

No Browser-Use needed for Gmail - direct API access via Python.

When to Use This Skill

Use this skill when the user wants to:

• Send individual emails
• Run email campaigns
• Send follow-up emails
• Integrate email into workflows
• Use Gmail templates

Available Email Actions

Action	Description
send	Send a single email
send_campaign	Send to multiple recipients
send_with_template	Send using a template

Available Templates

Outreach (templates/email/outreach/)

• cold_email.md - Cold outreach email
• warm_intro.md - Warm introduction
• referral_intro.md - Referral introduction
• partnership.md - Partnership proposal
• investor_pitch.md - Investor pitch

Follow-up (templates/email/follow-up/)

• no_response_1.md - First follow-up
• no_response_2.md - Second follow-up
• no_response_final.md - Final follow-up
• after_meeting.md - After meeting
• after_call.md - After call
• check_in.md - Check in

Promotional (templates/email/promotional/)

• product_launch.md - Product launch
• feature_announcement.md - Feature announcement
• discount_offer.md - Discount offer
• webinar_invite.md - Webinar invitation

Newsletters (templates/email/newsletters/)

• weekly_digest.md - Weekly digest
• monthly_update.md - Monthly update
• announcement.md - Announcement

Setup Required

1. Google Cloud Console Setup

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Gmail API:
   • Go to "APIs & Services" > "Library"
   • Search for "Gmail API"
   • Click "Enable"
4. Create OAuth2 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Select "Desktop app"
   • Download the credentials

2. Environment Variables

Add to .env:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
SENDER_EMAIL=[e-mail]
SENDER_NAME=Your Name

3. First-Time Authentication

On first use, a browser window will open for OAuth2 authentication. Grant permission to send emails on your behalf. Token is saved for future use.

Step-by-Step Execution Flow

Step 1: Check Gmail Configuration

# Check if Gmail is configured
python .claude/scripts/gmail_client.py status

Step 2: Load and Render Template

# List available email templates
python .claude/scripts/template_loader.py list --platform email --category outreach

# Render a template with variables
python .claude/scripts/template_loader.py render --path email/outreach/cold_email --var first_name "John" --var company "Acme Inc" --var my_name "Your Name"

Step 3: Send Email

# Send a single email
python .claude/scripts/gmail_client.py send --to "[e-mail]" --subject "Subject Line" --body "Email body text"

# Send with template
python .claude/scripts/gmail_client.py send --to "[e-mail]" --template "email/outreach/cold_email" --var first_name "John" --var company "Acme"

Step 4: Record Action (for rate limiting)

# Record successful email
python .claude/scripts/rate_limiter.py --user default --platform gmail --action send --record --success --target "[e-mail]"

Example: Send Cold Outreach Email

User: "Send a cold email to [e-mail] introducing myself"

You should:

1. Check configuration:

   python .claude/scripts/gmail_client.py status
   

2. Render template:

   python .claude/scripts/template_loader.py render --path email/outreach/cold_email --var first_name "John" --var company "Acme Inc" --var my_name "Your Name"
   

   → Get rendered subject and body

3. Send email:

   python .claude/scripts/gmail_client.py send --to "[e-mail]" --subject "RENDERED_SUBJECT" --body "RENDERED_BODY"
   

4. Record action:

   python .claude/scripts/rate_limiter.py --user default --platform gmail --action send --record --success --target "[e-mail]"
   

5. Report:

   Email sent successfully to [e-mail]!
   Subject: [Subject line]
   

Example: Email Campaign (Single Approval)

User: "Send cold emails to these 10 contacts from my Google Sheet"

You should:

1. Show preview:

   ═══════════════════════════════════════════
   EMAIL CAMPAIGN - 10 RECIPIENTS
   ═══════════════════════════════════════════
   
   Template: Cold Outreach
   Subject: "Quick question about [company]"
   
   Recipients:
   1. [e-mail] - John Smith (CEO at Acme)
   2. [e-mail] - Jane Doe (CTO at TechCo)
   3. [e-mail] - Bob Wilson (Founder at Startup)
   ... (7 more)
   
   Estimated time: ~15 minutes (with delays)
   ═══════════════════════════════════════════
   
   Proceed with all 10 emails?
   

2. After single approval, execute ALL autonomously:

   • Render template for each recipient
   • Send email via Gmail API
   • Wait for rate-limited delay (1-3 minutes)
   • Report progress after each email
   • Final summary when complete

Rate Limits

Action	Daily Limit	Min Delay	Max Delay
send	100	60s	180s
send_campaign	100	60s	180s

Check Rate Limits

# Check remaining emails
python .claude/scripts/rate_limiter.py --user default --platform gmail --remaining

# Check if send is allowed
python .claude/scripts/rate_limiter.py --user default --platform gmail --action send --check

Integration with Workflows

Gmail can be used as a step in multi-platform workflows:

phases:
  - name: "connect_linkedin"
    platform: "linkedin"
    action: "connect"

  - name: "send_email"
    platform: "gmail"
    action: "send"
    template: "email/outreach/warm_intro"
    delay_after: "24-48 hours"

Gmail vs Browser-Use

Feature	Gmail API	Browser-Use
Speed	Fast (direct API)	Slower (browser)
Reliability	Very reliable	May need retries
Setup	OAuth2 required	Browser profile
Use case	Email campaigns	Social platforms

Gmail API is preferred for email - faster, more reliable, and easier to manage at scale.

Troubleshooting

Authentication Failed

1. Check GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
2. Delete token.json and re-authenticate
3. Ensure Gmail API is enabled in Google Cloud Console

Rate Limit Exceeded

1. Gmail has daily sending limits (varies by account type)
2. The system enforces conservative limits (100/day)
3. Check remaining limit before bulk sends

Emails Going to Spam

1. Warm up new sender accounts gradually
2. Use personalized templates
3. Avoid spam trigger words
4. Ensure SPF/DKIM records are set up