<EFBFBD><EFBFBD> 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:

   npm install
   

2. Configure environment:

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

3. Test configuration:

   npm run test-config
   

📊 Data Management

Where to Change Data

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

{
  "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)

# 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)

# 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

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.