SendEmail CLI Tool

A Rust CLI application for sending templated HTML emails via SMTP with support for batch processing, mail merge, and attachments.

Features

• Send: Send emails to individual or multiple recipients (TO/CC/BCC)
• Batch: Send the same email to a list of recipients from CSV with rate limiting
• Merge: Personalized mail merge using CSV data with per-recipient template variables
• Multi-Profile Support: Manage multiple email accounts via config file
• Template Engine: Handlebars for HTML template rendering
• Attachments: Support for multiple file types with automatic MIME detection
• Rate Limiting: Configurable batch size and delays to avoid SMTP limits
• Progress Tracking: Resume batch operations across sessions

Installation

1. Make sure you have Rust installed on your system
2. Clone the repository
3. Build the project:

cargo build --release

Configuration

Email account profiles are configured in config.toml at the project root:

[accounts.personal]
smtp_server = "smtp.gmail.com"
smtp_port = 587
sender_email = "your.email@gmail.com"
sender_name = "Your Name"
password = "your-app-password"

[accounts.work]
smtp_server = "smtp.office365.com"
smtp_port = 587
sender_email = "work@company.com"
sender_name = "Work Account"

Note: If password is omitted, you'll be prompted at runtime.

List Available Profiles

cargo run -- profiles

Commands

1. Send Command

Send emails to individual or multiple recipients.

Basic Usage:

cargo run -- send --profile <profile> --recipients <email> --subject "..." [OPTIONS]

Options:

• --profile <name> - Email account profile to use
• --recipients <emails>... - TO recipients
• --cc-recipients <emails>... - CC recipients
• --bcc-recipients <emails>... - BCC recipients
• --subject <text> - Email subject
• --body <text> - Plain text message (alternative to --template)
• --template <path> - Path to HTML template file
• --attachments <files>... - File attachments
• --data <json> - JSON data for template variables

Examples:

# Simple plain text email
cargo run -- send --profile personal \
  --recipients user@example.com \
  --subject "Test Email" \
  --body "Hello World"

# Email with HTML template and data
cargo run -- send --profile personal \
  --recipients user@example.com \
  --subject "Welcome!" \
  --template ./templates/register.html \
  --data '{"name":"John Doe","link":"https://example.com/activate"}'

# Email with attachments
cargo run -- send --profile work \
  --recipients user@example.com \
  --subject "Your Certificate" \
  --template ./templates/certificate.html \
  --attachments ./cert.pdf

# Multiple recipients with CC and BCC
cargo run -- send --profile work \
  --recipients user@example.com \
  --cc-recipients manager@example.com supervisor@example.com \
  --bcc-recipients admin@example.com \
  --subject "Update" \
  --body "System update notification"

2. Batch Command

Send the same email to a list of recipients from a CSV file with rate limiting.

Basic Usage:

cargo run -- batch --profile <profile> --recipients <csv_file> --subject "..." [OPTIONS]

Options:

• --profile <name> - Email account profile to use
• --recipients <csv_file> - Path to CSV file with recipient list
• --subject <text> - Email subject
• --body <text> - Plain text message (alternative to --template)
• --template <path> - Path to HTML template file
• --attachments <files>... - File attachments (same for all recipients)
• --batch-size <num> - Recipients per batch (default: 25)
• --delay-minutes <num> - Minutes to wait between batches (default: 5)
• --limit <num> - Daily email limit (default: 1000)

CSV Format:

email
user1@example.com
user2@example.com
user3@example.com

Or with recipient types:

email,type
user1@example.com,to
manager@example.com,cc
admin@example.com,bcc

Examples:

# Basic batch send
cargo run -- batch --profile work \
  --recipients emails/list.csv \
  --subject "Newsletter" \
  --template ./templates/newsletter.html

# Batch with attachments and custom settings
cargo run -- batch --profile work \
  --recipients emails/list.csv \
  --subject "Your Certificate" \
  --template ./templates/certificate.html \
  --attachments ./cert.pdf \
  --batch-size 50 \
  --delay-minutes 3 \
  --limit 500

# Test batch with limit
cargo run -- batch --profile personal \
  --recipients emails/test.csv \
  --subject "Test" \
  --template ./templates/test.html \
  --limit 5

Progress Tracking:

• Creates a .progress file to track progress
• Resumes from last position if interrupted
• Resets daily count at midnight
• Progress file location: <csv_file>.progress

3. Merge Command

Send personalized emails using CSV data with per-recipient template variables.

Basic Usage:

cargo run -- merge --profile <profile> --data <csv_file> --subject "..." --template <path> [OPTIONS]

Options:

• --profile <name> - Email account profile to use
• --data <csv_file> - Path to CSV file with recipient data
• --subject <text> - Email subject
• --template <path> - Path to HTML template file (required)
• --delay-seconds <num> - Seconds to wait between emails (default: 1)
• --limit <num> - Maximum emails to send (default: 1000)

CSV Format: The CSV must have an email column. All other columns become template variables.

email,name,event,date
user1@example.com,John Doe,AI Workshop,June 10 2025
user2@example.com,Jane Smith,AI Workshop,June 10 2025

Special Columns:

• email - Recipient email address (required)
• type - Recipient type: to, cc, or bcc (optional, default: to)
• attachment or attachments - File paths, semicolon-separated for multiple files (optional)

CSV with Attachments:

email,name,event,attachments
user1@example.com,John Doe,Workshop 1,cert1.pdf
user2@example.com,Jane Smith,Workshop 2,cert2.pdf;badge2.jpg
user3@example.com,Bob Johnson,Workshop 3,cert3.pdf;badge3.jpg;photo3.png

Template Variables: All CSV columns (except email, type, attachment, attachments) are available in templates:

<h1>Hello {{name}}!</h1>
<p>Thank you for attending {{event}} on {{date}}.</p>
<p>Your score: {{score}}</p>

Examples:

# Basic mail merge
cargo run -- merge --profile work \
  --data participants.csv \
  --subject "Your Certificate" \
  --template ./templates/certificate.html

# Mail merge with per-recipient attachments
cargo run -- merge --profile work \
  --data participants.csv \
  --subject "Your Certificate" \
  --template ./templates/certificate.html

# Mail merge with custom delay and limit
cargo run -- merge --profile personal \
  --data users.csv \
  --subject "Personal Update" \
  --template ./templates/update.html \
  --delay-seconds 2 \
  --limit 100

Template Engine

Templates use Handlebars syntax for variable substitution.

Example Template:

<!DOCTYPE html>
<html>
<head>
  <title>Welcome</title>
</head>
<body>
  <h1>Hello {{name}}!</h1>
  <p>Thank you for registering.</p>
  {{#if link}}
    <a href="{{link}}">Activate your account</a>
  {{/if}}
</body>
</html>

Variable Sources:

• Send command: Use --data '{"name":"value"}' JSON
• Merge command: CSV columns become template variables automatically

Security Notes

1. Password Security: Never commit config.toml with passwords to version control
2. Use App Passwords: For Gmail/Office365, use app-specific passwords
3. Rate Limiting: Respect SMTP provider limits to avoid account suspension
4. File Paths: Ensure attachment files exist and are accessible

Troubleshooting

Authentication Failed

• Verify email and password in config.toml
• For Gmail: Enable 2FA and use an App Password
• For Office365: May need to enable SMTP AUTH

Connection Issues

• Check internet connection
• Verify SMTP server and port settings
• Port 587 uses STARTTLS (most common)

Template Errors

• Ensure template file exists at specified path
• Check Handlebars syntax for variables: {{variable}}
• Verify JSON data matches template variables

Attachment Issues

• Verify file paths are correct (absolute or relative to working directory)
• Check file read permissions
• For merge command with multiple attachments, use semicolon separator: file1.pdf;file2.jpg

Progress File Issues

• Batch progress is stored in <csv_file>.progress
• Delete .progress file to start fresh
• Progress resets daily email count at midnight

Examples

See examples.sh for comprehensive command examples and CSV-FORMAT.md for detailed CSV format reference.

License

This project is provided as-is for educational and internal use.