outreach/README.md

# <20><> Outreach Engine

A professional Node.js email outreach system for automated campaigns to law firms with tracking, templates, and comprehensive testing.

## 🚀 Quick Start

### Prerequisites

- Node.js (v14+)
- Gmail account with App Password

### Setup

1. **Install dependencies:**

   ```bash
   npm install
   ```

2. **Configure environment:**

   ```bash
   cp env.development.example .env.development
   # Edit .env.development with your Gmail credentials
   ```

3. **Test configuration:**
   ```bash
   npm run test-config
   ```

## 📊 Data Management

### Where to Change Data

**Firm Data**: Edit `firm.json` - contains all law firm contacts organized by state:

```json
{
  "State": [
    {
      "firmName": "Example Law Firm",
      "location": "City",
      "website": "https://example.com",
      "contactEmail": "contact@example.com"
    }
  ]
}
```

**Email Templates**: Edit files in `templates/` directory:

- `outreach.html` - Main outreach template
- `campaign-1-saas.html` - SaaS campaign
- `campaign-2-data-service.html` - Data service campaign
- `campaign-3-license.html` - License campaign
- `campaign-4-gui.html` - GUI campaign
- `general-intro.html` - General introduction
- `employment-layer.html` - Employment law focus

## 🧪 Testing

### Test Mode (SAFE - Never sends to real firms)

```bash
# Test single email
npm run test-email

# Test all campaigns with different recipients
npm run test-campaigns

# Test with custom limit
EMAIL_TEST_LIMIT=5 npm start
```

### Test Configuration

- **Test Mode**: All emails go to `EMAIL_TEST_RECIPIENT` (never to actual firms)
- **Multi-recipient**: Use `EMAIL_TEST_RECIPIENTS` for campaign testing
- **Auto-generated**: System creates test firms if needed

## 🎯 Available Commands

### Core Operations

- `npm start` - Run with default settings
- `npm run start:dev` - Development mode
- `npm run start:prod` - Production mode

### Testing

- `npm test` - Run all tests
- `npm run test:watch` - Watch mode for development
- `npm run test:coverage` - Generate coverage report
- `npm run test-email` - Send single test email
- `npm run test-campaigns` - Test all campaigns

### Utilities

- `npm run migrate` - Migrate JSON data to database
- `npm run validate-json` - Validate firm.json syntax
- `npm run test-config` - Check environment configuration

## ⚙️ Key Configuration

### Environment Variables (`.env.development`)

```env
# Required
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

# Test Mode (SAFE)
EMAIL_TEST_MODE=true
EMAIL_TEST_RECIPIENT=your-test-email@gmail.com

# Rate Limiting
DELAY_MINUTES=5
MAX_EMAILS_PER_HOUR=15

# Tracking
TRACKING_ENABLED=true
TRACKING_PORT=3000

# Debug
DEBUG=true
LOG_LEVEL=debug
```

### Rate Limiting

- **Default**: 5 minutes between emails
- **Hourly limit**: 15 emails/hour
- **Pause**: Every 50 emails, pause 30 minutes

## 📈 Email Tracking

**Automatic tracking** when `TRACKING_ENABLED=true`:

- **Open tracking**: Invisible pixel tracks email opens
- **Click tracking**: All links wrapped with tracking URLs
- **Analytics**: Database stores all tracking events
- **Server**: Runs on port 3000 by default

## 🛠️ Development

### Project Structure

```
outreach-engine/
├── index.js              # Main application
├── config/               # Configuration management
├── lib/                  # Core libraries
├── templates/            # Email templates
├── tests/                # Test suite
├── scripts/              # Utility scripts
├── firm.json             # Firm data
└── logs/                 # Application logs
```

### Testing Framework

- **Jest**: Unit testing framework
- **Coverage**: Code coverage reporting
- **Test files**: `tests/lib/*.test.js`
- **Setup**: `tests/setup.js`

### Database

- **SQLite**: Local database for tracking and campaigns
- **Migration**: `npm run migrate` converts JSON to database
- **Tables**: `firms`, `email_sends`, `tracking_events`

## 🔒 Security Features

### Test Mode Protection

- ✅ **100% Safe**: Test mode NEVER sends to actual firms
- ✅ **Fail-safe**: Application stops if test recipient not configured
- ✅ **Clear logging**: Every email shows test mode status
- ✅ **Validation**: Double-check before sending

### Best Practices

- Always test first with your own email
- Use Gmail App Passwords (not regular passwords)
- Monitor your email account for warnings
- Respect rate limits and delays

## 🐛 Troubleshooting

### Common Issues

- **"Invalid login"**: Check Gmail App Password
- **"No emails sent"**: Verify `.env` configuration
- **"JSON error"**: Run `npm run validate-json`

### Debug Mode

```bash
DEBUG=true npm start
```

Shows detailed SMTP, template, and rate limiting information.

## 📋 Legal Compliance

- Compliant with CAN-SPAM Act
- Includes unsubscribe mechanisms
- Professional business contact information
- Respects opt-out requests

---

**Need more details?** See `PROJECT.md` for technical architecture and development information.