Cold Outbound Dream Team

A multi-agent AI system for automated lead enrichment, audience expansion, and cold outbound campaign management.

What is This?

Imagine hiring a dream team of specialists to handle your cold outbound operations:

A Supervisor who analyzes your lead data and coordinates the team
A Lead Enrichment Expert who finds verified emails and contact info
An Audience Expansion Specialist who finds lookalike companies and people
An Email Campaign Specialist who manages your email sequences in Instantly
A LinkedIn Outbound Specialist who manages LinkedIn campaigns in HeyReach
A Research Analyst who gathers intelligence from company websites

This project brings that dream team to life using AI agents. Drop in a CSV of leads, and watch as the agents work together to enrich your data, expand your audience, and prepare it for outreach.

Architecture

graph TB
    subgraph "🎯 Input"
        CSV[CSV Lead List]
    end
    
    subgraph "🧠 Supervisor Layer"
        S[Supervisor Agent<br/>GPT-5.1<br/><i>Orchestrates the team</i>]
    end
    
    subgraph "👥 Specialist Agents"
        LM[LeadMagic Agent<br/>GPT-4o-mini<br/><i>Email finding & validation</i>]
        LA[Lookalike Agent<br/>GPT-4o-mini<br/><i>Audience expansion</i>]
        IA[Instantly Agent<br/>GPT-4o-mini<br/><i>Email campaigns</i>]
        HR[HeyReach Agent<br/>GPT-4o-mini<br/><i>LinkedIn campaigns</i>]
        FC[Firecrawl Agent<br/>GPT-4o-mini<br/><i>Web intelligence</i>]
    end
    
    subgraph "🔌 External APIs"
        LM_API[LeadMagic API<br/><i>Lead enrichment</i>]
        OC_API[Ocean.io API<br/><i>Lookalike discovery</i>]
        IA_API[Instantly API v2<br/><i>Email campaigns</i>]
        HR_API[HeyReach API<br/><i>LinkedIn outbound</i>]
        FC_API[Firecrawl API<br/><i>Web scraping</i>]
    end
    
    subgraph "📤 Output"
        OUTPUT[Enriched Leads +<br/>Expanded Audience +<br/>Email & LinkedIn Ready]
    end
    
    CSV --> S
    S --> |delegates| LM
    S --> |delegates| LA
    S --> |delegates| IA
    S --> |delegates| HR
    S --> |delegates| FC
    LM --> |calls| LM_API
    LA --> |calls| OC_API
    IA --> |calls| IA_API
    HR --> |calls| HR_API
    FC --> |calls| FC_API
    LM --> |reports| S
    LA --> |reports| S
    IA --> |reports| S
    HR --> |reports| S
    FC --> |reports| S
    S --> OUTPUT

Features

Lead Enrichment (via LeadMagic)

📧 Email Finder - Discover business emails from name + company
✅ Email Validation - Verify deliverability before sending
👤 LinkedIn Enrichment - Extract profile data from LinkedIn URLs
📱 Mobile Finder - Discover phone numbers
🏢 Company Search - Get company details from domain
🔄 Reverse Lookup - Find profiles from email addresses

Audience Expansion (via Ocean.io) 🆕

🔍 Lookalike Companies - Find companies similar to your best customers
👥 Lookalike People - Find decision makers matching your ICP
📈 List Expansion - Multiply your target list with quality lookalikes
🎯 Decision Maker Discovery - Find the right contacts at target companies

Email Campaign Management (via Instantly)

📊 Campaign Creation - Set up new email outreach campaigns
👥 Lead Import - Bulk import enriched leads
📈 Analytics - Monitor campaign performance
📬 Account Management - Manage sending accounts

LinkedIn Campaign Management (via HeyReach) 🆕

💼 LinkedIn Campaigns - Manage LinkedIn outbound sequences
🤝 Connection Requests - Automate connection requests
💬 LinkedIn Messaging - Send follow-up messages
📊 Campaign Analytics - Track acceptance and reply rates
👤 Account Management - Manage LinkedIn sender accounts

Web Intelligence (via Firecrawl)

🌐 Website Scraping - Extract content from company sites
🗺️ Site Mapping - Discover all pages on a domain
📋 Structured Extraction - Pull specific data points

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/cold-outbound-dream-team.git
cd cold-outbound-dream-team

2. Set Up Python Environment

# Create virtual environment (requires Python 3.10-3.13)
python3.12 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configure API Keys

# Copy the example environment file
cp .env.example .env

# Edit .env with your API keys

Required API Keys:

Service	Get Key From	Purpose
OpenAI	platform.openai.com/api-keys	Powers the AI agents
LeadMagic	app.leadmagic.io/settings/api	Lead enrichment
Ocean.io	app.ocean.io/settings/api	Lookalike discovery
Instantly	app.instantly.ai/app/settings/integrations	Email campaigns
HeyReach	app.heyreach.io → Settings → API	LinkedIn campaigns
Firecrawl	firecrawl.dev	Web scraping

4. Run Your First Analysis

# Analyze a CSV to see enrichment recommendations
python -m src.main analyze data/input/sample_leads.csv

Usage

Analyze a Lead List

See what enrichment your data needs:

python -m src.main analyze your_leads.csv

Output:

╭─────────────────────────────╮
│ Cold Outbound Dream Team    │
│ Analyzing your lead data... │
╰─────────────────────────────╯

       Data Summary       
┌──────────────────┬─────┐
│ Total Rows       │ 100 │
│ Missing Emails   │ 45  │
│ Has LinkedIn     │ Yes │
│ Has Website      │ Yes │
└──────────────────┴─────┘

Enrichment Recommendations:
  1. Use LeadMagic Email Finder for 45 missing emails
  2. Use LeadMagic Email Validation to verify existing emails
  3. Use Firecrawl to scrape company websites for context

Enrich Your Leads

Run the full enrichment workflow:

python -m src.main enrich your_leads.csv

Options:

--output, -o - Custom output path
--skip-email-finder - Skip finding missing emails
--skip-validation - Skip email validation
--skip-scraping - Skip website scraping

Expand Your Audience (NEW!)

Find lookalike companies and people:

# Find companies similar to your best customers
python -m src.main expand "stripe.com,shopify.com" --factor 20

# Also find decision makers
python -m src.main expand "stripe.com" --titles "CEO,VP Sales,CTO"

Options:

--factor, -f - How many lookalikes per seed (default: 10)
--find-people/--no-people - Also find decision makers
--titles, -t - Job titles to target

Create a Campaign

Enrich leads and create an Instantly campaign:

python -m src.main campaign your_leads.csv --name "Q1 Outreach"

Check Credits

Monitor your API credit balances:

python -m src.main credits

CSV Format

Your input CSV should contain lead data. The system automatically detects columns:

Column Type	Detected Keywords
Email	email, mail, e-mail
Name	name, first, last, contact
Company	company, organization, business
LinkedIn	linkedin, profile_url
Website	website, url, domain
Phone	phone, mobile, cell, tel

Example CSV:

first_name,last_name,company,website,linkedin_url,email
John,Smith,Acme Corp,https://acme.com,https://linkedin.com/in/johnsmith,
Sarah,Johnson,TechStart,https://techstart.io,,sarah@techstart.io

Project Structure

cold-outbound-dream-team/
├── src/
│   ├── main.py              # CLI entry point
│   ├── config.py            # Configuration management
│   ├── agents/              # AI agent definitions
│   │   ├── supervisor.py    # Orchestrator (GPT-4o)
│   │   ├── leadmagic_agent.py
│   │   ├── lookalike_agent.py
│   │   ├── instantly_agent.py
│   │   ├── heyreach_agent.py   # NEW! LinkedIn outbound
│   │   └── firecrawl_agent.py
│   ├── tools/               # API integrations
│   │   ├── leadmagic/       # LeadMagic API tools
│   │   ├── ocean/           # Ocean.io API tools
│   │   ├── instantly/       # Instantly API tools
│   │   ├── heyreach/        # HeyReach API tools (NEW!)
│   │   └── firecrawl/       # Firecrawl API tools
│   ├── crews/               # CrewAI orchestration
│   │   └── outbound_crew.py
│   └── utils/               # Helper functions
│       ├── csv_handler.py
│       └── validators.py
├── data/
│   ├── input/               # Drop CSVs here
│   └── output/              # Enriched results
├── diagrams/
│   └── architecture.svg     # System diagram
├── examples/
│   └── run_enrichment.py    # Example script
├── .env.example             # Environment template
├── requirements.txt
└── README.md

How It Works

Agent Roles

Supervisor Agent (GPT-5.1)

"I analyze your lead data, create enrichment strategies, and coordinate my specialist team to deliver the best results."

Examines CSV structure and data quality
Prioritizes enrichment tasks
Delegates to specialist agents
Aggregates results

LeadMagic Agent (GPT-4o-mini)

"I'm your lead enrichment expert. Give me a name and company, and I'll find their verified email, phone, LinkedIn, and more."

Finds missing email addresses
Validates email deliverability
Enriches LinkedIn profiles
Discovers mobile numbers

Lookalike Agent (GPT-4o-mini) 🆕

"I expand your audience by finding companies and people similar to your best customers. Give me your seed accounts, and I'll multiply your list."

Finds similar companies using Ocean.io
Identifies decision makers at target accounts
Expands lead lists with quality lookalikes
Matches your ideal customer profile

Instantly Agent (GPT-4o-mini)

"I manage your cold email campaigns. I'll create sequences, import leads, and monitor performance."

Creates email campaigns
Imports enriched leads
Monitors analytics
Manages sending accounts

HeyReach Agent (GPT-4o-mini) 🆕

"I manage your LinkedIn outbound campaigns. I'll add leads to LinkedIn sequences, send connection requests, and follow up with personalized messages."

Adds leads to LinkedIn campaigns
Manages connection requests
Sends LinkedIn messages
Monitors acceptance and reply rates
Manages LinkedIn sender accounts

Firecrawl Agent (GPT-4o-mini)

"I research companies online. I'll scrape their websites to find personalization opportunities for your outreach."

Scrapes company websites
Extracts structured data
Discovers site structure
Gathers intelligence for personalization

Workflow

1. CSV Upload → Supervisor analyzes data structure
2. Strategy → Supervisor creates enrichment plan
3. Expansion → Lookalike Agent finds similar companies (optional)
4. Enrichment → LeadMagic Agent finds/validates emails
5. Research → Firecrawl Agent gathers company context
6. Campaign → Instantly Agent creates campaign + imports leads
7. Output → Enriched CSV ready for outreach

Environment Variables

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes	-	OpenAI API key for LLM
`LEADMAGIC_API_KEY`	Yes	-	LeadMagic API key
`OCEAN_API_KEY`	Yes	-	Ocean.io API key
`INSTANTLY_API_KEY`	Yes	-	Instantly API key
`HEYREACH_API_KEY`	Yes	-	HeyReach API key
`FIRECRAWL_API_KEY`	Yes	-	Firecrawl API key
`SUPERVISOR_MODEL`	No	`gpt-5.1`	Model for supervisor
`AGENT_MODEL`	No	`gpt-4o-mini`	Model for specialists
`VERBOSE`	No	`false`	Enable verbose logging

API Credits

This system uses paid APIs. Estimated costs per operation:

Operation	Service	Credits/Call	Approximate Cost
Email Finder	LeadMagic	1	~$0.03
Email Validation	LeadMagic	1	~$0.01
Profile Search	LeadMagic	1	~$0.05
Mobile Finder	LeadMagic	1	~$0.10
Lookalike Companies	Ocean.io	1	~$0.02
Lookalike People	Ocean.io	1	~$0.03
Website Scrape	Firecrawl	1	~$0.01

💡 Tip: Use the analyze command first to estimate costs before running enrichment.

Contributing

Contributions welcome! Please read our contributing guidelines.

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Powered By

CrewAI - Multi-agent orchestration framework
LeadMagic - Lead enrichment API
Ocean.io - Lookalike audience discovery
Instantly - Cold email platform
HeyReach - LinkedIn automation platform
Firecrawl - Web scraping API
OpenAI - Large language models

License

MIT License - see LICENSE for details.

Built with ❤️ for the cold outbound community

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
data		data
diagrams		diagrams
examples		examples
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

bcharleson/cold-outbound-dream-team

Folders and files

Latest commit

History

Repository files navigation

Cold Outbound Dream Team

What is This?

Architecture

Features

Lead Enrichment (via LeadMagic)

Audience Expansion (via Ocean.io) 🆕

Email Campaign Management (via Instantly)

LinkedIn Campaign Management (via HeyReach) 🆕

Web Intelligence (via Firecrawl)

Quick Start

1. Clone the Repository

2. Set Up Python Environment

3. Configure API Keys

4. Run Your First Analysis

Usage

Analyze a Lead List

Enrich Your Leads

Expand Your Audience (NEW!)

Create a Campaign

Check Credits

CSV Format

Project Structure

How It Works

Agent Roles

Workflow

Environment Variables

API Credits

Contributing

Powered By

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 291

Uh oh!

Languages

Packages