AgentMail Campaigns

A CLI tool for managing email campaigns using AgentMail API.

Features

• Contact Management - Add, import (CSV), tag, and manage contacts
• Email Templates - Create reusable templates with Jinja2 variables ({{name}}, {{email}}, etc.)
• Campaign Orchestration - Create campaigns targeting contacts by tags
• Scheduling - Send immediately or schedule for later
• Analytics - Track sent, failed, and reply rates

Installation

# Clone the repo
git clone https://github.com/YOUR_USERNAME/agentmail-campaigns.git
cd agentmail-campaigns

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Edit .env and add your AgentMail API key

Quick Start

# Verify setup
python main.py setup

# Add contacts
python main.py contacts add "john@example.com" --name "John" --tags "leads"
python main.py contacts import contacts.csv --tags "imported"

# Create a template
python main.py templates create "welcome" \
  --subject "Hello {{name}}!" \
  --body "Hi {{name}}, welcome to our service!"

# Preview template
python main.py templates preview "welcome" --name "John"

# Create and send a campaign
python main.py campaigns create "Welcome Campaign" --template "welcome" --tags "leads"
python main.py campaigns send "Welcome Campaign"

# Check stats
python main.py stats

Commands

Contacts

python main.py contacts add <email> [--name NAME] [--tags "tag1,tag2"]
python main.py contacts list [--tags "tag"] [--all]
python main.py contacts import <csv_file> [--tags "tag"]
python main.py contacts remove <email>
python main.py contacts unsubscribe <email>

Templates

python main.py templates create <name> --subject "Subject" --body "Body text"
python main.py templates create <name> --subject "Subject" --file body.txt
python main.py templates list
python main.py templates preview <name> [--name "John"] [--email "john@example.com"]
python main.py templates delete <name>

Campaigns

python main.py campaigns create <name> --template <template_name> [--tags "tag1,tag2"]
python main.py campaigns list [--status draft|scheduled|sending|completed]
python main.py campaigns send <campaign_id_or_name>
python main.py campaigns schedule <campaign_id_or_name> --at "2024-02-01 09:00"
python main.py campaigns status <campaign_id_or_name>

Stats

python main.py stats

Template Variables

Templates use Jinja2 syntax. Available variables:

Variable	Description
{{name}}	Contact's name (or email prefix if no name)
{{email}}	Contact's email address
{{custom_field}}	Any custom field from contact

Project Structure

agentmail-campaigns/
├── main.py              # CLI entry point
├── config.py            # Configuration
├── requirements.txt     # Dependencies
├── .env.example         # Environment template
├── src/
│   ├── client.py        # AgentMail API wrapper
│   ├── contacts/        # Contact management
│   ├── templates/       # Email templates
│   ├── campaigns/       # Campaign orchestration
│   └── tracking/        # Analytics
└── data/                # Local storage (gitignored)

Requirements

• Python 3.10+
• AgentMail API key (get one here)

License

MIT