AI Cold Outreach System

Complete cold email outreach system for AI agents. Handles lead generation via Apollo API, email enrichment, Saleshandy sequence creation, prospect import, warmup monitoring, and campaign management. Use when setting up cold outreach, finding decision-maker emails, building email sequences, or managing cold email campaigns. Includes proven email copy templates and deliverability best practices.

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:

bash

# 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:

bash

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:

bash

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

bash

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:

bash

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

Do NOT activate sequences until all accounts score 85+.

Architecture

text

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

Issue	Fix
Apollo search returns 0 emails	Emails require enrichment — search only returns IDs
Apollo people/search returns 403	Use /mixed_people/api_search endpoint instead
Saleshandy API "Invalid token"	Header must be x-api-key not api-key or Authorization
Saleshandy import fails "conflictAction"	Valid values: overwrite, noUpdate, addMissingFields
Emails going to spam	Check warmup scores, verify DKIM, reduce daily volume
Merge tags not rendering	Use {{First Name}} format in Saleshandy content