Hi {{first_name}},
Your email body here.
", "variant_label": "A" } ] } ] ``` **Sequence Object Fields** `seq_number` · number · Required — Position of this step in the sequence (1-indexed). `seq_delay_details` · object · Required — Delay before this step sends. Use `delay_in_days` for the number of days to wait. `variant_distribution_type` · string · Required — How variants are distributed. Use `MANUALLY_EQUAL` for equal distribution. `variants` · array · Required — Array of email variants for A/B testing. **Variant Object Fields** `subject` · string · Required — Email subject line. Supports merge tags like `{{first_name}}`. `email_body` · string · Required — HTML email body. Supports merge tags. `variant_label` · string · Required — Label for this variant (e.g., `"A"`, `"B"`). ### Delete a Campaign in Smartlead via API Permanently removes a campaign from your account. ```javascript DELETE https://server.smartlead.ai/api/v1/campaigns/{campaign_id}?api_key=YOUR_API_KEY ``` > **Warning:** This action is irreversible. All campaign data including leads and analytics will be permanently deleted. ### List Email Accounts per Campaign in Smartlead via API Fetches all email accounts currently assigned to a campaign for sending. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/email-accounts?api_key=YOUR_API_KEY ``` Returns account details including SMTP/IMAP configuration, daily send limits, and authentication status. ### Add Email Account to Campaign in Smartlead via API Associates an email account with a campaign to use for sending. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/email-accounts?api_key=YOUR_API_KEY ``` **Request Body** ```json { "email_account_ids": [456, 457, 458] } ``` `email_account_ids` · number · Required — The ID of the email account to add to this campaign. ### Remove Email Account from Campaign in Smartlead via API Disassociates an email account from a campaign. ```javascript DELETE https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/email-accounts?api_key=YOUR_API_KEY ``` **Request Body** ```json { "email_account_ids": [ 456, 457, 458] } } ``` `email_account_ids` · number · Required — The ID of the email account to remove from this campaign. ### Fetch All Campaigns Using Lead ID in Smartlead via API Returns all campaigns that contain a specific lead. ```javascript GET https://server.smartlead.ai/api/v1/leads/{lead_id}/campaigns?api_key=YOUR_API_KEY ``` **Path Parameters** `lead_id` · number · Required — The unique ID of the lead. ## Email Account Endpoints ### Fetch All Email Accounts in Smartlead via API Lists all email accounts associated with your user account, with pagination support. ```javascript GET https://server.smartlead.ai/api/v1/email-accounts/?api_key=YOUR_API_KEY&offset=0&limit=10 ``` **Query Parameters** `api_key` · string · Required — Your API key. `offset` · number · Optional (default: `0`) — Pagination offset. `limit` · number · Optional (default: `100`, max: `100`) — Results per page. Returns account credentials, server settings, warmup details, and daily send counts. ### Create an Email Account in Smartlead via API Adds a new email account with SMTP/IMAP configuration. ```javascript POST https://server.smartlead.ai/api/v1/email-accounts/save?api_key=YOUR_API_KEY ``` **Request Body** ```json { "from_name": "John Smith", "from_email": "john@yourdomain.com", "username": "john@yourdomain.com", "password": "your_app_password", "smtp_host": "smtp.gmail.com", "smtp_port": 587, "smtp_port_type": "TLS", "imap_host": "imap.gmail.com", "imap_port": 993, "max_email_per_day": 50, "custom_tracking_url": null, "bcc": null, "signature": null } ``` **Request Body Parameters** `from_name` · string · Required — Display name shown to recipients. `from_email` · string · Required — The sending email address. `user_name` · string · Required — SMTP/IMAP login username (usually the email address). `password` · string · Required — SMTP/IMAP password or app password. `smtp_host` · string · Required — SMTP server hostname. `smtp_port` · number · Required — SMTP port (typically 587 for TLS, 465 for SSL). `smtp_port_type` · string · Required — Connection type: `TLS` or `SSL`. `imap_host` · string · Required — IMAP server hostname. `imap_port` · number · Required — IMAP port (typically 993). `max_email_per_day` · number · Optional — Daily send limit for this account. `custom_tracking_url` · string / null · Optional — Custom tracking domain for open and click tracking. `bcc` · string / null · Optional — BCC address to receive a copy of every sent email. `signature` · string / null · Optional — HTML email signature. ### Update an Email Account in Smartlead via API Modifies an existing email account's properties including daily limits, tracking URLs, and signatures. ```javascript POST https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}?api_key=YOUR_API_KEY ``` **Path Parameters** `email_account_id` · number · Required — The unique ID of the email account to update. Accepts the same fields as the Create endpoint. Include only the fields you want to update. ### Fetch Email Account by ID in Smartlead via API Retrieves complete details for a single email account. ```javascript GET https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}/?api_key=YOUR_API_KEY ``` **Path Parameters** `email_account_id` · number · Required — The unique ID of the email account. ### Configure Email Warmup in Smartlead via API Sets up or updates warmup settings for an email account, including daily volume and ramp-up strategy. ```javascript POST https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}/warmup?api_key=YOUR_API_KEY ``` **Path Parameters** `email_account_id` · number · Required — The unique ID of the email account. **Request Body** ```json { "warmup_enabled": true, "total_warmup_per_day": 20, "daily_rampup": 2, "reply_rate_percentage": 30 } ``` **Request Body Parameters** `warmup_enabled` · boolean · Required — Enable or disable warmup for this account. `total_warmup_per_day` · number · Required — Total warmup emails to send per day. `daily_rampup` · number · Required — Number of additional warmup emails to add each day (gradual ramp-up). `reply_rate_percentage` · number · Required — Percentage of warmup emails to reply to (improves sender reputation). ### Fetch Warmup Stats in Smartlead via API Returns the last 7 days of warmup statistics for an email account. ```javascript GET https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}/warmup-stats?api_key=YOUR_API_KEY ``` **Path Parameters** `email_account_id` · number · Required — The unique ID of the email account. Returns: sent count, spam placement count, and inbox placement count per day for the last 7 days. ## Lead Management Endpoints ### List All Leads by Campaign in Smartlead via API Fetches all leads in a campaign with full lead data and pagination. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads?api_key=YOUR_API_KEY&offset=0&limit=100 ``` **Query Parameters** `api_key` · string · Required — Your API key. `offset` · number · Optional (default: `0`) — Pagination offset. `limit` · number · Optional (default: `100`, max: `100`) — Results per page. Returns lead data including status, contact info, custom fields, and engagement metrics (open count, click count, reply count). ### Fetch Lead by Email Address in Smartlead via API Returns full lead data using the lead's email address as the identifier. ```javascript GET https://server.smartlead.ai/api/v1/leads/?api_key=YOUR_API_KEY&email=lead@example.com ``` **Query Parameters** `api_key` · string · Required — Your API key. `email` · string · Required — The email address of the lead to fetch. ### Fetch Lead Categories in Smartlead via API Retrieves all available lead categories for organization and segmentation. ```javascript GET https://server.smartlead.ai/api/v1/leads/fetch-categories?api_key=YOUR_API_KEY ``` ### Add Leads to a Campaign in Smartlead via API Bulk uploads leads to a campaign. Maximum **400 leads per request**. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads?api_key=YOUR_API_KEY ``` **Request Body** ```json { "lead_list": [ { "email": "john@example.com", "first_name": "John", "last_name": "Smith", "company_name": "Acme Corp", "phone_number": "+1234567890", "website": "https://acme.com", "location": "New York, USA", "linkedin_profile": "https://linkedin.com/in/johnsmith", "company_url": "https://acme.com", "custom_fields": { "job_title": "VP of Sales", "industry": "SaaS" } } ], "settings": { "ignore_global_block_list": false, "ignore_unsubscribe_list": false, "ignore_community_bounce_list": false, "ignore_duplicate_leads_in_other_campaign": false } } ``` **Lead Object Fields** `email` · string · Required — Lead's email address. `first_name` · string · Optional — Lead's first name. `last_name` · string · Optional — Lead's last name. `company_name` · string · Optional — Lead's company name. `phone_number` · string · Optional — Lead's phone number. `website` · string · Optional — Lead's personal or company website. `location` · string · Optional — Lead's location. `linkedin_profile` · string · Optional — Lead's LinkedIn profile URL. `company_url` · string · Optional — Lead's company website URL. `custom_fields` · object · Optional — Key-value pairs for any custom fields defined in your account. **Settings Parameters** `ignore_global_block_list` · boolean — When `true`, skips global block list check when importing this batch. `ignore_unsubscribe_list` · boolean — When `true`, skips unsubscribe list check. `ignore_community_bounce_list` · boolean — When `true`, skips community bounce list check. `ignore_duplicate_leads_in_other_campaign` · boolean — When `true`, allows importing leads that already exist in other campaigns. ### Update a Lead in Smartlead via API Modifies lead information including custom fields. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. `lead_id` · number · Required — The unique ID of the lead. Accepts the same fields as the lead object in the Add Leads endpoint. Include only the fields you want to update. ### Pause a Lead in Smartlead via API Pauses a lead's activity within a specific campaign — no further emails will be sent until the lead is resumed. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/pause?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. `lead_id` · number · Required — The unique ID of the lead. ### Resume a Lead in Smartlead via API Resumes a paused lead in a campaign with an optional delay before the next send. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/resume?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. `lead_id` · number · Required — The unique ID of the lead. ### Delete a Lead from Campaign in Smartlead via API Removes a lead from a specific campaign. The lead's data is deleted from that campaign only. ```javascript DELETE https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. `lead_id` · number · Required — The unique ID of the lead. ### Unsubscribe Lead from Campaign in Smartlead via API Unsubscribes a lead from a specific campaign only. The lead can still receive emails from other campaigns. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/unsubscribe?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. `lead_id` · number · Required — The unique ID of the lead. ### Unsubscribe Lead from All Campaigns in Smartlead via API Globally unsubscribes a lead from all campaigns and prevents them from being re-added to any future campaign. ```javascript POST https://server.smartlead.ai/api/v1/leads/{lead_id}/unsubscribe?api_key=YOUR_API_KEY ``` **Path Parameters** `lead_id` · number · Required — The unique ID of the lead to globally unsubscribe. ### Add Lead/Domain to Global Block List in Smartlead via API Adds an email address or entire domain to the global block list to prevent any future outreach. ```javascript POST https://server.smartlead.ai/api/v1/leads/add-domain-block-list?api_key=YOUR_API_KEY ``` **Request Body — Block a specific email address:** ```json { "email": "donotcontact@example.com" } ``` **Request Body — Block an entire domain:** ```json { "domain": "example.com" } ``` `email` · string · Conditionally Required — Email address to block. Use this OR `domain`, not both. `domain` · string · Conditionally Required — Domain to block (e.g., `"example.com"`). Blocks all email addresses at this domain. Use this OR `email`, not both. ### Fetch Lead Message History in Smartlead via API Returns the complete email conversation thread for a specific lead within a campaign. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/message-history?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. `lead_id` · number · Required — The unique ID of the lead. Returns: message types (`SENT` / `REPLY`), timestamps, subject lines, and full email bodies. ### Reply to Lead via Smartlead API Sends a reply directly into a lead's message thread from the master inbox. ```javascript POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/reply-email-thread?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. **Request Body** ```json { "lead_id": 789, "email_body": "Hi John, thanks for your reply...
", "reply_message_id": "msg_abc123", "reply_email_time": "2024-01-20T10:00:00.000Z" } ``` `lead_id` · number · Required — The ID of the lead to reply to. `email_body` · string · Required — HTML content of your reply. `reply_message_id` · string · Required — The message ID of the email you are replying to (maintains thread continuity). `reply_email_time` · string · Required — ISO 8601 timestamp for the reply. ### Export Campaign Leads to CSV in Smartlead via API Downloads a CSV file of all leads in a campaign with complete metrics. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads-export?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. **CSV columns included:** `id`, `campaign_lead_map_id`, `status`, `created_at`, `first_name`, `last_name`, `email`, `phone_number`, `company_name`, `website`, `location`, `custom_fields`, `linkedin_profile`, `company_url`, `is_unsubscribed`, `last_email_sequence_sent`, `is_interested`, `open_count`, `click_count`, `reply_count` ## Analytics Endpoints ### Fetch Campaign Statistics in Smartlead via API Returns detailed engagement metrics for a campaign with optional filtering by sequence number or email status. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/statistics?api_key=YOUR_API_KEY&offset=0&limit=100 ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. **Optional Query Parameters** `email_sequence_number` · number · Optional — Filter results by a specific sequence step number. `email_status` · string · Optional — Filter by engagement status. Values: `opened`, `clicked`, `replied`, `unsubscribed`, `bounced`. `offset` · number · Optional (default: `0`) — Pagination offset. `limit` · number · Optional (default: `100`) — Results per page. ### Analytics by Date Range in Smartlead via API Retrieves campaign analytics for a specific date range. Maximum span: **30 days**. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/analytics-by-date?api_key=YOUR_API_KEY&start_date=2024-01-01&end_date=2024-01-30 ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. **Query Parameters** `start_date` · string · Required — Start of date range in `YYYY-MM-DD` format. `end_date` · string · Required — End of date range in `YYYY-MM-DD` format. Maximum 30 days from start date. Returns: sent count, open count, click count, reply count, bounce count, and unsubscribe count per day within the range. ### Top-Level Campaign Analytics in Smartlead via API Provides aggregate performance metrics for a campaign in a single response. ```javascript GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/analytics?api_key=YOUR_API_KEY ``` **Path Parameters** `campaign_id` · number · Required — The unique ID of the campaign. Returns: sent / open / click / reply totals, lead status distribution, and client information. ### Global Analytics Overview in Smartlead via API Returns performance metrics across **all campaigns** — not just a single campaign. Use this for dashboard-level reporting and portfolio health tracking. ```javascript GET https://server.smartlead.ai/api/v1/analytics/overview?api_key=YOUR_API_KEY ``` Includes: aggregate sent / open / click / reply counts, response analysis with sentiment breakdown, lead category-wise response tracking, day-wise and month-wise performance metrics, email health by domain and individual account (with bounce rate), and provider comparison across Gmail, Outlook, and SMTP. ## Webhook Integration Smartlead supports webhook integration for real-time event notifications. Configure webhooks to push campaign and lead activity events to your CRM, Slack, or any HTTP endpoint the moment they occur. **Webhook Endpoints:** `POST /webhooks` — Create a new webhook `GET /webhooks` — List all webhooks `PUT /api/v1/webhook/update/:webhook_id` — Update a webhook `DELETE /webhooks/{webhook_id}` — Delete a webhook **Common webhook events:** - Email reply received - Email bounced - Lead unsubscribed - Campaign completed - Lead status changed ## Error Handling The Smartlead API uses standard HTTP response codes: `200` — Success. Request completed as expected. `400` — Bad Request. Check your request body or query parameters for errors. `401` — Unauthorized. Your API key is missing or invalid. `404` — Not Found. Verify the resource ID exists in your account. `422` — Validation Error. Check parameter types and ensure all required fields are present. `429` — Rate Limit Exceeded. You've exceeded 10 requests per 2 seconds. Implement exponential backoff and retry. `500` — Server Error. Retry after a short delay. Contact support if the error persists. `503` — Service Unavailable. Retry after a short delay. **Best practice:** On `429`, wait at least 2 seconds before retrying. Use exponential backoff for repeated failures. ## Frequently Asked Questions ### **What is the Smartlead API base URL?** The Smartlead API base URL is `https://server.smartlead.ai/api/v1`. All endpoints use this as the root, with your API key appended as a query parameter: `?api_key=YOUR_API_KEY`. ### **How do I authenticate with the Smartlead API?** Authentication is done via API key. Go to your Smartlead account settings, activate API access, and copy your key. Append it to every request as `?api_key=YOUR_KEY`. There is no OAuth — every request must include the key. ### **What are the Smartlead API rate limits?** Rate limits vary by subscription plan. Please contact customer support. ### **How do I add leads to a campaign using the Smartlead API?** Use `POST /api/v1/campaigns/{campaign_id}/leads` with your API key. You can upload up to 400 leads per request. The payload supports custom fields, duplicate detection, and block list handling. ### **Can I create and manage campaigns through the Smartlead API?** Yes. The Smartlead API supports full campaign lifecycle management: create, update schedule, update settings, add/remove email accounts, fetch sequences, save sequences, and delete campaigns — all via REST endpoints. ### **How do I configure email warmup via the Smartlead API?** Use `POST /api/v1/email-accounts/{email_account_id}/warmup` to configure warmup settings including daily send volume and ramp-up amount. Use `GET /warmup-stats` to monitor the last 7 days of warmup performance. ### **What analytics can I pull from the Smartlead API?** The API returns sent, open, click, reply, bounce, and unsubscribe counts. You can query by campaign ID, by date range (max 30-day span), or get top-level aggregate metrics. Lead status distribution is also included. ### **How do I unsubscribe a lead globally via the Smartlead API?** Use `POST /api/v1/leads/{lead_id}/unsubscribe` to globally unsubscribe a lead from all campaigns and prevent re-adding. For a single campaign, use the campaign-specific unsubscribe endpoint. ### **Does Smartlead support webhooks via the API?** Yes. Smartlead supports webhook integration for real-time event notifications. Use the `/webhooks` endpoints to create, list, update, and delete webhooks that fire on campaign and lead events. ### **What is the difference between Smartlead API v1 and the legacy version?** The current recommended version uses `/api/v1/...` endpoint paths. The legacy version (`/api/...`) is maintained for backward compatibility. All new integrations should use v1. ### **What campaign statuses are available in the Smartlead API?** Campaigns can have the following statuses: `ACTIVE`, `PAUSED`, `STOPPED`, `ARCHIVED`, and `DRAFTED`. New campaigns start as `DRAFTED`. ### **Can I filter campaigns by client in agency accounts?** Yes. Use the `client_id` query parameter on `GET /campaigns/` to filter results to a specific client. This is designed for agency and white-label accounts managing multiple clients. ### **What does** `enable_ai_esp_matching` **do?** When set to `true`, Smartlead's AI automatically matches each lead with the optimal sending email account based on the lead's email provider and historical deliverability data. This improves inbox placement rates. ### **What does** `send_as_plain_text` **do?** When `true`, Smartlead sends emails as plain text instead of HTML. This can improve deliverability with technical audiences and makes emails look more personal. ### **Can I export lead data via the Smartlead API?** Yes. Use `GET /campaigns/{campaign_id}/leads-export` to download a full CSV of all leads in a campaign including engagement metrics (opens, clicks, replies), custom fields, and subscription status. ## Related Resources - [Smartlead API Reference](https://api.smartlead.ai/introduction) - [Complete API Index](https://api.smartlead.ai/llms.txt) - [Quickstart Guide](https://api.smartlead.ai/quickstart) - [Authentication Setup](https://api.smartlead.ai/authentication) - [Campaign Setup Guide](https://api.smartlead.ai/guides/campaign-setup) - [Email Warmup Guide](https://api.smartlead.ai/guides/email-warmup) - [Lead Management Guide](https://api.smartlead.ai/guides/lead-management) - [Webhook Integration Guide](https://api.smartlead.ai/guides/webhook-integration) - [Error Handling Guide](https://api.smartlead.ai/guides/error-handling) - [Rate Limits Guide](https://api.smartlead.ai/guides/rate-limits) - [Best Practices Guide](https://api.smartlead.ai/guides/best-practices) _For support, contact support@smartlead.ai_