Initial commit

2025-08-15 01:03:38 -08:00
commit 959e52287a
35 changed files with 11807 additions and 0 deletions
@@ -0,0 +1,215 @@
+# �� 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.