Send Batch Emails from CSV with the CLI

Send personalized emails to many recipients from a CSV or JSON file with the AhaSend CLI, with concurrent workers, retries and failure files.

This guide shows how to send batches of personalized email with the AhaSend CLI and check the results.

Before running the examples, log in with a full API key, use your verified sender domain, and replace YOUR_RESOURCE_ID with a resource UUID from your test account. Create any named template, recipient, attachment, or JSON files first. Shell examples use Bash; examples that read JSON with jq need jq installed. Sends use sandbox mode.

Overview

Batch processing allows you to:

• Send thousands of personalized emails
• Use concurrent workers for speed
• Track progress in real-time
• Automatically retry failures
• Generate performance metrics

Recipient File Formats

CSV Format

Create recipients.csv:

email,name,first_name,company,account_type
[e-mail],John Doe,John,ACME Corp,premium
[e-mail],Jane Smith,Jane,Tech Inc,basic
[e-mail],Alice Johnson,Alice,StartUp Ltd,enterprise

JSON Format

Create recipients.json:

[
  {
    "email": "[e-mail]",
    "name": "John Doe",
    "substitution_data": {
      "first_name": "John",
      "company": "ACME Corp",
      "account_type": "premium"
    }
  }
]

CSV uses email for the address and name for the display name. Other columns become template variables. JSON uses email, optional name, and substitution_data for per-recipient variables. The CLI converts these into the API’s substitutions field.

Save the template files named by a command before running it. Every send needs --from, --subject, a recipient source, and content.

Basic Batch Send

ahasend messages send --sandbox \
  --from [e-mail] \
  --recipients recipients.csv \
  --subject "Welcome to {{company}}" \
  --html-template welcome.html \
  --progress \
  --show-metrics

Performance Options

Concurrency Control

# Conservative (1 worker)
ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients users.csv \
  --html-template template.html \
  --max-concurrency 1

# High performance (5 workers; default is 1)
ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients users.csv \
  --html-template template.html \
  --max-concurrency 5

# Maximum throughput (10 workers)
ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients users.csv \
  --html-template template.html \
  --max-concurrency 10

The default --max-concurrency is 1; the allowed range is 1–10. More workers do not change your account API limits. Throughput depends on request latency and your sending limits.

Progress Tracking

ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients large-list.csv \
  --html-template newsletter.html \
  --max-concurrency 5 \
  --progress

Error Handling

Automatic Retries

ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients users.csv \
  --html-template template.html \
  --max-retries 3

Failed Recipients Recovery

Failed recipients are saved as JSON at ~/.ahasend/failed-YYYYMMDD-HHMMSS.json. Replace the filename below with the actual file from a failed run:

# If failures occur, retry with saved file
ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients ~/.ahasend/failed-YYYYMMDD-HHMMSS.json \
  --html-template campaign.html \
  --max-retries 5

Template Personalization

Global and Per-Recipient Data

global-data.json

{
  "company_name": "ACME Corp",
  "support_email": "[e-mail]"
}

ahasend messages send --sandbox \
  --from [e-mail] \
  --recipients users.csv \
  --subject "{{first_name}}, Welcome to {{company_name}}" \
  --html-template welcome.html \
  --global-substitutions global-data.json

Best Practices

1. Test with Small Batches First

# Test with first 10 recipients
head -11 recipients.csv > test-batch.csv

ahasend messages send --subject "Docs test" \
  --from [e-mail] \
  --recipients test-batch.csv \
  --html-template template.html \
  --sandbox

2. Use Idempotency Keys

ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients users.csv \
  --html-template template.html \
  --idempotency-key "campaign-$(date +%Y%m%d)"

3. Monitor Performance

# Send with detailed logging
ahasend messages send --sandbox --subject "Docs test" --from [e-mail] \
  --recipients users.csv \
  --html-template template.html \
  --verbose \
  --show-metrics \
  --output json

Troubleshooting

Slow Performance: Increase --max-concurrency up to 10 workers

High Failure Rate: Verify domains and check suppressions list

Memory Issues: Process large files in smaller chunks

Next Steps

• Learn about templates
• Set up webhook monitoring

Related Guides

• Install the CLI, CLI authentication, REST sending guide.
• SMTP settings, Node.js SDK, Go SDK.
• CLI configuration and output, API authentication, Permission scopes.
• Domain setup, Sandbox behavior, Tracking setup.
• Suppression durations.