Vello

Automation-First Email Outreach System

Enterprise-grade email outreach automation with intelligent campaign management

Features • Installation • Usage • Documentation • Contributing

---

🚀 Features

Vello is an automation-first email outreach engine designed to handle cold email campaigns programmatically. Built with modern Python best practices, it emphasizes intelligent automation and deliverability safety.

Core Capabilities

Feature	Description
🤖 Automated Decision-Making	Classifies responses, manages inboxes, adjusts sending patterns automatically
📊 Deliverability-Safe Sending	Warmup management, inbox rotation, intelligent pacing controls
🔄 Dynamic Campaign Logic	Multi-step campaigns with configurable timing and conditional flows
🧠 Smart Response Handling	Intent analysis, automatic unsubscription, response classification
📧 Multi-Provider Support	SMTP, SendGrid, and more (extensible architecture)
🎨 Template System	Jinja2-based email templates with HTML and text support

Key Highlights

✅ Production-Ready - Modular, extensible architecture following SOLID principles ✅ Type-Safe - Comprehensive type hints throughout the codebase ✅ Testable - Protocol-based design enables easy mocking and testing ✅ Scalable - Repository pattern and factory design for easy extension ✅ Maintainable - Clear separation of concerns and consistent patterns

---

🎯 Key Concepts

Automation-First Architecture

Vello is built around a set of configurable automation behaviors that control how the system:

• ✅ Classifies and reacts to email responses automatically
• ✅ Rotates between sending inboxes intelligently
• ✅ Generates plaintext versions of email bodies
• ✅ Adjusts sending times and pacing for optimal delivery
• ✅ Warms up inboxes gradually to maintain deliverability
• ✅ Cleans or maintains email lists automatically

This approach allows Vello to operate closer to a "programmatic SDR," reducing manual workload and making high-volume outreach safer and more consistent.

Extensible Campaign System

Campaigns consist of a sequence of steps, each with its own timing, subject, and template. Vello is designed to be extended into more advanced workflows, including:

• Conditional branching based on recipient behavior
• Nurturing paths for different lead segments
• Adaptive follow-up logic with machine learning integration

Transparent and Source-Available

The application is source-available for review, auditing, and contribution. Self-hosting for personal or internal use is permitted, while commercial hosting or resale is restricted by the Vello Source-Available License.

---

📁 Project Structure

This is a monorepo structure separating the Python backend and Next.js frontend:

vello/
├── backend/                    # Python backend
│   ├── .env                    # Environment variables
│   ├── requirements.txt        # Python dependencies
│   ├── setup.py                # Package installation config
│   ├── src/
│   │   └── vello/              # Main package
│   │       ├── core/           # Database, models, config
│   │       ├── services/       # Business logic
│   │       ├── utils/          # Utility functions
│   │       ├── email/          # Email sending providers
│   │       └── api/            # REST API endpoints
│   ├── examples/               # Usage examples
│   ├── templates/              # Email templates (Jinja2)
│   └── tests/                  # Test suite
│
└── frontend/                   # Next.js web GUI (planned)
    ├── src/
    │   ├── app/                # Next.js App Router
    │   ├── components/         # React components
    │   ├── lib/                # Utilities and API client
    │   └── types/              # TypeScript types
    └── public/                 # Static assets

---

🛠️ Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Quick Start

1. Clone the repository:

   git clone <your-repo-url>
   cd vello

2. Navigate to backend and install dependencies:

   cd backend
   pip install -r requirements.txt

3. Install the package in development mode:

   pip install -e .

4. Configure environment variables:

   cp .env.example .env
   # Edit .env with your configuration

5. Initialize the database:

   from vello.core.db import init_db
   init_db()

---

⚙️ Configuration

All configuration is managed through backend/.env.

Vello exposes both standard system settings (database, SMTP configuration, debug mode) and a set of automation flags that control intelligent behavior:

Setting	Description
AUTO_CLASSIFY_RESPONSES	Automatically classify replies (positive, neutral, negative)
AUTO_UNSUBSCRIBE_ON_REQUEST	Unsubscribe leads who request removal
AUTO_ROTATE_INBOXES	Rotate sender inboxes automatically
AUTO_ADJUST_SEND_TIMES	Adjust send times to recipient local time
AUTO_PAUSE_RISKY_CAMPAIGNS	Protect deliverability by pausing risky campaigns
WARMUP_ENABLED	Enable inbox warmup with safe volume increases

These automation controls allow Vello to function with minimal human intervention while maintaining safe sending practices.

Configuration Files

• backend/config/automation.json - Automation behavior flags
• backend/config/warmup.json - Inbox warmup settings
• backend/.env - Environment-specific settings (not committed)

---

💻 Usage

Running Example Scripts

From the backend directory:

# Test intent analysis
python examples/test_analysis.py

# Test template loading
python examples/example_template_usage.py

# Test email sending (requires .env configuration)
python examples/example_email_usage.py

# Test campaign usage
python examples/example_campaign_usage.py

Using the Package

from vello.core.db import init_db, get_db
from vello.core.models import Campaign, Recipient
from vello.services import analyze_intent
from vello.utils import get_template_loader
from vello.email import get_email_provider

# Initialize database
init_db()

# Analyze response intent
intent = analyze_intent("Yes, I'm interested!")
print(f"Intent: {intent}")  # ResponseStatus.POSITIVE

# Load and render email templates
loader = get_template_loader()
html, text = loader.render_email(
    "welcome_series/initial_outreach",
    {"name": "John", "company": "Acme Corp"}
)

# Send emails
provider = get_email_provider()
result = provider.send_email(
    to="user@example.com",
    subject="Hello from Vello",
    body_html=html,
    body_text=text
)

if result.success:
    print(f"Email sent! Message ID: {result.message_id}")
else:
    print(f"Error: {result.error}")

Campaign Management

from vello.services.campaign.manager import CampaignManager
from vello.core.db import get_db

# Get database session
db = next(get_db())

# Create campaign manager
manager = CampaignManager(db)

# Create a new campaign
campaign = manager.create_campaign(
    name="Q4 Outreach",
    description="Quarterly outreach campaign"
)

# Add campaign steps
step1 = manager.add_campaign_step(
    campaign_id=campaign.id,
    position=1,
    subject="Initial Outreach",
    template_path="welcome_series/initial_outreach",
    delay_days=0
)

step2 = manager.add_campaign_step(
    campaign_id=campaign.id,
    position=2,
    subject="Follow-up",
    template_path="follow_up/no_response",
    delay_days=3
)

---

📚 Documentation

For detailed documentation about the codebase architecture, design patterns, and development practices, see the WIKI.md.

Quick Links

• Architecture & Design Patterns
• Core Components
• Email Provider System
• Configuration System
• Database Models

---

🗺️ Roadmap

Current Status: MVP ✅

• ✅ Core email sending infrastructure
• ✅ Campaign management system
• ✅ Intent analysis and response classification
• ✅ Template system with Jinja2
• ✅ SMTP provider implementation
• ✅ Database models and migrations

Planned Features

• 🔄 Next.js Web Interface - Visual campaign management for non-technical users
• 🔄 Inbox Rotation Management - UI for managing multiple sending inboxes
• 🔄 Delivery Analytics - Comprehensive reporting and analytics dashboard
• 🔄 Additional Email Providers - Full support for SES, Mailgun, SendGrid
• 🔄 Template Versioning - A/B testing and template versioning
• 🔄 Advanced Campaign Logic - Conditional branching and nurturing paths
• 🔄 Webhooks & Events - Event relay system for integrations
• 🔄 Send-Time Optimization - ML-powered optimal send time prediction
• 🔄 Smart Lead Enrichment - Automatic lead data enrichment
• 🔄 Open-Core Model - Community extensibility and plugins

---

🤝 Contributing

We welcome contributions! Before contributing:

1. Review the License - Ensure your use case aligns with permitted usage
2. Check the Wiki - Familiarize yourself with the architecture and patterns
3. Follow Code Style - Use type hints, follow existing patterns
4. Write Tests - Add tests for new features
5. Update Documentation - Keep the wiki and README up to date

Contribution Guidelines

• Follow existing code patterns (protocols, factories, type hints)
• Export new functionality from __init__.py files
• Add examples to the examples/ directory
• Update configuration files when adding new settings
• Document design choices in the wiki

---

📄 License

Vello is released under the Vello Source-Available License, allowing:

• ✅ Personal and internal use
• ✅ Modification and contribution
• ✅ Self-hosting for personal or internal use

While prohibiting:

• ❌ Commercial resale
• ❌ Offering Vello as a hosted service

See the LICENSE file for full details.

---

💬 Support

For issues, questions, or feature requests:

• 📧 Open a GitHub Issue - Create an issue
• 📖 Check the Wiki - WIKI.md for detailed documentation
• 💡 Review Examples - Check backend/examples/ for usage patterns

---

🌟 Acknowledgments

Vello was originally developed by Mirako and is currently for private use by NovaLare. It is released as a source-available project to support transparency, community feedback, and future open-core development.

---

Built with ❤️ by the Vello Development Team

Automation-First Email Outreach • Production-Ready • Type-Safe • Extensible