216 lines
5.1 KiB
Markdown
216 lines
5.1 KiB
Markdown
# �� 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.
|