Gmail Outreach

Gmail Outreach — Touchbase + Unsubscribe

Outbound email management: maintain relationships and remove noise. Combines two functions into one skill.

Prerequisites

• OAuth tokens in ~/.gmail-{account}/credentials.json
• Client credentials in ~/.gmail-mcp/oauth-env.json
• Contact CSVs normalized (see contact-manager skill)
• gmail-multi-account skill configured

Part 1: Touchbase — Relationship Maintenance

Identify contacts due for periodic outreach and draft check-in messages.

Contact Cadence Rules

Touchbase Workflow

1. Load contact CSV for the account
2. Check last interaction date (search Gmail for sent-to + received-from)
3. Filter contacts past their cadence threshold
4. Sort by priority: clients > prospects > vendors > network
5. Draft personalized check-in messages using communication style profiles (#1986)

Draft Templates

Client check-in:

{FirstName},

Hope all is well on your end. It's been a few weeks since we last connected — just wanted to check in and see if there's anything I can help with on the [project] front.

Let me know if you'd like to catch up briefly.

Thank you,
Vamsee

Touchbase with GTM prospect:

{FirstName},

I wanted to follow up on our earlier conversation about [topic]. I've been working on [recent project/capability] and thought it might be relevant to what you're doing at [Company].

Would love to catch up when you have a moment.

Thank you,
Vamsee Achanta, P.E.

Network check-in:

Hey {FirstName},

Long time no talk. Hope [work/family/life] has been treating you well.

Let's catch up when you get a chance.

Vamsee

Per-Account Style Profiles

Load the full style profile for the sending account before drafting any message:

config/email/ace-style.yaml       — professional-technical, concise (2-5 sentences)
config/email/personal-style.yaml  — casual-terse, ultra-short (1-2 sentences)
config/email/skestates-style.yaml — business-formal-warm, medium (3-6 sentences)

Each profile defines greeting, closing, signature, tone, formality rules, and calibration examples. Check formality_rules to adjust for context (new client vs ongoing thread, vendor follow-up vs family matters). See config/email/README.md for the full usage guide. Reference: #1986.

Quick reference (see YAML files for complete rules):

Execution

import json, urllib.request, urllib.parse, os
from datetime import datetime, timedelta

def search_gmail_for_contact(email, account, token):
    """Check for last interaction with an email address"""
    query = urllib.parse.quote(f"from:{email} OR to:{email}")
    result = gmail_get(f"users/me/messages?q={query}&maxResults=1", token)
    if result.get("messages"):
        msg = gmail_get(f"users/me/messages/{result['messages'][0]['id']}?format=metadata", token)
        hdrs = {h["name"]: h["value"] for h in msg.get("payload", {}).get("headers", [])}
        return hdrs.get("Date", "")
    return None

def get_touchbase_candidates(account, contacts_csv, cadence_days=30):
    """Get contacts due for touchbase"""
    import csv
    cutoff = datetime.now() - timedelta(days=cadence_days)
    token = refresh_token(account)
    candidates = []

    with open(contacts_csv) as f:
        reader = csv.DictReader(f)
        for row in reader:
            email = row.get("email", "")
            category = row.get("category", "")
            last_contact = search_gmail_for_contact(email, account, token)
            if last_contact:
                contact_date = datetime.strptime(last_contact[:24], "%a, %d %b %Y %H:%M:%S")
                if contact_date < cutoff:
                    candidates.append({
                        "email": email,
                        "name": row.get("name", ""),
                        "category": category,
                        "last_contact": last_contact,
                    })
    return candidates

Part 2: Unsubscribe — Batch Noise Removal

Identify emails with List-Unsubscribe headers and batch process unsubscribes.

Unsubscribe Detection

def find_unsubscribe_candidates(account, max_results=200):
    """Scan inbox for emails with List-Unsubscribe headers"""
    token = refresh_token(account)
    search = gmail_get(f"users/me/messages?maxResults={max_results}", token)

    candidates = []
    for msg_stab in search.get("messages", []):
        detail = gmail_get(
            f"users/me/messages/{msg_stab['id']}?format=metadata&metadataHeaders=List-Unsubscribe&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date&metadataHeaders=List-Unsubscribe-Post",
            token
        )
        hdrs = {h["name"]: h["value"] for h in detail.get("payload", {}).get("headers", [])}
        
        if hdrs.get("List-Unsubscribe"):
            method = "http" if hdrs["List-Unsubscribe"].startswith("http") else "mailto"
            ""))
            candidates.append({
                "msg_id": msg_stab["id"],
                "from": hdrs.get("From", ""),
                "subject": hdrs.get("Subject", ""),
                "date": hdrs.get("Date", ""),
                "unsubscribe_url": hdrs.get("List-Unsubscribe", ""),
                "method": method,
                "one_click": one_click,
            })
    return candidates

Unsubscribe Execution

HTTP/one-click unsubscribe (POST to the URL):

def execute_unsubscribe(url, method="http"):
    """Execute unsubscribe via HTTP POST or mailto"""
    if method == "http" and url.startswith("http"):
        req = urllib.request.Request(url, method="POST")
        try:
            with urllib.request.urlopen(req, timeout=10) as resp:
                return {"status": resp.status, "success": True}
        except Exception as e:
            return {"error": str(e), "success": False}
    elif method == "mailto":
        # Send empty email to unsubscribe address
        mailto_addr = url.replace("<mailto:", "").replace(">", "").split(",")[0]
        return {"method": "mailto", "address": mailto_addr}
    return {"error": "unsupported method", "success": False}

Unsubscribe + Delete Pipeline

def unsubscribe_and_delete(account, domains_to_remove, max_per_domain=500, dry_run=False):
    """Unsubscribe from domains and delete matching emails"""
    token = refresh_token(account)
    stats = {"unsubscribed": 0, "deleted": 0, "skipped": 0}

    for domain in domains_to_remove:
        query = f"from:{domain} has:List-Unsubscribe"
        search = gmail_get(f"users/me/messages?q={urllib.parse.quote(query)}&maxResults={max_per_domain}", token)
        
        for msg_stab in search.get("messages", []):
            detail = gmail_get(f"users/me/messages/{msg_stab['id']}?format=metadata", token)
            hdrs = {h["name"]: h["value"] for h in detail.get("payload", {}).get("headers", [])}
            unsub_url = hdrs.get("List-Unsubscribe", "")
            
            if unsub_url:
                method = "http" if unsub_url.startswith("http") else "mailto"
                if not dry_run:
                    execute_unsubscribe(unsub_url, method)
                    gmail_post(f"users/me/messages/{msg_stab['id']}/trash", token, {})
                stats["unsubscribed"] += 1
                stats["deleted"] += 1
            else:
                stats["skipped"] += 1

    return stats

Safety Rules

1. ALWAYS show unsubscribe candidates to user before executing
2. First run: execute in dry_run mode and show what would happen
3. Never unsubscribe domains marked as REVIEW in email-routing.yaml
4. Touchbase drafts: ALWAYS require user approval before sending
5. Batch unsubscribe: max 20 domains per batch to avoid Gmail rate limits
6. Log all unsubscribe actions — track what was unsubscribed and when
7. Unsubscribe list is maintained in ~/.hermes/unsubscribe-log.yaml

Usage Examples

Find touchbase candidates for ace account

cd /mnt/local-analysis/workspace-hub
# Load contact CSV, check last interaction dates, produce candidate list

Find unsubscribe candidates

candidates = find_unsubscribe_candidates("personal", max_results=200)
# Display: sender, subject, unsubscribe method (HTTP/mailto), one-click support

Execute batch unsubscribe (after user approval)

domains = ["promote.weebly.com", "e.swimoutlet.com", "lists.wikimedia.org"]
stats = unsubscribe_and_delete("personal", domains, dry_run=False)
# Returns: {"unsubscribed": N, "deleted": N, "skipped": N}

Unsubscribe Watchlist (from email-routing.yaml)

CONFIRMED DELETE (safe to unsubscribe + delete):
  collide.io, skylineseven.ccsend.com, promote.weebly.com
  e.swimoutlet.com, email.myflighthub.com, mail.urbanairparks.com
  e.stantonoptical.com, lists.wikimedia.org, jongordon.com
  atticbuddies.com, email.theparkingspot.com, marketing.goindigo.in
  deeplearning.ai, gamemail.com, suzeorman.com

REVIEW FIRST (do not auto-unsubscribe):
  substack.com, info.marineinsight.com, indianstarllc.ccsend.com
  rigzonemail.com, m.learn.coursera.org, irctc.co.in
  info.dpam.com, blueskysfund.com, cincsystems.net

Deprecation Notice

This skill replaces:

• gmail-touchbase — functionality merged into this skill
• gmail-unsubscribe — functionality merged into this skill

Pitfalls

1. one-click unsubscribe (List-Unsubscribe-Post header) requires POST to the URL with List-Unsubscribe header set to "1"
2. Some unsubscribe URLs are POST-only and require specific headers — test before batch
3. Touchbase cadence: use Gmail search for last interaction, not local timestamps (more reliable)
4. Don't touchbase with contacts who explicitly opted out — check "do_not_contact" column in contact CSV
5. Gmail API rate limits — batch requests with 0.15s delays between calls
6. Touchbase emails should feel personal — avoid obvious template language
7. Always cross-reference against email-routing.yaml REVIEW list before auto-unsubscribing