# Hermithire Campaign Engine

Automated outreach campaign for hermit volunteer recruitment.
Sends beautiful HTML emails via Zoho Mail SMTP. Zero cost. No external APIs.

---

## Quick Start

### 1. Fix Zoho SMTP credentials

Open `.env` and update two things:

**a) Generate an App Password** (important — Zoho blocks plain passwords for SMTP):
- Log into Zoho Mail at mail.zoho.eu
- Settings → Security → App Passwords → Add
- Name: `HermithireSMTP`
- Copy the generated password into `.env` as `SMTP_PASSWORD`

**b) Find your sending address**:
- In Zoho: Settings → Accounts → look for your "From Address"
- This may be `contact@hermithire.com` (if custom domain is configured)
  or your default Zoho address
- Set this as both `SMTP_USERNAME` and `FROM_EMAIL` in `.env`

### 2. Send yourself a test email

```bash
cd /Users/archieshouse/hermithire-campaign
python3 test_send.py you@example.com 1   # test initial email
python3 test_send.py you@example.com 2   # test follow-up email
```

Check your inbox. Verify the images load and the HTML renders correctly.

### 3. Dry run (see what would be sent, send nothing)

```bash
python3 campaign.py send --touch 1 --dry-run
```

### 4. Send first batch — press & heritage contacts

```bash
# Send touch 1 to press contacts (most important segment first)
python3 campaign.py send --touch 1 --segment press

# Then heritage
python3 campaign.py send --touch 1 --segment heritage

# Then philosophy
python3 campaign.py send --touch 1 --segment philosophy
```

### 5. Check progress

```bash
python3 campaign.py status
```

### 6. Send follow-ups (7 days later)

```bash
# Sends touch 2 only to contacts who received touch 1 and haven't replied
python3 campaign.py send --touch 2
```

### 7. Mark a reply (stops follow-ups to that person)

```bash
python3 campaign.py replied editor@example.com --note "Interested — requested press kit"
```

---

## Adding More Contacts

### Interactive (one at a time):
```bash
python3 add_contacts.py
```

### Bulk import from CSV:
```bash
python3 add_contacts.py --file new_batch.csv
```
CSV must have columns: `name, first_name, email, organisation, segment, notes`

---

## Segments

| Segment | Audience |
|---------|----------|
| `press` | National and international journalists |
| `heritage` | Heritage/estate/garden publications |
| `history` | History publications and podcasts |
| `philosophy` | Philosophy and ideas publications |
| `lifestyle` | Luxury lifestyle magazines |
| `substack` | Newsletter and Substack creators |
| `influencer` | YouTube, TikTok, Instagram creators |
| `community` | Community managers (manual posting) |
| `local` | Local and regional press |
| `default` | Everything else |

---

## Zoho Free Tier Limits

- ~200 emails/day safe limit (free plan)
- Use `--limit 80` to stay well within limits
- `DELAY_SECONDS=8` means ~80 emails = ~11 minutes per run
- Run twice per day across two days to do 200 contacts

---

## File Structure

```
hermithire-campaign/
├── campaign.py           Main sending engine
├── test_send.py          Send test email to yourself
├── add_contacts.py       Add/import contacts
├── .env                  Your credentials (never commit this)
├── .env.example          Template for credentials
├── templates/
│   ├── email_1_initial.html    First outreach email
│   └── email_2_followup.html   Follow-up email (7 days later)
├── contacts/
│   └── master.csv        All contacts
└── tracking/
    ├── log.json          Sent/replied tracking
    └── campaign.log      Full activity log
```

---

## Tracking Log Format

`tracking/log.json` stores state per email address:

```json
{
  "editor@example.com": {
    "name": "Country Life Editorial",
    "segment": "heritage",
    "touch_1_sent": true,
    "touch_1_date": "2026-03-06",
    "touch_2_sent": false,
    "replied": false
  }
}
```

---

## Tips

- **Start with press**: they amplify to thousands of readers
- **Follow up exactly 7 days later**: the script enforces this automatically
- **Mark replies immediately**: `python3 campaign.py replied email@example.com`
- **Don't send community segment by email**: those are for manual Reddit/Facebook posts
- **Keep DELAY_SECONDS at 8+**: lower values risk Zoho rate limiting