Overview

Smartlead's UI works fine when you are managing five campaigns and a few hundred leads. But the moment your outbound operation scales past that, the clicking becomes the bottleneck. You are manually uploading CSVs, copy-pasting lead data between tools, and checking campaign status one at a time. The API exists to eliminate all of that, but Smartlead's documentation leaves gaps that cost hours of debugging if you don't know where to look.

This guide covers the Smartlead API end to end: authentication setup, the endpoints that matter for campaign and lead management, webhook configuration for real-time event handling, and the integration patterns that connect Smartlead to the rest of your GTM stack. Whether you are building a custom enrichment-to-outreach pipeline with Clay or syncing campaign data back to your CRM, the API is how you turn Smartlead from a standalone tool into a programmable sending layer.

One important caveat upfront: API access requires Smartlead's Pro Plan ($94/month) or higher. The Basic Plan does not include API access, and this is the single most common frustration for teams that discover it after building integration specs.

Authentication and API Fundamentals

Smartlead uses API key authentication, which is the simplest pattern you will encounter in GTM integrations. If you have worked with REST API auth methods before, this is the straightforward end of the spectrum.

Getting Your API Key

Base URL and Request Format

All requests go to https://server.smartlead.ai/api/v1/ with your API key passed as a query parameter: ?api_key=YOUR_API_KEY. This is slightly unusual because most modern APIs pass authentication in headers, but Smartlead uses query parameters for their key. Request and response bodies use JSON.

Rate Limits

Smartlead enforces rate limits that vary by endpoint and plan tier. The Pro Plan allows approximately 100 requests per minute across most endpoints. Campaign creation and lead upload endpoints have lower limits, roughly 30 requests per minute, because they trigger heavier backend processing.

When you hit a rate limit, the API returns a 429 status code with a Retry-After header. The correct response is exponential backoff: wait the specified duration, then retry with increasing delays on subsequent failures. Teams that ignore this and hammer the API with immediate retries risk temporary key suspension.

For a deeper look at managing rate limits across your full stack, see our API rate limiting guide. The short version: batch your operations, respect the 429 responses, and never run parallel API calls to the same endpoint without a queue.

Campaign Management Endpoints

Campaigns are the core object in Smartlead. Every outbound sequence you run maps to a campaign, and the API gives you full CRUD control over them. This is where programmatic campaign creation saves the most time because setting up campaigns manually through the UI takes 10-15 minutes each, and agencies running dozens of client campaigns feel that overhead acutely.

Creating Campaigns

The POST /api/v1/campaigns/create endpoint accepts a JSON body with the campaign name, sending schedule, and configuration options. A minimal creation request looks like this:

After creation, you configure the campaign in separate calls. This modular approach is actually useful because it lets you build campaigns incrementally: create the shell, add sequences, configure settings, upload leads, and activate—each as a discrete step in your automation pipeline.

Configuring Sequences

Sequences are the email steps within a campaign. The POST /api/v1/campaigns/{campaign_id}/sequences endpoint lets you add and order sequence steps. Each step includes the subject line, body (supporting HTML and Smartlead variables like {{first_name}}), and the delay before sending.

The key here is variable mapping. If your leads include custom fields from a Clay enrichment pipeline, you need to ensure the variable names in your email templates match the field names in your lead upload. A mismatch means the variable renders as blank or literal text, and there is no validation at upload time to catch it.

Listing and Updating Campaigns

GET /api/v1/campaigns?api_key=YOUR_KEY returns all campaigns with their status, lead counts, and basic metrics. Use this for building dashboards or monitoring systems that track campaign health across your entire operation.

PATCH /api/v1/campaigns/{campaign_id}/status lets you pause, resume, or stop campaigns programmatically. This is critical for building guardrails: if your deliverability monitoring detects a bounce rate spike, your automation can pause the offending campaign before it damages sender reputation further. Teams running deliverability-focused operations often build this as an automated circuit breaker.

Campaign Settings

The settings endpoint (PATCH /api/v1/campaigns/{campaign_id}/settings) controls sending behavior: daily send limits per mailbox, sending windows (time zones and hours), stop-on-reply behavior, and tracking preferences. Two settings deserve special attention:

• stop_on_reply: When enabled, a lead who replies is automatically removed from the sequence. This should almost always be true for cold outreach. Sending a follow-up to someone who already replied is the fastest way to burn goodwill.
• track_opens: Open tracking inserts a pixel that modifies deliverability. For campaigns targeting technical audiences or companies with aggressive email security, disabling open tracking can improve inbox placement. The tradeoff is losing open rate data, which as we discuss in our Smartlead analytics guide, is already an unreliable metric.

Lead Management Endpoints

Lead management is where the API delivers the most value over the UI. Uploading leads via CSV through the dashboard means manual field mapping every time, no validation before import, and no way to programmatically control which leads enter which campaigns based on real-time qualification data.

Adding Leads to Campaigns

The POST /api/v1/campaigns/{campaign_id}/leads endpoint accepts an array of lead objects. Each lead requires at minimum an email address, but you should include every field your sequences reference.

The 100-lead batch limit is the constraint you will hit first when scaling. If your Clay table enriches 2,000 leads and you want to push them into a Smartlead campaign, you need 20 sequential API calls with proper rate limiting between each. Build this as a queue-based operation, not a synchronous loop, especially if you are running this inside n8n or Make where timeout behavior can be unpredictable.

Lead Status and Management

The GET /api/v1/campaigns/{campaign_id}/leads endpoint returns lead status within a campaign: queued, sent, replied, bounced, or unsubscribed. This data is essential for building closed-loop reporting. When a lead replies in Smartlead, that signal should propagate back to your CRM and enrichment systems to update the lead's status and prevent other campaigns from targeting the same person.

You can also remove leads from campaigns via DELETE /api/v1/campaigns/{campaign_id}/leads, which is useful for building exclusion logic. If a lead books a meeting through your scheduling tool, your automation should immediately remove them from all active Smartlead campaigns. This requires querying across campaigns to find where the lead exists, which means maintaining a local index or making list calls across all active campaigns.

Global Lead Operations

The GET /api/v1/leads endpoint lets you search for leads across all campaigns. This is the endpoint you use for de-duplication checks before uploading: query by email address to see if a lead already exists in another campaign, and skip the upload if they do. Teams scaling de-duplication and standardization workflows rely on this to prevent the same prospect from receiving outreach from multiple campaigns simultaneously.

Webhook Configuration

Smartlead supports outbound webhooks that fire when specific events occur: lead replies, emails bounce, leads unsubscribe, or campaign sequences complete. Webhooks turn Smartlead from a system you poll for updates into one that pushes events to you in real time.

Setting Up Webhooks

Configure webhooks through the POST /api/v1/webhooks endpoint or via Settings > Webhooks in the UI. Each webhook requires a target URL and the event types you want to subscribe to.

Webhook Payload Structure

Smartlead webhook payloads include the lead's email, the campaign ID, the sequence step that triggered the event, and event-specific data (reply text for replies, bounce reason for bounces). The payload does not include the full lead record by default, which means if you need enrichment data or custom fields to process the event, you will need to make a follow-up API call to GET /api/v1/leads/{email} or maintain your own lead data store.

This is a common pain point. Your webhook handler receives a reply notification with just an email and campaign ID, but your downstream processing (CRM update, Slack notification, qualification trigger) needs the full lead context. Either enrich the payload in your webhook handler or, better yet, maintain a synchronized lead database that your handler can query locally. For teams building production webhook architectures, the decouple-ingestion-from-processing pattern applies directly here.

Webhook Reliability

Smartlead retries failed webhook deliveries up to three times with increasing delays. If your endpoint is down for an extended period, events are lost after the retry window expires. There is no built-in dead letter queue or event replay mechanism.

Integration Patterns That Work

The API endpoints are building blocks. The real value comes from wiring them into automated workflows that connect Smartlead to the rest of your GTM infrastructure. Here are the patterns that teams actually run in production.

Pattern 1: Clay-to-Smartlead Enrichment Pipeline

This is the most common integration pattern. Clay enriches and qualifies leads, then pushes qualified leads into Smartlead campaigns based on segment or persona.

The workflow: Clay table enriches leads from your source (CRM export, Apollo list, inbound form). Qualification columns score and filter leads. A webhook or HTTP request column pushes passing leads to the appropriate Smartlead campaign via the leads endpoint. Custom fields from Clay (company size, tech stack, funding stage) map to Smartlead variables for deep personalization in sequences.

The key implementation detail is the campaign routing logic. Don't push all leads to a single campaign. Use Clay's formula columns to determine which campaign each lead should enter based on persona, company size, or intent signals. Then route the API call to the correct campaign ID.

Pattern 2: CRM Sync via Webhooks

When a lead replies in Smartlead, the REPLY_RECEIVED webhook fires. Your handler creates or updates a CRM record with the reply content, updates the lead's status, and optionally creates a task for the assigned rep. This gives reps visibility into email engagement without switching to Smartlead.

The reverse flow is equally important: when a deal closes or a lead is disqualified in your CRM, that event should trigger lead removal from active Smartlead campaigns. Build this as a CRM webhook that calls Smartlead's lead removal endpoint. Teams running CRM-to-sequencer field mapping need this bidirectional sync to keep data consistent across systems.

Pattern 3: Automated Campaign Lifecycle

For agencies or teams running high campaign volumes, automate the entire lifecycle: campaign creation, sequence configuration, lead upload, activation, monitoring, and teardown. This turns campaign launch from a 30-minute manual process into a single API call (or a short automation sequence).

Store campaign templates as JSON configurations in your codebase or a configuration database. When it's time to launch a new campaign, your automation reads the template, creates the campaign, configures sequences and settings, uploads the target leads from your enrichment pipeline, and activates sending. This approach is especially powerful for agencies managing multiple client campaigns where each client has standard campaign structures that repeat monthly.

Pattern 4: Engagement-Based Routing

Use the analytics endpoints to pull campaign performance data and feed it into routing decisions. If a particular campaign or sequence variant shows low reply rates, automatically pause it and redirect leads to a better-performing variant. This requires polling the analytics endpoint on a schedule and comparing performance against thresholds you define.

The sophistication ceiling here is high. You can build adaptive systems that A/B test sequence variants, measure results through the API, and automatically scale the winning variants, all without manual intervention. Teams exploring sequence A/B testing can use the API to automate what is otherwise a tedious manual process.

Error Handling and Debugging

Smartlead's API returns standard HTTP status codes, but the error messages vary in helpfulness. Here is what you will encounter and how to handle each case.

Common Error Codes

Silent Failures to Watch For

The most dangerous errors are the ones Smartlead doesn't tell you about. Several operations return 200 success codes while partially failing:

• Lead uploads with invalid emails: A batch of 100 leads where 5 have malformed emails returns 200 with a success count of 95. If you don't check the response body's error array, those 5 leads disappear silently.
• Duplicate leads: Uploading a lead that already exists in the campaign returns 200 but does not add a duplicate. This is actually correct behavior, but it means your upload count won't match your expected count if you're not deduplicating before upload.
• Variable mismatches: Sequences referencing custom fields that don't exist in the lead data send with blank variable substitutions. There is no validation at upload or campaign activation time.

Debugging Toolkit

Build a small set of debugging utilities before you need them:

• API call logger: Record every API request and response with timestamps. When something breaks at 2 AM, the logs tell you exactly which call failed and why.
• Reconciliation script: A scheduled job that compares your local lead database against Smartlead's lead status API. Flags discrepancies for review.
• Health check endpoint: A simple script that calls GET /api/v1/campaigns every 5 minutes and alerts if the response time exceeds 3 seconds or the status code is not 200. Early warning for API degradation.

Beyond Individual API Calls

Building a Smartlead API integration for a single campaign workflow is a weekend project. Making it work across 50 campaigns, three enrichment sources, a CRM, and a reporting dashboard is where things break down.

The problem is not any individual integration. It is the accumulated complexity. Your Clay-to-Smartlead pipeline works until you realize Smartlead reply webhooks need to update Salesforce, which also needs to trigger a Slack notification, which should reference the original enrichment data from Clay that is no longer easily accessible. Each connection works in isolation. The system fails as a whole because no single tool has the complete picture.

Campaign performance data lives in Smartlead. Lead enrichment context sits in Clay. Deal stage and rep assignment are in the CRM. When your webhook handler receives a reply, it needs to pull from all three to make an intelligent routing decision. So you build custom middleware. Then you maintain it. Then it breaks at 3 AM.

This is the problem that context platforms like Octave solve. Instead of building and maintaining point-to-point integrations between Smartlead, Clay, your CRM, and every other tool in the stack, Octave maintains a unified context layer that any system can query. When a Smartlead reply comes in, your handler doesn't need to make five API calls to assemble the lead's full picture. The context is already unified and available. For teams running Smartlead at the volumes where the API becomes necessary in the first place, this is the infrastructure that determines whether your automations scale gracefully or collapse under their own complexity.

FAQ

Conclusion

The Smartlead API transforms the platform from a manual email tool into a programmable component of your outbound infrastructure. The endpoints are straightforward once you understand the authentication model, rate limits, and the batch constraints on lead management. The real complexity lives not in any single API call but in the integration patterns that connect Smartlead to the rest of your GTM stack.

Start with the simplest pattern that solves your immediate bottleneck. For most teams, that is automating lead uploads from an enrichment pipeline like Clay. Once that is stable, add webhook-based reply routing to your CRM. Then build out campaign lifecycle automation and performance monitoring. Each layer reduces manual work and increases the speed at which your outbound operation can iterate.

The teams that extract the most value from the API are the ones that treat error handling and monitoring as first-class concerns from day one. Build your logging, reconciliation, and health checks before you need them. When something breaks at scale, and it will, those are the systems that tell you what happened and where to fix it.

Related Articles

• Smartlead and Clay Integration Guide: Enrich Leads Before Outreach
• REST API Authentication Methods for GTM Integrations
• API Rate Limiting Strategies for GTM Engineers
• Webhook Best Practices for Sales and Marketing Automation
• Smartlead Analytics Guide: Metrics, Dashboards, and Campaign Optimization