Choco Mailer Documentation

Choco Mailer supports two user roles with different access levels:

Fields

How to Send a Campaign

1. Enter a Campaign Name to identify this send (e.g., "Newsletter Jan 2026")
2. Add Recipients — paste emails one per line, upload a file (.txt, .csv, or .xlsx), or load from an Email List
3. Write your Subject and Message (supports rich text and HTML)
4. Optionally check "Validate accounts before sending" to verify all tokens first
5. Select a Tracking Domain if you want branded tracking links
6. Click Send Campaign

Adding Recipients

There are three ways to populate the recipients list:

• Paste manually — type or paste email addresses directly into the text area, one per line
• Upload File — click the Upload File button to import recipients from a .txt, .csv, or .xlsx file
• Email Lists — click the Email Lists button to load a previously saved list

Campaign Controls

Once a campaign starts, you get real-time controls:

Progress Tracking

The progress panel shows:

• Progress bar with sent/total count
• Success count (green)
• Failed count (red)
• Send rate (emails per minute)

Duplicate Handling

When duplicates are detected in your recipient list, a warning badge shows the count. You have two options:

• Remove Duplicates — click the button to automatically de-duplicate the list (recommended for most campaigns)
• Allow Duplicates — check the Allow duplicates checkbox to intentionally send to the same email address multiple times (useful when the same recipient needs multiple distinct notifications)

Random Sender Name

Override the default sender display name on each email with a randomly picked name from a list you provide. This helps vary the "From" name across a campaign for better deliverability.

1. Toggle Random Sender Name on (below the Tracking Domain selector)
2. Enter names in the text area — one name per line — or click Upload File to load a .txt or .csv file of names
3. The counter below the text area shows how many names are loaded
4. When the campaign sends, each email picks a random name from the list as its "From" display name

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

Adding SMTP Accounts

• Single Add: Click "Add SMTP Account", select a preset or enter custom server details
• Bulk Import: Click "Bulk Import" and choose one of two methods:

Each account needs: email, password, and SMTP host — host and port are auto-detected for known providers.

Bulk Import Formats

Use the | (pipe) delimiter for best results, especially if your password contains colons:

email@gmail.com|password
email@gmail.com|password|smtp.gmail.com|587
email@custom.com|my:complex:password|mail.custom.com|465
email@custom.com|pass|smtp.custom.com|587|John Doe
email@custom.com|pass|smtp.custom.com|587|John Doe|auth@provider.com

Triple-dash --- format for separate sender and authentication emails:

sender@domain.com---smtp.host.com:587----auth@provider.com----password
sender@domain.com---smtp.host.com:587----password

Slash-star /*/ format with explicit fields (sender, auth, password, host, port, encryption):

sender@domain.com/*/auth@provider.com/*/password/*/smtp.host.com/*/587/*/STARTTLS
sender@domain.com/*/auth@provider.com/*/password/*/smtp.host.com/*/465/*/SSL

Colon : delimiter is also supported for simple passwords:

email@gmail.com:password
email@gmail.com:password:smtp.gmail.com:587

Encryption Options

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

Supported Languages

How to Change Language

1. Look for the Language selector in the dashboard header or settings area
2. Click the dropdown and choose your preferred language
3. The interface updates immediately — no page reload required
4. Your language preference is saved and persists across sessions

Built-in Variables

Custom Variables

Create your own reusable variables to personalize emails beyond the built-in options. Custom variables can hold a fixed value or a list of random values.

Managing Custom Variables

1. Go to the Settings tab and scroll to the Custom Variables section
2. Click Add Variable to create a new one
3. Enter a name (e.g., sender_company) and a value
4. Choose the type: Static for a fixed value, or Random to pick a random line each time
5. Click Save to store the variable
6. Use it in your email subject or body as {{sender_company}}

You can also edit an existing variable by clicking the edit icon, or delete it with the trash icon.