ai-cold-outreach（艾冷外展）

AI Cold Outreach System

End-to-end cold email outreach managed by your AI agent. From lead discovery to sending sequences — no human in the loop.

Prerequisites

• Apollo.io account with API key (Basic plan $59/mo for email enrichment)
• Saleshandy account with API key (Outreach plan)
• Google Workspace sending accounts (2+ domains recommended)
• SPF, DKIM, DMARC configured on sending domains

Quick Start

1. Configure API Keys

Store keys in your workspace:

# Apollo
export APOLLO_API_KEY="your_key"

# Saleshandy  
export SALESHANDY_API_KEY="your_key"

Or save to a JSON config (see references/config-template.json).

2. Find Leads

Use the Apollo lead generation script to search for decision-makers:

python3 scripts/apollo-search.py --titles "Owner,Founder,CEO" --keywords "aesthetic clinic" --location "United States" --max 100

This outputs a CSV with: name, email, title, organization, city, state, country.

3. Enrich Emails

Search results don't include emails. Enrich them:

python3 scripts/apollo-enrich.py --input leads-raw.csv --output leads-enriched.csv

Uses Apollo's people/match endpoint (1 credit per enrichment). Budget ~500 credits for 300 verified emails.

4. Import to Saleshandy

python3 scripts/saleshandy-import.py --csv leads-enriched.csv --step-id "YOUR_STEP_ID" --api-key "YOUR_KEY"

5. Monitor Warmup

Check email account health before sending:

python3 scripts/check-warmup.py --api-key "YOUR_KEY"

Do NOT activate sequences until all accounts score 85+.

Architecture

Apollo API (lead gen) → CSV → Saleshandy API (import) → Email Sequence → Prospects
                                    ↑
                          Email Copy Templates (references/)

Key API Endpoints

Apollo

• Search: POST /api/v1/mixed_people/api_search — find people by title, keyword, location
• Enrich: POST /api/v1/people/match — get email from person ID (1 credit each)
• Bulk Enrich: POST /api/v1/people/bulk_match — batch enrichment (use name+company, not IDs)

Saleshandy

• Base URL: https://open-api.saleshandy.com
• Auth Header: x-api-key: YOUR_KEY
• List Sequences: GET /v1/sequences
• Import Prospects: POST /v1/sequences/prospects/import-with-field-name
• List Email Accounts: POST /v1/email-accounts
• Add Account to Sequence: POST /v1/sequences/{id}/email-accounts/add

See references/api-reference.md for full endpoint documentation.

Email Copy Best Practices

See references/email-templates.md for proven templates.

Key rules:

1. Short punchy lines. One thought per line.
2. Story-driven. Every email tells a specific story with real results.
3. Real numbers always. Never round. "$457,500" not "almost half a million."
4. P.S. lines are punchlines. The best hook lives in the P.S.
5. Never beg. Confident, almost amused tone.
6. 3-step sequences minimum: Opener → Proof → Close
7. 3-5 day gaps between steps

Deliverability Checklist

Before activating any sequence:

• [ ] SPF record configured on sending domain
• [ ] DKIM record configured and passing
• [ ] DMARC record configured
• [ ] Email accounts warming for 7-14 days minimum
• [ ] Health scores above 85 on all accounts
• [ ] Using "get" prefix domains for cold outreach (protect main domain)
• [ ] Daily sending limits set conservatively (15-25/account/day to start)
• [ ] Warmup tool running (Saleshandy built-in or TrulyInbox)

Troubleshooting