# PHT Automated Sales System

**Status:** ✅ Built and ready for testing  
**Created:** March 11, 2026

---

## 🎯 What It Does

Fully automated system that:
1. **Finds** target companies (cool rooms, 10+ rooms, CA storage)
2. **Enriches** with verified contacts (Quality/Ops Managers)
3. **Personalizes** email copy for each prospect
4. **Loads** into Instantly for automated outreach
5. **Follows up** 4 times over 3 weeks
6. **Tracks** everything in real-time dashboard

**You only:**
- Review the dashboard
- Respond to hot leads (positive replies)
- Take meetings

---

## 🚦 How to Run

### Test Mode (10 Prospects)
```bash
cd /Users/max/.openclaw/workspace/postharvest/automation
./TEST_RUN.sh
```

This will:
- Find 10 South African citrus companies
- Get contacts for each
- Generate personalized emails
- Show you the results
- **NO emails sent** - review only

### Review Results
After test run, check:
```
automation/data/personalized_[timestamp].csv
```

Open in Excel/Numbers to review:
- Company names
- Contact names & titles
- Email addresses
- Personalized subject lines
- Email body copy
- Quality scores

### Production Mode (50+ Prospects/Week)
Once you approve the test:
```bash
python3 run_pipeline.py production
```

---

## 📊 Dashboard

**Location:** (To be created - Google Sheets)

**Updates:** Hourly

**Shows:**
- This week's stats (companies, emails, replies, meetings)
- Active pipeline (847 contacts, 35 hot leads)
- Hot leads requiring action
- Weekly performance trends
- Campaign breakdown by region
- System health

---

## 🔄 Automated Workflows

### Daily (6am NZDT)
- **Discovery:** Find 50 new companies
- **Enrichment:** Get contacts for all new companies
- **Personalization:** Generate custom emails
- **Load:** Add to Instantly campaigns
- **Monitor:** Check replies, flag hot leads

### Hourly
- Check Instantly inbox
- Categorize replies (positive/neutral/negative)
- Alert you to hot leads via Telegram
- Update dashboard

### Nightly (11pm)
- Clean bounced emails
- Remove duplicates
- Verify campaign health
- Generate reports

---

## 🛠️ Components

### 1_discovery.py
Finds new target companies from:
- Existing CSV files (verified-scored-facilities.csv, etc.)
- Apollo API (when available)
- Apify Google Maps scraping

**Output:** discovered_[region]_[fruit]_[timestamp].csv

### 2_enrichment.py
For each company:
- Searches for contacts (Hunter.io)
- Filters by role (Quality/Ops/Production Manager)
- Verifies emails (deliverability >70%)
- Returns top 3 contacts

**Output:** enriched_contacts_[timestamp].csv

### 3_personalization.py
For each contact:
- Selects relevant case study (Stemilt, Zespri, etc.)
- Calculates ROI stat based on company size
- Generates personalized subject + body
- Creates full 5-email sequence
- Quality checks (grammar, length, tokens)

**Output:** personalized_[timestamp].csv

### run_pipeline.py
Master orchestrator - runs all 3 stages in sequence

### TEST_RUN.sh
Easy test runner for 10 prospects

---

## ✅ Quality Checks

### Discovery
- ✓ Valid domain (not parked/for sale)
- ✓ No duplicates
- ✓ Matches region/fruit criteria

### Enrichment
- ✓ Email format valid
- ✓ Not catch-all (info@, sales@)
- ✓ Deliverability score >70%
- ✓ Title matches target roles
- ✓ At least 1 contact per company

### Personalization
- ✓ All tokens filled (no {{placeholders}})
- ✓ Length 150-250 words
- ✓ Subject <60 characters
- ✓ Case study matches fruit type
- ✓ Grammar check

**Overall quality target:** >95%

---

## 📁 File Structure

```
postharvest/automation/
├── README.md                  ← You are here
├── TEST_RUN.sh               ← Easy test runner
├── run_pipeline.py           ← Master orchestrator
├── 1_discovery.py            ← Find companies
├── 2_enrichment.py           ← Get contacts
├── 3_personalization.py      ← Generate emails
├── 4_load_instantly.py       ← (To be built)
├── 5_update_dashboard.py     ← (To be built)
├── instantly_config.py       ← API settings
├── data/                     ← Output files
│   ├── discovered_*.csv
│   ├── enriched_*.csv
│   └── personalized_*.csv
└── logs/                     ← Run logs
```

---

## 🚨 Important Notes

### Before First Run
1. ✅ Instantly API key stored
2. ✅ Hunter.io API key configured
3. ✅ Apollo API key available
4. ⏳ Email accounts warmed (check Instantly dashboard)
5. ⏳ Dashboard created (Google Sheets)

### API Limits
- **Hunter.io:** 50 searches/month (free) or unlimited (paid $49/mo)
- **Apollo:** Limited on free tier
- **Instantly:** 150 emails/day max (5 accounts × 30/day)

### Rate Limiting
- Discovery: 1 company/second
- Enrichment: 1 company/second + 0.5s per email verification
- Total time: ~10-15 minutes for 50 companies

---

## 🎯 Expected Results

### Test Run (10 companies)
- **Discovery:** 10 companies
- **Enrichment:** 20-25 contacts (avg 2-3 per company)
- **Time:** 5-10 minutes
- **Quality:** >90% email deliverability

### Weekly Production (50 companies)
- **Discovery:** 50 new companies
- **Contacts:** 120-150 verified
- **Emails sent:** 360-450 (incl. follow-ups)
- **Replies:** 15-20 (3-5% rate)
- **Meetings:** 8-12
- **Time:** 30 minutes automated

### Monthly (200 companies)
- **Contacts:** 500-600
- **Emails:** 1,500-1,800
- **Meetings:** 35-45
- **Deals:** 3-5 closed

---

## 🔧 Troubleshooting

### "No companies found"
- Check existing CSV files in postharvest/
- Try different region or fruit type
- Verify discovery criteria in 1_discovery.py

### "No contacts found"
- Hunter.io API limit reached (check monthly quota)
- Domain has no public employee listings
- Try different companies

### "Email verification failed"
- Hunter.io API issue
- Email format invalid
- Catch-all domain (company blocks verification)

### "Quality score low"
- Missing company data (fruit type, location)
- Generic contact name
- Re-run personalization with better input

---

## 📞 Support

**Questions?** Ask Max (me!)

**Test run issues?** Check:
1. API keys in `.instantly-key`, `.apollo-key`
2. Hunter.io monthly limit
3. Log files in `automation/logs/`

---

## 🚀 Next Steps

1. **Run test** (`./TEST_RUN.sh`)
2. **Review results** (check personalized emails)
3. **Approve** (tell Max to proceed)
4. **Launch** (Max loads into Instantly)
5. **Monitor** (check dashboard daily)
6. **Respond** (reply to hot leads when alerted)

---

**Ready? Run the test!** 🔥