# 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:
```bash
cargo build --release
```
## Configuration
Email account profiles are configured in `config.toml` at the project root:
```toml
[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
```bash
cargo run -- profiles
```
## Commands
### 1. Send Command
Send emails to individual or multiple recipients.
**Basic Usage:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```csv
email
user1@example.com
user2@example.com
user3@example.com
```
Or with recipient types:
```csv
email,type
user1@example.com,to
manager@example.com,cc
admin@example.com,bcc
```
**Examples:**
```bash
# 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:**
```bash
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.
```csv
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:**
```csv
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:
```html
<h1>Hello {{name}}!</h1>
<p>Thank you for attending {{event}} on {{date}}.</p>
<p>Your score: {{score}}</p>
```
**Examples:**
```bash
# 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](https://handlebarsjs.com/) syntax for variable substitution.
**Example Template:**
```html
<!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](https://support.google.com/accounts/answer/185833)
- 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.