Choco Mailer Documentation

Choco Mailer supports two user roles with different access levels:

Fields

How to Send a Campaign

1. Enter a Campaign Name
2. Add Recipients — paste emails one per line, or load from an Email List
3. Write your Subject and Message
4. Optionally check "Validate accounts before sending"
5. Select a Tracking Domain if you want branded tracking links
6. Click Send Campaign

Campaign Controls

Campaign Statuses

Campaign Details

• Total, sent, failed counts and success rate
• Per-recipient delivery status with timestamps
• Email content preview (subject and body)
• Tracking report (opens, clicks, IPs)
• Option to resend failed emails

Filtering & Sorting

• Search by campaign name or UUID
• Filter by status, sort by newest/oldest/name/most recipients
• Export/import campaigns as JSON
• Paginated results for large campaign lists

Required Fields

JSON Import Format

{
  "apps": [{
    "app_name": "My Azure App",
    "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "client_secret": "your-client-secret",
    "accounts": [{ "email": "user@domain.com", "refresh_token": "0.AAAA..." }]
  }]
}

Account Management

• Validate All: Check that all refresh tokens are still valid
• Filter & Search: Filter by status, sort by sent count, search by email
• Bulk Actions: Activate, deactivate, or delete multiple accounts
• Pagination: 10 to 5000 accounts per page

Supported Presets

Required Fields

Bulk Actions

• Save: Click "Save as Template" from Single Email or Bulk Send
• Load: Click "Templates" to open the Template Manager
• Edit: Modify name, subject, and body from the Template Manager
• Preview: View rendered template before loading
• Delete: Remove templates you no longer need

Supported Formats

• Import from file upload or paste emails directly
• Automatic email validation and deduplication
• Load directly into Bulk Send recipients
• Rename, delete, filter by date range, and export lists

How It Works

1. Add {{unsubscribe_url}} to your email template footer
2. Each recipient gets a unique, token-based unsubscribe link
3. When clicked, recipients see an unsubscribe page to select a reason
4. Unsubscribed emails are automatically skipped in future campaigns

• View all unsubscribers with reason and campaign info
• Manually add or remove emails from the unsubscribe list
• Bulk import / export unsubscribers
• Search, filter, and view stats

When your template contains {{unsubscribe_url}}, two headers are automatically added:

List-Unsubscribe: <https://your-domain.com/api/unsubscribe/TOKEN>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• Gmail, Outlook, and Yahoo show a visible "Unsubscribe" button in the email header
• Improves sender reputation and reduces spam complaints
• One-Click unsubscribe (RFC 8058) is the modern standard

How Tracking Works

Tracking Metrics

Setup Steps

1. Go to Settings → Custom Tracking Domain
2. Enter your domain (e.g., track.yourdomain.com)
3. Click "Add" — the system generates a TXT DNS record for verification
4. Add the TXT record to your domain's DNS settings
5. Click "Verify" — the system checks the DNS record
6. Once verified, click "Activate" to start using the domain

Supported AI Providers

How It Works

• Subject Variations: AI generates 1–20 unique subject line variations from your original
• Body Variations: Local synonym-based spinning creates 1–10 body versions
• Each email in the campaign gets a randomly selected variation
• If AI fails, the system falls back to the local spinner

Setup

1. Go to Settings → AI Content Spinner
2. Enable the AI Spinner toggle
3. Select your preferred AI provider and enter the API key
4. Set the number of subject and body variations, then save

• Time Range: Quick filters for 30min, 1hr, 2hr, 6hr
• Log Level: Filter by DEBUG, INFO, WARNING, ERROR, CRITICAL
• Module: Filter by application module
• Search: Full-text search across log entries
• Auto-refresh: Toggle real-time log streaming
• Download: Export logs as a file

Log Retention

• Hot log: Current log file (up to 1MB)
• Daily rotation: Logs rotate daily with 7-day retention