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, 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

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)

Campaign Statuses

Campaign Details

Click on any campaign to view:

• 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

Export & Import

Campaigns can be exported as JSON files containing all data (recipients, send log, tracking). Import campaigns from JSON to restore or transfer between instances.

Available Filters

How to Import

1. Go to the Import tab and select Microsoft Graph API
2. Select the Graph App Permission inner tab
3. Enter an optional App Name to identify this app
4. Enter your Tenant ID, Client ID, and Client Secret from Azure AD
5. Add the user emails (one per line) that this app should send as
6. Click Import Accounts

Required Fields

How to Import

1. Go to the Import tab and select Microsoft Graph API
2. Select the Graph Delegated (Refresh Token) inner tab
3. Prepare a JSON file with your apps and accounts (see format below)
4. Click Import Tokens and select your JSON file

JSON Import Format

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

Each app can contain multiple accounts. The import page includes a step-by-step guide for generating refresh tokens.

Account Management

After importing, you can manage delegated accounts directly from this tab:

• Validate All: Check that all refresh tokens are still valid
• Filter & Search: Filter by status (active/inactive), sort by sent count, and search by email
• Bulk Actions: Select multiple accounts to activate, deactivate, or delete them
• Pagination: Choose how many accounts to display per page (10 to 5000)

Token Validation

Click Validate All to check every account's refresh token. The validation process shows:

• A progress bar with current/total count
• Valid (green) and invalid (red) counts
• Pause, resume, and stop controls

Supported Presets

Adding SMTP Accounts

• Single Add: Click "Add SMTP Account", select a preset or enter custom server details
• Bulk Import: Paste multiple accounts in email:password format (one per line)
• Each account needs: email, password, SMTP host, port, and encryption type (TLS/SSL)

Rotation Modes

Daily Limits

Each account has a configurable daily sending limit (1–10,000). When an account reaches its limit, it's automatically soft-banned for the day and rotation moves to the next available account.

Adding a Billing Account

1. Navigate to the Firebase section
2. Click Add Billing Account
3. Enter a Display Name to identify this account
4. Enter the Google account Email and Password
5. Optionally enter a TOTP Secret if the account uses two-factor authentication
6. Click Save

Required Fields

OAuth2 Connection

Connect a billing account to Google Cloud via OAuth2 for automated project and resource management:

1. Open the billing account and go to the OAuth section
2. Copy the Redirect URI shown below the OAuth fields — click the copy icon next to it to copy it to your clipboard, then add it as an authorized redirect URI in your Google Cloud OAuth credentials
3. Enter your Google Cloud OAuth2 Client ID and Client Secret
4. Click Save Credentials
5. Click Connect to start the Google authorization flow
6. Authorize access in the Google consent screen that opens
7. Once redirected back, a green status banner appears showing the authenticated Google email and confirming the OAuth2 connection is active

Managing Accounts

• Live 2FA Codes: If a TOTP secret is saved, the accounts table shows a live 6-digit code that refreshes every 30 seconds. A countdown bar indicates when the next code generates. Click the copy icon next to the code to copy it to your clipboard.
• Edit: Update display name, email, password, or TOTP secret at any time
• Connection Status: When connected, a green banner displays the authenticated Google email. If you experience permission errors, use the Reconnect link in the amber hint below the banner to re-authorize with all required scopes.
• Disconnect OAuth: Revoke the Google OAuth connection by clicking Disconnect on the green status banner. This clears the stored tokens and sets the account status back to disconnected. You can reconnect at any time by clicking Connect again.
• Delete: Removes the billing account and all associated Firebase projects and tenants
• Status: View connection status and the linked Google email

Prerequisites — API & OAuth Setup

Before connecting an account, complete these one-time steps in Google Cloud Console:

1. Enable the following APIs in your Google Cloud project:
   • Cloud Resource Manager API
   • Cloud Billing API
   • IAM API
2. Create an OAuth2 App at the Google Auth Overview page (choose External app type)
3. Set the callback URL to your app's Redirect URI (displayed in the Firebase tab under the OAuth fields — click the copy icon to copy it)
4. Publish the OAuth app: go to the OAuth Consent Screen and click Publish App to move it from Testing to Production
5. Copy the OAuth2 Client ID and Client Secret into the account detail view

Project Provisioning

Once your Google account is connected via OAuth, you can provision Firebase on your GCP projects:

1. Open a billing account and scroll to Setup Firebase on Projects
2. Click Fetch Projects to load your GCP projects from Google
3. Select the projects you want to provision using the checkboxes (or use Select All)
4. Click Provision Selected to start the automated setup

Each project goes through 8 automated steps:

Provisioning Progress & Error Hints

During provisioning, each step shows a live status indicator. If a step fails, an inline error message and actionable troubleshooting hints appear directly in the progress panel:

Steps that depend on a failed earlier step (e.g., steps 5–6 when step 4 fails) are shown as Skipped with a gray indicator instead of red, so you can focus on fixing the root cause.

Fix Service Account Permissions

If a provisioned project has permission issues, select it and click Fix SA Permissions to re-apply the required service account roles.

Creating Tenants

After provisioning, create Firebase Auth tenants on your projects:

1. Open the Create Tenants modal from the Firebase tab
2. Set the number of Tenants per project (default is 100, max 1000)
3. Filter projects by account or search by name
4. Select the projects you want to create tenants on
5. Click Create Tenants

Projects Table

The Delivery Management view shows all provisioned projects in a table with the following columns:

Bulk Actions

Select one or more projects using the checkboxes, then use the toolbar buttons:

Filtering & Pagination

• Use the Search box to filter projects by name
• Change the rows per page (10, 25, or 50) using the dropdown
• The project count is displayed next to the section heading

Managing Templates

• Save: Click "Save as Template" from the Single Email or Bulk Send tab
• Load: Click "Templates" button to open the Template Manager and load a saved template
• Edit: Modify template name, subject, and body from the Template Manager
• Preview: View rendered template before loading
• Create New: Build templates directly in the Template Manager
• Delete: Remove templates you no longer need

Supported Formats

Features

• Import from file upload or paste emails directly
• Automatic email validation and deduplication
• Preview list contents before using
• Load directly into Bulk Send recipients
• Rename and delete lists
• Filter lists by date range
• Export list emails

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 where they can select a reason
4. Unsubscribed emails are automatically skipped in future campaigns

Management Features

• View all unsubscribers with reason and campaign info
• Manually add or remove emails from the unsubscribe list
• Bulk import unsubscribers
• Export unsubscriber list
• Search and filter unsubscribers
• Stats: total unsubscribed, this week's count

Limits

How to Attach Files

• Drag and drop files onto the attachment zone in the Single Email or Bulk Send tab
• Or click the attachment zone to browse and select files
• Files are uploaded immediately and listed with name and size
• Click the X button on any file to remove it before sending

How It Works

• When your email template contains {{unsubscribe_url}}, the system automatically adds two headers to each outgoing email:

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

These headers are added for both Graph API and SMTP emails.

Why It Matters

• Gmail, Outlook, and Yahoo show a visible "Unsubscribe" button in the email header
• Improves sender reputation and reduces spam complaints
• Required by many email providers for bulk senders
• One-Click unsubscribe support (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

Export Formats

Settings Reference

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
4. Enter the API key for your chosen provider
5. Set the number of subject and body variations
6. Save settings

Configuration

Features

• 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
• Stats: Visual count of entries by log level