🚀 Automated Outreach Pipeline

Enterprise-grade B2B lead generation & cold outreach engine — fully automated, end-to-end.

Feed it a single company domain → Get personalized outreach emails delivered to verified decision-makers at lookalike companies. Zero manual steps.

Quick Start • Architecture • Pipeline Stages • Demo • Engineering • Roadmap

---

📌 Problem Statement

Traditional outbound prospecting is manual, fragmented, and time-intensive:

Manual Workflow	Time Spent
🔍 Researching lookalike companies	~45 min
👤 Finding decision-maker contacts	~60 min
📧 Resolving verified work emails	~30 min
✍️ Writing & sending personalized emails	~90 min
Total per campaign	~3–4 hours

This pipeline reduces it to a single command that executes in under 2 minutes.

---

🏛️ Architecture & Data Flow

                        ┌─────────────────────┐
                        │   🌐 Seed Domain     │
                        │   (e.g. wise.com)    │
                        └──────────┬──────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 1 — Company Discovery │
                    │  CUFinder API (Ocean)        │
                    │  Discovers lookalike domains  │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 2 — Prospect Finder   │
                    │  Prospeo Search Person API   │
                    │  Extracts C-Suite / VP / Dir  │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 3 — Email Enrichment  │
                    │  Prospeo Enrich Person API   │
                    │  Resolves verified work email │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  🛡️ SAFETY CHECKPOINT        │
                    │  CLI Approval Gate            │
                    │  Human confirms recipients    │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 4 — Email Delivery    │
                    │  Brevo Transactional SMTP    │
                    │  Jinja2 HTML template render  │
                    └─────────────────────────────┘

Each stage's output feeds directly into the next — no CSV exports, no copy-pasting, no intermediate tools required.

---

🗂️ Project Structure

Automated_outreach_platform/
│
├── 📄 main.py                        # CLI entrypoint & pipeline orchestrator
│
├── 📂 services/                      # Modular API integration layer
│   ├── ocean.py                      # Stage 1 — Lookalike company discovery (CUFinder)
│   ├── prospeo.py                    # Stage 2 — Decision-maker extraction (Prospeo)
│   ├── eazyreach.py                  # Stage 3 — Email verification & enrichment (Prospeo)
│   └── brevo.py                      # Stage 4 — Transactional email delivery (Brevo)
│
├── 📂 templates/                     # Email template assets
│   └── outreach_template.html        # Jinja2 HTML cold-outreach template
│
├── 📂 models/                        # Data model definitions
│   └── contact.py                    # Contact data structures
│
├── 📂 utils/                         # Shared utility functions
│   └── helpers.py                    # Helper utilities
│
├── 📂 screenshots/                   # Pipeline demonstration captures
│   ├── pipeline_output.jpg           # Pipeline execution (2-company run)
│   ├── pipeline_output_1.png         # Pipeline execution (5-company run)
│   ├── safety-checkpoints.png        # Safety gate — single contact
│   ├── safety-checkpoints-2.png      # Safety gate — multi-contact batch
│   ├── Brevo_analyst.jpeg            # Brevo real-time delivery dashboard
│   └── statistics.jpeg               # Brevo campaign statistics & metrics
│
├── 📄 requirements.txt               # Python dependencies
├── 📄 .env.example                   # python-dotenv environment template
└── 📄 .env                           # Local credentials (python-dotenv, git-ignored)

---

⚡ Engineering Highlights

What makes this implementation production-grade rather than a weekend script:

🎨 Decoupled HTML Templating (Jinja2)

Email copy lives in a standalone templates/outreach_template.html file — not hardcoded Python strings. Marketing can edit the template without touching business logic. Jinja2 handles personalization tokens ({{ first_name }}, {{ company_name }}, {{ title }}).

🖥️ Fully Configurable CLI (argparse)

Every pipeline parameter is tunable from the command line. Run quick 2-company test iterations to conserve API credits, or full 10-company campaigns:

python main.py wise.com -c 2 -m 1    # fast test: 2 companies, 1 contact each
python main.py wise.com -c 10 -m 5   # full campaign: 10 companies, 5 contacts each

🛡️ Human Safety Checkpoint

Before any email leaves the system, the pipeline pauses and displays a formatted summary table of every recipient (name, seniority, email). Requires explicit y confirmation — preventing accidental mass emails.

🔄 Graceful Error Recovery

Rate limits, timeouts, and API failures for individual companies are caught and logged — the pipeline skips the failing target and continues processing the rest. A single flaky API call never kills the entire campaign.

🔡 Cross-Platform Unicode Safety

Windows CMD/PowerShell terminals using CP1252/ASCII encoding crash on emoji output. This build dynamically reconfigures stdout to UTF-8 and wraps all output in a safe_print() fallback that strips non-BMP characters on legacy terminals.

🧹 Deduplication Engine

Tracks LinkedIn URLs and resolved emails across the entire run. If the same person appears from multiple company queries, they receive exactly one email — protecting sender domain reputation.

🧠 Smart Seniority Parsing

Parses Prospeo's nested job_history array to identify the current role's seniority. Filters out Analysts, Seniors, and Associates — only C-Suite, VPs, Directors, and Founders get through.

---

🔍 Pipeline Stages — Deep Dive

Stage 1 — Company Discovery (services/ocean.py)

Detail	Value
API	CUFinder /v2/fcl
Input	Seed company domain
Output	List of { name, domain } for lookalike companies
Error Handling	Timeout protection, non-JSON response fallback, self-domain exclusion

Stage 2 — Decision Maker Discovery (services/prospeo.py)

Detail	Value
API	Prospeo /search-person
Input	Company domains from Stage 1
Output	Decision-makers with { name, title, seniority, linkedin_url, company }
Filters	C-Suite, Vice President, Founder/Owner, Director
Smart Parsing	Extracts seniority from nested job_history[].current field

Stage 3 — Email Enrichment (services/eazyreach.py)

Detail	Value
API	Prospeo /enrich-person
Input	LinkedIn URLs / Person IDs from Stage 2
Output	Verified work email addresses
Safeguards	Only VERIFIED status emails pass through, rate-limit delay (1s), deduplication

Stage 4 — Email Delivery (services/brevo.py)

Detail	Value
API	Brevo /v3/smtp/email
Input	Enriched contacts from Stage 3
Output	Transactional emails with Brevo messageId tracking
Template	Jinja2-rendered HTML with personalization tokens
Fallback	Inline template if outreach_template.html is missing

---

📸 Demo & Screenshots

🖥️ Pipeline Execution — 2-Company Quick Run

Shows Stage 1 → 3 with 2 lookalike companies (Adyen, Airwallex) discovered for the seed domain wise.com:

---

🖥️ Pipeline Execution — Full 5-Company Run

Full campaign targeting 5 companies (Adyen, Airwallex, Google, Klarna, Monzo). Note Klarna hitting a rate limit — the pipeline gracefully skips it and continues:

---

🛡️ Safety Checkpoint — Single Contact

Interactive confirmation gate showing 1 queued recipient before email dispatch:

---

🛡️ Safety Checkpoint — Multi-Contact Batch

Batch confirmation for 6 verified decision-makers across multiple companies. All emails dispatched successfully with Brevo message IDs:

---

📊 Brevo Real-Time Analytics Dashboard

Live SMTP delivery dashboard showing 6 events, 6 delivered, 0 bounced — 100% deliverability:

---

📈 Campaign Statistics & Metrics

Brevo statistics panel showing 7 total emails sent with 100% delivery rate, 14.29% estimated open rate, 0% bounce rate:

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• API keys for: CUFinder, Prospeo, Brevo
• A verified sender domain on Brevo (e.g., caliver.me)

1. Clone the Repository

git clone https://github.com/Subodh26oct/Automated_outreach_platform.git
cd Automated_outreach_platform

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment (python-dotenv)

cp .env.example .env

Edit the .env file with your credentials (loaded automatically via python-dotenv):

CUFINDER_API_KEY=your_cufinder_api_key_here
PROSPEO_API_KEY=your_prospeo_api_key_here
BREVO_API_KEY=your_brevo_api_key_here
SENDER_EMAIL=name@domain.me
SENDER_NAME=Company Name

4. Run the Pipeline

# Quick test — 2 companies, 1 contact per company
python main.py wise.com -c 2 -m 1

# Full campaign — 5 companies, 3 contacts each
python main.py wise.com -c 5 -m 3

# View all CLI options
python main.py --help

---

🛠️ Technology Stack

Layer	Technology	Purpose
Language	Python 3.10+	Core runtime
CLI	argparse	Command-line interface & flag parsing
HTTP	requests	API communication layer
Templating	Jinja2	Decoupled HTML email rendering
Config	python-dotenv	Secure credential management via .env
Company Discovery	CUFinder API	Lookalike company extraction
Prospect Intelligence	Prospeo API	Decision-maker search + email enrichment
Email Delivery	Brevo SMTP API	Transactional email dispatch with tracking

---

🗺️ Future Roadmap

Features planned for upcoming iterations to evolve this into a full SaaS-grade outreach platform:

Priority	Feature	Description
🔴 P0	Multi-Sequence Campaigns	Automated follow-up sequences (Day 1 → Day 3 → Day 7) with smart stop-on-reply
🔴 P0	CRM Integration	HubSpot / Salesforce sync to auto-log outreach activities and update deal stages
🟠 P1	AI-Powered Personalization	LLM-generated email copy tailored per recipient using company news + LinkedIn activity
🟠 P1	A/B Testing Engine	Template variant testing with statistical significance tracking on open/reply rates
🟡 P2	Web Dashboard	React/Next.js dashboard for campaign management, analytics visualization, and team collaboration
🟡 P2	Webhook-Based Tracking	Real-time open/click/reply event processing via Brevo webhooks
🟢 P3	Multi-Channel Outreach	LinkedIn InMail + Twitter DM integration alongside email campaigns
🟢 P3	Domain Warm-Up Module	Automated sender reputation building for new domains to maximize inbox placement
🟢 P3	Rate Limit Intelligence	Adaptive request throttling per API provider with token bucket algorithm
🔵 P4	Team Collaboration	Multi-seat accounts with role-based access, campaign sharing, and audit logging
🔵 P4	CSV/Webhook Export	Pipeline output export to CSV, Google Sheets, or custom webhook endpoints

---

📐 Design Decisions & Trade-offs

Decision	Rationale
Prospeo for enrichment instead of Eazyreach	Prospeo already provides verified email resolution via /enrich-person, avoiding an additional API dependency while maintaining the same data quality
argparse over click	Zero additional dependencies — argparse ships with Python stdlib, keeping the install lightweight
Jinja2 templates over f-strings	Clean separation of concerns — email copy is editable by non-developers without touching Python code
Sequential email sending	Deliberate choice over async/parallel to respect Brevo rate limits and maintain predictable delivery ordering
1-second enrichment delay	Built-in rate-limit protection between Prospeo enrichment calls to prevent 429 errors

---

⚠️ Important Notes

• API Credits: CUFinder and Prospeo have free-tier usage limits. Use -c 2 -m 1 for testing to conserve credits.
• Sender Verification: Your SENDER_EMAIL domain must be verified in Brevo's dashboard before emails will deliver successfully.
• Compliance: This tool is for legitimate B2B outreach only. Ensure compliance with CAN-SPAM, GDPR, and local regulations.

---

👨‍💻 Author

Subodh AI & Software Engineer

---

_{Built with ☕ and Python — from seed domain to signed deal.}