smartlead-api

Smartlead API Reference

Authentication

All requests use query parameter auth: ?api_key={SMARTLEAD_API_KEY}

Environment variable: $SMARTLEAD_API_KEY

Base URL: https://server.smartlead.ai/api/v1

Rate Limiting

• Standard plan: 2,000 req/min (33 req/sec)
• Higher plans: 3,000 req/min (50 req/sec)
• Retry on 429 and 5xx with exponential backoff
• For bulk operations, use p-limit or PQueue with 8-15 concurrency

CLI Quick Reference

The smartlead CLI (@smartlead/cli) wraps all API endpoints. Use it for quick lookups:

# Campaigns
smartlead campaigns list
smartlead campaigns get <id>
smartlead campaigns create --name "Campaign Name"

# Leads
smartlead leads list --campaign-id <id>
smartlead leads add --campaign-id <id> --file leads.csv

# Email accounts
smartlead email-accounts list
smartlead email-accounts get <id>

# Analytics
smartlead analytics campaign <id>
smartlead analytics overall

# Master inbox
smartlead inbox replies

API Endpoints

Campaigns

GET  /campaigns/{id}                    — Fetch campaign by ID
POST /campaigns/create                  — Create new campaign
POST /campaigns/{id}/status             — Update status (START, PAUSED, STOP)
     Body: { "status": "START" }

Campaign Email Accounts

GET    /campaigns/{id}/email-accounts   — List accounts assigned to campaign
POST   /campaigns/{id}/email-accounts   — Add accounts to campaign
       Body: { "email_account_ids": [1, 2, 3] }
DELETE /campaigns/{id}/email-accounts   — Remove accounts from campaign

Campaign Sequences

GET  /campaigns/{id}/sequences          — Fetch sequences
POST /campaigns/{id}/sequences          — Save/update sequences
     Body: { "sequences": [{ "seq_number": 1, "seq_delay_details": { "delay_in_days": 0 }, "subject": "...", "email_body": "..." }] }

A/B/C Variants — use seq_variants array inside each sequence:

{
  "sequences": [{
    "seq_number": 1,
    "seq_delay_details": { "delay_in_days": 0 },
    "seq_variants": [
      { "variant_label": "A", "subject": "Subject A", "email_body": "<div>Body A</div>" },
      { "variant_label": "B", "subject": "Subject B", "email_body": "<div>Body B</div>" },
      { "variant_label": "C", "subject": "Subject C", "email_body": "<div>Body C</div>" }
    ]
  }]
}

Note: Do NOT include distribution field — SmartLead splits evenly automatically.