--- name: smartlead-api description: Smartlead API endpoint reference and patterns. Use for any Smartlead campaign, lead, email account, analytics, or inbox operation. Covers auth, rate limiting, and all commonly used endpoints. user_invocable: false --- # 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: ```bash # Campaigns smartlead campaigns list smartlead campaigns get smartlead campaigns create --name "Campaign Name" # Leads smartlead leads list --campaign-id smartlead leads add --campaign-id --file leads.csv # Email accounts smartlead email-accounts list smartlead email-accounts get # Analytics smartlead analytics campaign 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: ```json { "sequences": [{ "seq_number": 1, "seq_delay_details": { "delay_in_days": 0 }, "seq_variants": [ { "variant_label": "A", "subject": "Subject A", "email_body": "
Body A
" }, { "variant_label": "B", "subject": "Subject B", "email_body": "
Body B
" }, { "variant_label": "C", "subject": "Subject C", "email_body": "
Body C
" } ] }] } ``` Note: Do NOT include `distribution` field — SmartLead splits evenly automatically. **Email body order:** content → PS unsub line → `%signature%` (signature always last) ### Campaign Settings & Schedule ``` POST /campaigns/{id}/settings — Update settings Body: { "track_settings": [...], "stop_lead_settings": "..." } POST /campaigns/{id}/schedule — Update schedule Body: { "timezone": "US/Eastern", "days_of_the_week": [1,2,3,4,5], "start_hour": "08:00", "end_hour": "17:00", "min_time_btw_emails": 8, "max_new_leads_per_day": 30 } ``` ### Leads ``` GET /leads/?api_key={key}&email={email} — Lookup lead by email address POST /campaigns/{id}/leads — Add leads to campaign (batch up to 100) Body: { "lead_list": [{ "email": "...", "first_name": "...", "last_name": "...", "company_name": "...", "custom_fields": { "field1": "value1" } }] } ``` ### Analytics ``` GET /analytics/day-wise-overall-stats ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD — Day-by-day metrics (sent, opened, clicked, replied, bounced) GET /analytics/day-wise-positive-reply-stats ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD — Day-by-day positive reply counts GET /analytics/overall-stats-v2 ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD — Overall campaign metrics for date range GET /analytics/campaign/list ?api_key={key} — List all campaigns with summary stats GET /campaigns/{id}/analytics ?api_key={key} — Analytics for specific campaign GET /campaigns/{id}/analytics-by-date ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD — Campaign analytics for specific date range (sent_count, reply_count) ``` ### Email Accounts (Global) ``` GET /email-accounts ?api_key={key}&offset=0&limit=100 — List all email accounts (paginated) GET /email-accounts/{id} ?api_key={key} — Get specific email account POST /email-accounts/save — Create/update email account (SMTP details, warmup, etc.) ``` ### Master Inbox ``` POST /master-inbox/inbox-replies Body: { "api_key": "...", "offset": 0, "limit": 50, "message_type": "RECEIVED" } — Fetch inbox replies with filtering and pagination ``` ## Sub-Client / Custom API Key Pattern - **Normal sub-clients:** Pass `?api_key={MAIN_KEY}&client_id={CLIENT_ID}` on all requests - **Custom API key clients:** Use the client's own API key directly, no `client_id` param ## TypeScript Pattern ```typescript const SMARTLEAD_API = "https://server.smartlead.ai/api/v1"; const API_KEY = process.env.SMARTLEAD_API_KEY; // GET example const res = await fetch(`${SMARTLEAD_API}/campaigns/${campaignId}?api_key=${API_KEY}`); const campaign = await res.json(); // POST example (add leads) const res = await fetch(`${SMARTLEAD_API}/campaigns/${campaignId}/leads?api_key=${API_KEY}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ lead_list: leads.slice(0, 100) }), }); ``` ## Performance tip: cache the email-accounts list If you hit `/email-accounts` more than a few times per script, paginate once at the start and keep the result in memory. Smartlead's pagination returns 100 per page — for accounts with thousands of inboxes, a full walk takes 30+ seconds. For persistent caching across scripts, write the list to a local JSON file and refresh on a timer (e.g. every hour). The `/smartlead-inbox-manager` skill has scripts that implement this pattern. --- ## What to do next This is a reference skill — no direct next step. Used by all skills that interact with Smartlead (`/smartlead-inbox-manager`, `/smartlead-campaign-upload-public`, `/email-deliverability-audit`, `/positive-reply-scoring`, `/deliverability-incident-response`, etc.). Return to the skill that sent you here. ## Related skills - Every skill that touches Smartlead uses this reference.