# The Cold Email Machine — n8n Workflow Kit
# Setup & Installation Guide

## What's Included

### Workflows
1. **cold-email-sender.json** — Core cold email sending workflow with throttling
2. **lead-enrichment.json** — Takes a list of leads, enriches with name, company, title
3. **follow-up-sequence.json** — 3-touch follow-up sequence (day 1, day 3, day 7)
4. **email-warmup.json** — Gradual warmup routine for new sending accounts
5. **full-outreach-pipeline.json** — End-to-end: scrape → enrich → personalise → send → follow up

### Docs
- SETUP-GUIDE.md — This file
- SMTP-SETUP.md — How to configure Gmail, SMTP2GO, Mailgun
- DELIVERABILITY.md — Inbox placement best practices
- WARMUP-PROTOCOL.md — 30-day warmup schedule

---

## Quick Start

### Step 1: Install n8n
```bash
# On your VPS
npm install -g n8n
n8n start

# Or with Docker
docker run -d --name n8n -p 5678:5678 n8nio/n8n
```

### Step 2: Import a Workflow
1. Open n8n at http://your-server:5678
2. Click "Workflows" → "Import from JSON"
3. Paste the contents of any workflow .json file
4. Click "Save"

### Step 3: Configure Your SMTP
Each workflow uses a "SMTP" credential. To set up:
1. Click "Credentials" in n8n
2. Add "Email Send (SMTP)" credential
3. Fill in your SMTP details:
   - Host: smtp.example.com
   - Port: 587
   - User: your@email.com
   - Password: your SMTP password
   - From: Your Name <your@email.com>

### Recommended SMTP Providers
- **SMTP2GO** — Best for cold email, starts at $10/mo for 50k emails
- **Mailgun** — Good deliverability, 5k free/month
- **Amazon SES** — Cheapest option, $0.10/1000 emails
- **Google Workspace** — Works for low volume, 500/day limit

---

## Workflow Descriptions

### 1. Cold Email Sender
**Best for:** Sending personalised cold emails to a list

Input: Google Sheet or CSV of leads
- First name, last name, email, company, custom fields
- Personalisation tokens: {{firstName}}, {{company}}, {{jobTitle}}, {{customField}}

Process:
- Reads your lead list
- Substitutes personalisation tokens
- Adds tracking pixel (optional)
- Sends via your SMTP with throttling (30-60 sec between emails)
- Logs result to Google Sheet

Output: Sent emails logged, bounces flagged

---

### 2. Lead Enrichment
**Best for:** Adding missing data to cold leads

Input: List of companies or domains
- company name or website domain

Process:
- Calls Clearbit API (free tier: 50 req/day)
- Or calls LinkedIn scrape (requires PhantomBuster)
- Extracts: employee count, funding, revenue, industry, tech stack

Output: Enriched CSV with additional columns

---

### 3. Follow-Up Sequence
**Best for:** Automating reply/no-reply follow-ups

Input: Triggered by cold email workflow output
- Who you emailed, when, their reply status

Process:
- Waits 3 days after first email
- Checks if replied (manual flag in sheet)
- If no reply: sends follow-up #1
- Waits 4 more days
- If still no reply: sends follow-up #2
- Waits 7 more days
- If still no reply: sends final "breakup" email

Output: Full sequence tracked per lead

---

### 4. Email Warmup
**Best for:** Warming up a new sending domain or email

Input: List of warmup partner emails (real contacts who'll engage)

Process:
- Day 1-7: Send 5 warmup emails/day, get 2-3 replies
- Day 8-14: Send 10 warmup emails/day
- Day 15-21: Send 20 warmup emails/day
- Day 22-30: Send 30 warmup emails/day

Each warmup email:
- Gets a reply from your partner
- Marks as important
- Moves to inbox

Output: Warmup score increases, deliverability improves

---

### 5. Full Outreach Pipeline
**Best for:** Complete end-to-end cold outreach

Input: Target company list or LinkedIn search URL

Process:
1. Scrapes LinkedIn for target companies/people
2. Enriches with Clearbit (company data)
3. Personalises email based on company news/triggers
4. Sends first email via SMTP
5. Waits for reply window
6. Fires follow-up sequence if no reply
7. Moves responders to "replied" list
8. All activity logged to Google Sheet

Output: Full pipeline with status per lead

---

## Personalisation Tokens

All workflows support these tokens:
```
{{firstName}}      → John's
{{lastName}}       → Smith's
{{company}}        → Acme Corp
{{jobTitle}}      → Marketing Manager
{{domain}}        → acmecorp.com
{{linkedinUrl}}   → linkedin.com/in/johnsmith
{{customField}}    → any column from your sheet
```

---

## Tips for Inbox Placement

1. **Start slow** — 20-30 emails/day first week
2. **Warm up first** — Run warmup workflow for 2-3 weeks
3. **Use proper SPF/DKIM** — Set up email authentication
4. **Monitor bounces** — Remove bounced emails immediately
5. **Reply to all** — Encourage warmup partners to reply
6. **Don't send on weekends** — Monday-Thursday is best
7. **Personalise** — Generic emails go to spam

---

## Troubleshooting

**Emails going to spam:**
- Run warmup longer
- Check your SPF/DKIM setup
- Reduce volume
- Improve email content quality

**Bounces high:**
- Your list quality is low — buy fresh data
- Remove hard bounces immediately
- Don't email unsubscribe addresses

**Account suspended:**
- You sent too fast or got too many complaints
- Contact your SMTP provider
- Reduce volume by 80%

---

Questions? Email support@coldstack.tech
