Smartlead API Guide: Build a Safe Outbound Workflow
Summarize with AI
The Smartlead API can run campaigns, mailbox connections, lead state, replies, webhooks, and suppression, but it should not be treated as a fire-and-forget sending pipe. Our recommendation is to use the Smartlead API only behind a controlled workflow that creates a draft, tests with owned addresses, reconciles every uncertain write, and keeps suppression outside Smartlead too. If your system cannot deduplicate webhook events, preserve suppression, or recover an uncertain lead write, keep the integration in a test campaign.
What the Smartlead API is good for
The API is useful when Smartlead is one part of a larger outbound system rather than the only place where state lives. Its documented surfaces cover campaign creation and settings, lead changes, SMTP or OAuth mailbox setup, message history, Master Inbox replies, webhooks, unsubscribe actions, and block-list utilities. Smartlead documents these as separate operations. (campaign creation, lead import, SMTP mailbox setup, Master Inbox replies, webhook creation, unsubscribe endpoint)
Smartlead should own sending execution, while your CRM or controlled database owns contact identity, suppression intent, and the record of what should happen next. That split matters because the public documentation does not describe a general idempotency identifier for campaign, lead, mailbox, or reply mutations. After a timeout, the safe action is to read and reconcile before writing again, not to assume the first request failed.
| Surface | Useful operation | Control your system must own |
|---|---|---|
| Campaigns | Create, configure, test, start, pause | Release approval and status read-back |
| Leads | Add, update, pause, resume | Normalized identity and duplicate reconciliation |
| Mailboxes | Connect SMTP/IMAP or ingest OAuth tokens | Secret handling and provider authorization |
| Replies | Read history, send a thread reply, check status | Intent log and Message-ID reconciliation |
| Webhooks | Receive campaign and message events | Authentication, durable queue, deduplication |
| Suppression | Unsubscribe and block emails or domains | Durable policy, scope, and legal decision |
The controls in the final column are our design recommendation. They are not Smartlead guarantees.
Authenticate without leaking the API credential
Smartlead documents https://server.smartlead.ai/api/v1 as the base URL. Its current help article says API access is available on Pro and higher plans, requires owner or admin access, and uses an API credential created under Settings, API Key Management. The same article says the credential must be supplied in the URL and is not accepted in a request header. (Smartlead authentication, Smartlead API getting-started guide)
A minimal request therefore has this shape:
The API authentication page says POST and PATCH requests can also put the credential in the body, while the newer help article says the credential must be in the URL. Do not guess between them. Use the consistently supported query parameter, redact query strings in application logs and monitoring, and test credential rotation in the target account. (Smartlead authentication, Smartlead API getting-started guide)
Create a separate credential for each integration where your account model allows it. Smartlead's help article says an account can create up to 25 admin API credentials, which makes rotation and integration-level revocation more practical than sharing one credential across every workflow. (Smartlead API getting-started guide)
Build a Smartlead campaign without accidental sending
POST /campaigns/create accepts a campaign name and an optional client_id. Smartlead says the result includes the campaign ID and begins in DRAFTED status. Sequences, settings, mailboxes, leads, and the sending state are configured through other routes. (create campaign, campaign overview)
Use this release order:
- Create a timestamped draft and store its returned ID.
- Add the sequence and campaign settings.
- Attach one controlled mailbox.
- Add only owned synthetic addresses.
- Send a test message for rendering and sender verification.
- Obtain an explicit release approval.
- Send the start command and read the campaign status back.
The settings endpoint covers controls such as tracking, stop conditions, unsubscribe text, plain-text mode, out-of-office handling, bounce controls, and domain auto-pause behavior. The test-email endpoint requires leadId and sequenceNumber and can send to a customEmailAddress. (campaign settings, send test email)
Campaign status is another unresolved documentation conflict. The creation page says DRAFTED, while the campaign overview says DRAFT. The update-status parameter table tells callers to send START, but code examples on the same page send ACTIVE, and successful responses show ACTIVE. Send START because it is the explicit request value, then read the state back and require ACTIVE before treating the campaign as live. Test that transition in your account before automating it. Smartlead also describes STOPPED as permanent, so use PAUSED when you need a reversible stop. (create campaign, campaign overview, update campaign status)
Add and update leads with a reconciliation identifier
The lead-import route requires an email address and supports standard contact data, up to 200 custom fields, duplicate controls, suppression checks, and optional returned lead IDs. Its default import settings do not ignore the global block list, unsubscribe list, duplicate-in-other-campaign check, or community bounce list. Leave those bypass flags off unless a documented, approved exception requires otherwise. (add leads to campaign)
Normalize the email address in your system and keep the returned Smartlead lead ID. Use the email plus campaign ID to reconcile an uncertain import, then use the lead ID for later changes. Smartlead documents separate routes to update contact or custom-field data, pause one lead, and resume immediately or after resume_lead_with_delay_days. (update lead, pause lead, resume lead)
Do not publish or code one unqualified batch maximum. The add-leads reference and error guide say 400 leads per request, while the help article updated on November 16, 2026 says 1,000. Batch at 400 until a controlled test in the authenticated account succeeds at a higher size or Smartlead confirms the account-specific limit. (add leads to campaign, error handling, Smartlead API getting-started guide)
A failed or timed-out write remains ambiguous because no general mutation idempotency token is documented. Before retrying an import or update, query the campaign state and reconcile by normalized email or returned lead ID.
Connect mailboxes with a narrow credential boundary
POST /email-accounts/save adds an SMTP/IMAP mailbox and validates both connections. The documented fields include sender identity, SMTP and IMAP hosts and ports, credentials, and warmup_enabled; optional settings include reply-to, daily maximum, spacing, signature, BCC, custom tracking domain, and warmup controls. (add SMTP account)
Smartlead also documents POST /email-accounts/save-oauth for Gmail and Outlook tokens and says it handles token refresh. That page assumes the caller already has the tokens, so it is not a complete authorization flow for an external integration. Credential changes use the save route with an account ID, while the account update route changes noncredential settings without reauthentication. (add OAuth account, update email account)
For the Smartlead acceptance fixture, store the mailbox ID and redacted connection result. Do not store reusable passwords or tokens with the test evidence.
Reconcile replies instead of sending twice
The per-lead history route returns inbound and outbound messages and supports an event_time_gt filter. The Master Inbox endpoint provides a cross-campaign view, supports filtering, can include complete history, and has a documented maximum of 20 records per page. (lead message history, Master Inbox messages)
POST /campaigns/{campaign_id}/reply-email-thread can send or schedule a threaded reply with CC, BCC, attachments, and signatures. Smartlead's reply-status route accepts the RFC 5322 Message-ID and can return a completion state, event time, and email_stats_id. Store the reply intent before sending, capture the Message-ID, and check status and history before any resend after a timeout. (send thread reply, reply status)
We would not build on the documented bulk message-history route until it passes a sandbox test. Its published URL contains an unexplained opaque path segment. Prefer per-lead history or Master Inbox for the first production version.
Use the current Smartlead webhook event contract
Create standard hooks with POST /webhook/create. Smartlead supports user, client, and campaign association levels, and payload fields vary by event, so the receiver must branch on event_type rather than assume one shared body. The newer help material describes account or user level as taking precedence over client, then campaign, with the most recently updated hook winning at the same level. (create webhook, webhook events, webhook troubleshooting)
| Current event name | What to use it for | Important boundary |
|---|---|---|
| `EMAIL_SENT` | Record a send event | Not proof of delivery or reading |
| `FIRST_EMAIL_SENT` | Detect the first sequence send | Event-specific payload |
| `EMAIL_OPEN` | Record tracking-pixel loading | Not proof that a human read the email |
| `EMAIL_LINK_CLICK` | Record a tracked link event | Depends on tracking configuration |
| `EMAIL_REPLY` | Route a tracked reply | Use this, not older `EMAIL_REPLIED` wording |
| `EMAIL_BOUNCE` | Update sending and contact state | Preserve the event payload for diagnosis |
| `LEAD_UNSUBSCRIBED` | Update suppression state | Confirm whether the action was local or global |
| `LEAD_CATEGORY_UPDATED` | Sync category changes | Branch on its event-specific fields |
| `CAMPAIGN_STATUS_CHANGED` | Reconcile campaign state | Read back state before downstream release |
| `UNTRACKED_REPLIES` | Route untracked replies | Available only at account or client level |
| `MANUAL_STEP_REACHED` | Queue a manual action | Do not treat it as an automated send |
These are the current standard names in the Create Webhook and Events references. Older core pages use names such as EMAIL_OPENED, EMAIL_REPLIED, and EMAIL_UNSUBSCRIBED; mixing the two taxonomies can silently drop routing rules. The help test article also lists MANUAL_REPLY_SENT, but the API Create Webhook list does not. Label that event help-documented and verify availability in the target account before relying on it. (create webhook, webhook events, test webhook payloads)
A Smartlead test event has is_test: true and fixed sample data. It proves only that the destination accepted the test. A live campaign may not produce every expected event or field. (test webhook payloads)
Secure webhooks and make retries harmless
Smartlead documents two mutually exclusive signing options, both off by default. HMAC follows the Standard Webhooks pattern with webhook-id, webhook-timestamp, and webhook-signature, and verification must use the exact raw request body. JWT uses ES256 in the Authorization header, includes a body hash, has a five-minute lifetime, and includes a unique jti. (HMAC webhook security, JWT webhook security)
The receiver should follow this order:
- Capture the raw bytes and relevant headers.
- Verify HMAC or JWT before parsing business fields.
- Insert the event into a durable queue with a unique constraint on
webhook-idor bodyevent_id. - Return
2xxwithin 60 seconds after durable insertion. - Process the business action asynchronously.
- Record the downstream result against the same event identifier.
Smartlead says failed authentication should return 401 so the event can be retried. Its current help documentation says failed live events receive up to eight attempts over about 28 hours, while 400, 413, and 422 are not retried. A receiver's 429 Retry-After can be honored up to one hour, and the same event keeps its event_id and webhook-id across retries. (retry failed webhooks, webhook troubleshooting)
Older API material describes five retries over roughly six hours and mentions X-Request-Id or synthetic composite identifiers. The newer help pages identify up to eight attempts and stable event_id or webhook-id, so build to the newer contract but confirm it with the acceptance test. Recent delivery logs cover three days, and the campaign retrigger endpoint can replay failures from the prior two weeks for a selected time window. (retry failed webhooks, retrigger webhooks)
Every Smartlead webhook should be traceable from its delivery record to the resulting CRM or campaign action. A production consumer must deduplicate the documented event identifier before those actions run.
Treat unsubscribe and block lists as scoped controls
Smartlead's unsubscribe endpoint stops future email to a campaign lead, but the help center distinguishes global unsubscribe from campaign-local unsubscribe. Imports can explicitly bypass unsubscribe and block-list checks, although the defaults do not. That means the endpoint description should not be presented as an unconditional, irreversible, account-wide suppression guarantee. (unsubscribe endpoint, unsubscribe behavior, add leads to campaign)
Block-list routes can list and add emails or domains, with optional client scope. Smartlead says applicable existing campaign matches are marked blocked and unsent email is cancelled, while new uploads normally skip blocked contacts. It also says deleting a block entry does not automatically change leads already marked Blocked, and a global block without a client does not necessarily cover later uploads into client campaigns. (domain block list, manage global block list, blocked leads behavior)
Keep one suppression ledger in the integrating system with the normalized address or domain, requested scope, source, timestamp, reason, and Smartlead write result. Apply the correct client and campaign scope during import, and fail closed if suppression state cannot be confirmed.
Parse errors defensively and learn limits from live responses
Do not hard-code one universal Smartlead API quota. The API rate guide says Standard credentials receive 60 requests per minute and Pro credentials 120 per minute, with hourly quotas, while the newer help article says admin credentials share 200 requests per minute per account and client credentials receive 60. Smartlead says the number in the actual 429 message is authoritative. State limits as account and credential dependent, then confirm the contracted limit and record what the live account returns. (rate limits, Smartlead API getting-started guide)
Three resource-heavy endpoints have an additional documented limit of 10 requests per 60 seconds: campaign lead statistics, all-lead activities, and domain-wise mailbox health. Their endpoint-specific 429 can be plain text without Retry-After or rate-limit headers, so a client must tolerate missing headers and wait up to 60 seconds. General documentation mentions X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After, but those fields are not guaranteed on every throttling response. (rate limits)
Retry 429, 500, 502, and 503 with jitter and any supplied Retry-After. Do not automatically retry 400, 401, 403, 404, 409, or 422 until the request, credentials, permissions, resource, conflict, or validation problem has been resolved. Smartlead examples include structured JSON, flat JSON, and plain text, so log status, content type, and a redacted body rather than assuming one error schema. (error handling, rate limits)
Run a synthetic Smartlead API acceptance test
Use this test design in your own controlled account. We have not run it against your Smartlead workspace. Use one test mailbox and two or more aliases you own. Never use prospects or production credentials in the fixture.
| Test | Synthetic action | Pass condition | Evidence to save |
|---|---|---|---|
| Authentication | Call a read route with valid and invalid credentials | Valid request works; invalid credential returns a handled auth failure | Redacted status and body |
| Draft creation | Create `LH-SL-API-ACCEPTANCE-<timestamp>` | ID is returned and campaign is not sending | Campaign ID and read-back state |
| Lead lifecycle | Add, update, pause, and resume one owned alias | One identity reconciles across every state | Lead ID and state reads |
| Duplicate write | Repeat the same lead add | Outcome is classified as skip, conflict, or duplicate | Both requests and read-back |
| Suppression | Block a second owned alias, then import normally | Address is skipped or blocked without bypass flags | Scope, import response, lead state |
| Test email | Send a test to an owned address | Sender and personalization are correct | Redacted message and request ID |
| Start transition | Send explicit `START`, then read state | Returned state is understood and read-back becomes expected live state | Request and status read-back |
| Live events | Send once and reply from the owned inbox | Current `EMAIL_SENT` and `EMAIL_REPLY` events reconcile with history | Raw signed events and history |
| Retry | Return `500` once, then `200` | Same event ID arrives again and creates one downstream effect | Two deliveries and one effect |
| Unsubscribe | Unsubscribe the owned live alias | Event arrives and no later sequence email is sent | Event, state, and send history |
| API reply | Send one reply with a unique token | Message-ID reaches completed status and appears once in history | Intent, Message-ID, status |
| Error parsing | Use an invalid payload and missing resource | Client handles JSON or text without crashing | Status, content type, redacted body |
Do not hammer the service to manufacture a 429. Unit-test throttling locally, then record the response shape and headers if a natural 429 occurs. Pass only when duplicate events create one effect, suppression survives a normal re-import, ambiguous writes can be reconciled, and the observed status and limits are represented in configuration rather than assumptions.
Our no-go conditions are simple: unsigned events, duplicate CRM actions, suppression bypass, unexplained START or ACTIVE behavior, blind write retries, or dependence on the opaque bulk-history route. Fix those before live contacts enter the workflow.
Decide where Smartlead fits in your outbound system
Before approval, give an operator the frozen test fixture and ask them to reconcile one success, one duplicate, one suppressed lead, and one failed webhook without developer help. Hold the release if they cannot identify the owner, current state, and safe next action for each case.
Our outbound services connect prospect research, sending infrastructure, outreach, reply handling, and CRM handoff as one owned system. Review our case studies for examples of evaluating the complete outbound operation, not one endpoint in isolation.
Ready to control your outbound workflow?
Bring your Smartlead account model, campaign steps, event receiver, and failure cases to a free ICP and campaign-fit review. We will map where sending, suppression, reply handling, and CRM ownership should live in the wider system. Book your free ICP review →
Frequently Asked Questions
An in-house SDR costs a full salary plus their tool stack, and you pay both through months of ramp before they add any pipeline. Training and management time come on top. A typical outbound retainer rents you someone else's system and starts over every month. A managed outbound system covers prospect research through qualified bookings, with infrastructure the client owns and a month-to-month engagement after the initial three months. See the current offer for terms.
With a properly built system, most clients see their first qualified replies within 2–3 days of campaign launch (after the 2–3 week warm-up period). The real power shows in month 2–3 as domain reputation strengthens, sequences optimize from real data, and targeting sharpens.
In-house works if you have a dedicated ops person, 6+ months of runway for ramping, and budget for 20+ tool subscriptions. Outsourcing makes sense when you want speed-to-pipeline, can't justify a full-time hire, or need multi-channel orchestration (email + LinkedIn + intent data) that requires specialized tooling.
Inbound attracts leads through content, SEO, and ads. Prospects come to you. Outbound proactively reaches prospects through targeted email, LinkedIn, and calls. Inbound scales slowly but compounds over time. Outbound delivers faster results but requires ongoing execution. The best B2B companies run both.
A compound outbound system is an orchestrated set of 20–30 tools (enrichment, sending, warm-up, analytics) that improves automatically over time. Month 2 outperforms month 1 because domain reputation strengthens, AI sequences learn from engagement data, and targeting tightens from real conversion patterns. It's the opposite of starting fresh every month.



