aaaaqwq/email-outreach-run

Email Outreach Agent - Run Skill

Send mass email campaigns with personalization and approval workflow

When to use

• User wants to send email outreach campaign
• "send emails to [segment]"
• "email outreach to new leads"
• "send training reminder to participants"

Prerequisites

1. Gmail API authenticated (google-auth skill if needed)
2. CRM data available (sales/crm/)
3. Template or AI mode

How to execute

Step 1: Determine campaign type

CRM Segment Mode:

cd $AGENTS_PATH/email-outreach

python3 email-outreach_agent.py \
  --segment "stage=new AND product_id=prod-labeling" \
  --template templates/cold_outreach.txt

Manual CSV Mode:

python3 email-outreach_agent.py \
  --recipients /path/to/recipients.csv \
  --template templates/training_reminder.txt

AI-Generated Mode:

python3 email-outreach_agent.py \
  --segment "stage=qualified" \
  --ai-mode \
  --subject "Following up on our conversation"

Step 2: Always dry-run first

python3 email-outreach_agent.py \
  --segment "..." \
  --template templates/cold_outreach.txt \
  --dry-run

Step 3: Review approval prompt

Agent shows:

• Number of recipients
• Subject line
• First 3 sample emails

Options:

• [A] - Approve and send
• [T] - Send test to [email protected]
• [C] - Cancel (save draft)

Step 4: Check results

# Summary
ls -lh $GOOGLE_TOOLS_PATH/data/email_outreach_summaries/

# Agent log
cat $GOOGLE_TOOLS_PATH/data/email_outreach_log.json | jq '.[-1]'

# CRM activities
tail -10 $CRM_PATH/activities.csv

Templates

Available templates in agents/email-outreach/templates/:

• cold_outreach.txt - For new leads
• follow_up.txt - Follow-up to previous contact
• training_reminder.txt - Event/training reminders

Placeholders:

• {name} - Full name
• {first_name} - First name
• {last_name} - Last name
• {company} / {company_name} - Company name
• {role} - Job role

Segment Queries

Filter CRM leads:

# New leads for specific product
--segment "stage=new AND product_id=prod-labeling"

# Qualified leads
--segment "stage=qualified"

# Custom filters
--segment "stage=new AND product_id=prod-training"

Rate Limits (OWNER DECISIONS)

• Max: 50 emails/day
• Rate: 1-2 sec between emails
• Cooldown: 7 days (same person+product)

Error Handling

| Error | Action | |-------|--------| | "Gmail credentials not found" | Run google-auth skill | | "Daily limit reached" | Wait until tomorrow | | "No recipients match" | Check segment query, verify CRM data | | "Invalid email" | Check CSV, emails will be skipped |

Manual CSV Format

email,first_name,last_name,company_name
[email protected],John,Doe,Example Corp
[email protected],Jane,Smith,Test Inc

Required: email Optional: first_name, last_name, company_name, person_id, product_id

Common Use Cases

Use Case 1: Cold outreach to new leads

python3 email-outreach_agent.py \
  --segment "stage=new AND product_id=prod-labeling" \
  --template templates/cold_outreach.txt \
  --campaign-name "Q1 Cold Outreach - Labeling"

Use Case 2: Training reminder (manual list)

# Create CSV with participants
cat > participants.csv << 'EOF'
email,first_name
[email protected],John
[email protected],Jane
EOF

python3 email-outreach_agent.py \
  --recipients participants.csv \
  --template templates/training_reminder.txt

Use Case 3: AI-generated follow-up

python3 email-outreach_agent.py \
  --segment "stage=qualified" \
  --ai-mode \
  --subject "Following up on data labeling project"

Testing

# Run unit tests
cd $AGENTS_PATH/email-outreach
python3 test_email_outreach.py

# Dry-run test
python3 email-outreach_agent.py \
  --recipients test_data/test_recipients.csv \
  --template test_data/test_template.txt \
  --dry-run

Output

• Summary: google-tools/data/email_outreach_summaries/YYYY-MM-DD.md
• Log: google-tools/data/email_outreach_log.json
• Activities: sales/crm/activities.csv (appended)
• Drafts (on cancel): google-tools/data/email_outreach_drafts/

Integration with other skills

• Before: google-auth (if Gmail auth needed)
• After: Monitor responses via email-agent
• Future: change-review for CRM updates

Troubleshooting

Test send not arriving

# Check Gmail API
python3 -c "from google.oauth2.credentials import Credentials; print(Credentials.from_authorized_user_file('$GOOGLE_TOOLS_PATH/token.json'))"

# Re-auth if needed
# Run google-auth skill

Template placeholders not being filled

# Check CSV has the required columns
head -1 recipients.csv

# Placeholders case-sensitive: {name} not {Name}

Daily limit reached

# Check send log
cat $GOOGLE_TOOLS_PATH/data/email_send_log.json | jq '[.[] | select(.date == "2026-02-12")] | length'

# Wait until tomorrow or increase limit in config.json

Owner Decisions Applied

✅ Human approval required for ALL outreach ✅ Rate limit: 50/day max ✅ Logs to CRM activities ✅ Dry-run flag mandatory for testing ✅ Uses claude -p --model haiku (not API key) ✅ Idempotent (re-run safe)

Related Files

• Agent: $AGENTS_PATH/email-outreach/email-outreach_agent.py
• Config: $AGENTS_PATH/email-outreach/config.json
• Templates: $AGENTS_PATH/email-outreach/templates/
• Spec: $AGENTS_PATH/specs/email-outreach.spec.md

Related skills

• google-auth - Gmail API auth
• telegram-send - Parallel outreach channel
• add-lead - Add new contacts
• log-activity - Manual activity logging