LeadHaste

Smartlead API Guide: Build a Safe Outbound Workflow

Christian Sørensen
Christian Sørensen·Nov 17, 2026·18 min read

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.

SurfaceUseful operationControl your system must own
CampaignsCreate, configure, test, start, pauseRelease approval and status read-back
LeadsAdd, update, pause, resumeNormalized identity and duplicate reconciliation
MailboxesConnect SMTP/IMAP or ingest OAuth tokensSecret handling and provider authorization
RepliesRead history, send a thread reply, check statusIntent log and Message-ID reconciliation
WebhooksReceive campaign and message eventsAuthentication, durable queue, deduplication
SuppressionUnsubscribe and block emails or domainsDurable 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:

[@portabletext/react] Unknown block type "code", specify a component for it in the `components.types` prop

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:

  1. Create a timestamped draft and store its returned ID.
  2. Add the sequence and campaign settings.
  3. Attach one controlled mailbox.
  4. Add only owned synthetic addresses.
  5. Send a test message for rendering and sender verification.
  6. Obtain an explicit release approval.
  7. 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 nameWhat to use it forImportant boundary
`EMAIL_SENT`Record a send eventNot proof of delivery or reading
`FIRST_EMAIL_SENT`Detect the first sequence sendEvent-specific payload
`EMAIL_OPEN`Record tracking-pixel loadingNot proof that a human read the email
`EMAIL_LINK_CLICK`Record a tracked link eventDepends on tracking configuration
`EMAIL_REPLY`Route a tracked replyUse this, not older `EMAIL_REPLIED` wording
`EMAIL_BOUNCE`Update sending and contact statePreserve the event payload for diagnosis
`LEAD_UNSUBSCRIBED`Update suppression stateConfirm whether the action was local or global
`LEAD_CATEGORY_UPDATED`Sync category changesBranch on its event-specific fields
`CAMPAIGN_STATUS_CHANGED`Reconcile campaign stateRead back state before downstream release
`UNTRACKED_REPLIES`Route untracked repliesAvailable only at account or client level
`MANUAL_STEP_REACHED`Queue a manual actionDo 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:

  1. Capture the raw bytes and relevant headers.
  2. Verify HMAC or JWT before parsing business fields.
  3. Insert the event into a durable queue with a unique constraint on webhook-id or body event_id.
  4. Return 2xx within 60 seconds after durable insertion.
  5. Process the business action asynchronously.
  6. 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.

Dimitar Petkov, LeadHaste

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.

TestSynthetic actionPass conditionEvidence to save
AuthenticationCall a read route with valid and invalid credentialsValid request works; invalid credential returns a handled auth failureRedacted status and body
Draft creationCreate `LH-SL-API-ACCEPTANCE-<timestamp>`ID is returned and campaign is not sendingCampaign ID and read-back state
Lead lifecycleAdd, update, pause, and resume one owned aliasOne identity reconciles across every stateLead ID and state reads
Duplicate writeRepeat the same lead addOutcome is classified as skip, conflict, or duplicateBoth requests and read-back
SuppressionBlock a second owned alias, then import normallyAddress is skipped or blocked without bypass flagsScope, import response, lead state
Test emailSend a test to an owned addressSender and personalization are correctRedacted message and request ID
Start transitionSend explicit `START`, then read stateReturned state is understood and read-back becomes expected live stateRequest and status read-back
Live eventsSend once and reply from the owned inboxCurrent `EMAIL_SENT` and `EMAIL_REPLY` events reconcile with historyRaw signed events and history
RetryReturn `500` once, then `200`Same event ID arrives again and creates one downstream effectTwo deliveries and one effect
UnsubscribeUnsubscribe the owned live aliasEvent arrives and no later sequence email is sentEvent, state, and send history
API replySend one reply with a unique tokenMessage-ID reaches completed status and appears once in historyIntent, Message-ID, status
Error parsingUse an invalid payload and missing resourceClient handles JSON or text without crashingStatus, 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.

SmartleadAPIcold emailoutbound operations
Christian Sørensen

Christian Sørensen

Co-Founder & CEO, LeadHaste

Co-founded LeadHaste and runs the multichannel side of the system, from LinkedIn outreach to the agents that qualify replies before a human ever sees them.

Newsletter

The weekly for people who buy outbound.

Five things that changed in outbound this week, why they matter, and what to do about each. Read by founders, sales leaders and growth leads at B2B companies.

Read past issues →

Ready to build outbound that compounds?

We'll build the entire system for your business, and the infrastructure it runs on stays yours.

Book my free review →