Connect Smartlead to Claude: Control email warmup and lead lists

If you need to connect Smartlead to Claude to automate cold email outreach, manage complex lead lists, or dynamically control inbox warmup settings, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Smartlead's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Smartlead to ChatGPT or explore our broader architectural overview on connecting Smartlead to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling outreach ecosystem like Smartlead is a significant engineering challenge. You have to handle API key lifecycles, map nested JSON schemas to MCP tool definitions, and deal with Smartlead's specific state machines and rate limits. Every time an endpoint updates or a new parameter is required, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Smartlead, connect it natively to Claude Desktop, and execute complex outreach workflows using natural language.

The Engineering Reality of the Smartlead API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Smartlead's APIs is painful. You are not just integrating "Smartlead" - you are integrating campaign managers, global inbox pipelines, lead tracking databases, and warmup orchestration systems.

If you decide to build a custom MCP server for Smartlead, you own the entire API lifecycle. Here are the specific challenges you will face:

The Strict Campaign State Machine

Smartlead enforces a rigid state machine for campaigns. You cannot freely transition between statuses using generic terminology. For example, if an LLM tries to activate a campaign by setting the status to "ACTIVE", the API will reject it - the required string is "START". Furthermore, if an LLM sets a campaign to "STOPPED", that action is permanent and cannot be reversed. Sequence modifications require a campaign to be paused first; attempting to patch a sequence on a running campaign results in immediate validation errors. A robust integration must either train the model heavily on these constraints or enforce them at the middleware layer.

Bounded Warmup Configurations

Warmup settings in Smartlead are highly specific. You cannot simply pass warmup_enabled: true without adhering to documented integer ranges for associated parameters. For instance, total_warmup_per_day must strictly fall between 1 and 50, and reply_rate_percentage must be between 20 and 100. When LLMs generate tool calls for configuration, they frequently hallucinate or approximate these values based on general knowledge, leading to HTTP 400 Bad Request errors. Your MCP definitions must tightly bound these parameters in the JSON schema.

Distinct Aggregation Models

Smartlead's API separates individual lead interactions from bulk reporting. While you can query single leads globally by ID, extracting meaningful thread history requires the smartlead_campaign_leads_get_bulk_message_history endpoint. LLMs often attempt to iterate over leads one by one to compile a history report, which aggressively consumes tokens and rate limits.

Raw Rate Limits and Backoff

Smartlead enforces API quotas that you must respect. A critical architectural note: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Smartlead upstream API returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset), but the calling system - in this case, your AI agent or Claude implementation - is strictly responsible for implementing its own retry and exponential backoff logic.

Generating the Managed MCP Server for Smartlead

Instead of building your own translation layer, Truto derives MCP tool definitions dynamically from the underlying API resources and human-readable documentation. The resulting server exposes a JSON-RPC 2.0 endpoint that any MCP client can consume.

You can create this server in two ways: via the Truto dashboard or programmatically via the API.

Method 1: Via the Truto UI

For internal tools and direct Claude Desktop usage, the UI is the fastest path.

1. Log into your Truto account and navigate to the Integrated Accounts page.
2. Select your connected Smartlead environment.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter the tools by method (e.g., only read operations) or by tag (e.g., only campaigns or analytics).
6. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4....

Method 2: Via the Truto API

For platform builders provisioning MCP servers dynamically for end-users, use the API. This endpoint validates the tool configuration, provisions a secure, hashed token in the storage layer, and returns the connection URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smartlead Outreach Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": "2025-12-31T23:59:59Z"
  }'

The response contains the exact URL you need to configure Claude:

{
  "id": "mcp_srv_987654",
  "name": "Smartlead Outreach Agent",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8...",
  "config": {
    "methods": ["read", "write", "custom"]
  }
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero additional coding. The token embedded in the URL is cryptographically bound to your specific Smartlead account connection.

Method A: Via the Claude UI

If you are using Claude for Enterprise or Claude Desktop with UI configuration enabled:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server.
2. Paste your https://api.truto.one/mcp/... URL into the Server URL field.
3. Give the server a descriptive name like "Smartlead Integration".
4. Click Add.

Claude will immediately perform a protocol handshake, requesting the available tools via the tools/list endpoint, and they will become available in your current context.

Method B: Via the Manual Configuration File

If you are deploying Claude Desktop manually or configuring an environment for engineering teams, you can add the server to your configuration JSON file. This requires using the official @modelcontextprotocol/server-sse transport to handle the Server-Sent Events proxy over HTTPS.

Edit your claude_desktop_config.json (located in %APPDATA%\Claude\ on Windows or ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "smartlead-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
      ]
    }
  }
}

Restart Claude Desktop. The application will initialize the connection and sync the Smartlead schemas.

Hero Tools for Smartlead Workflows

Truto exposes the entirety of the Smartlead REST API as tool calls. Instead of overwhelming the model context with every possible endpoint, you should rely on these high-leverage operations for complex workflows.

Update a Smartlead Campaign

Tool: update_a_smartlead_campaign_by_id

This is the core tool for programmatic campaign administration. It allows Claude to adjust sending limits, toggle AI matching, alter plain text modes, and reconfigure out-of-office detection. Because campaigns must be structured carefully, the schema enforces correct typing on these sub-objects.

"The reply rate on the 'Q3 Enterprise Outreach' campaign is dropping. Update the campaign settings to enforce a maximum of 50 sends per day and enable AI email matching to improve deliverability."

Manage Campaign Status

Tool: smartlead_campaigns_update_campaign_status

Transitions a campaign between running and halted states. The tool schema specifically guides the LLM to use "START", "PAUSED", or "STOPPED", preventing state errors.

"I need to adjust the sequences on the 'Tech Founder Sequence'. Pause the campaign immediately so I can make those updates without validation errors."

Configure Email Warmup Settings

Tool: create_a_smartlead_email_account_warmup_setting

Controls the deliverability engine. Claude can use this to adjust daily volume limits, ramp-up speeds, and reply rates. The schema enforces the integer boundaries (e.g., maximum 50 warmup emails per day) to prevent API rejections.

"The email account 'sales-rep@acme-domain.com' is showing lower inbox placement. Reconfigure its warmup settings: set the total warmup per day to 35, the daily ramp-up to 5, and force a 60% reply rate."

Fetch Bulk Message History

Tool: smartlead_campaign_leads_get_bulk_message_history

Retrieves conversational context efficiently. Instead of scraping lead by lead, this bulk action grabs message threads for an entire campaign or subset of leads, providing the LLM with the context required to assess campaign health or draft bulk responses.

"Pull the bulk message history for the 'Outbound SaaS' campaign so we can analyze the sentiment of the most recent 100 replies."

Query the Master Inbox

Tool: smartlead_inbox_get_messages

Grabs cross-campaign replies. This allows Claude to act as a unified sales inbox manager, finding unread responses, categorizing them, or prepping replies regardless of which campaign triggered the lead.

"Check the master inbox for any unread messages that came in over the weekend. Filter the results to only show leads categorized as 'Interested'."

Execute Inbox Replies

Tool: smartlead_campaign_leads_reply_to_lead

Enables agentic engagement. Claude can draft a contextual reply, maintain the existing email thread, include signatures, and execute the send directly via the API.

"Draft and send a reply to John Doe in the 'Series A Founders' campaign. Acknowledge his request for a demo next Tuesday, confirm the time works, and maintain the thread context."

Extract Campaign Analytics

Tool: smartlead_analytics_get_campaign_performance

Extracts the raw performance data - total sent, open rate, click rate, reply rate - mapped over a specific date range. Crucial for automated reporting loops.

"Generate a performance summary for all campaigns running this month. Pull the analytics from the 1st to the 30th and highlight any campaign with an open rate below 40%."

To view the complete schema details, exact property keys, and the full list of available tools, review the Smartlead integration page.

Workflows in Action

Exposing individual tools is useful, but the true power of MCP lies in giving Claude the ability to chain these tools into autonomous, multi-step workflows.

Workflow 1: The Deliverability Triage Loop

When open rates drop, an operations manager usually has to manually pause campaigns, audit warmup limits, and reconfigure settings. Claude can orchestrate this entire diagnostic sequence.

"Check the top-level analytics for the 'Enterprise Outreach' campaign over the last 14 days. If the reply rate is below 5%, pause the campaign immediately. Then, fetch the warmup settings for the primary email account attached to it, and adjust the warmup to 40 emails a day with an 80% reply rate."

Execution steps:

1. Claude calls smartlead_analytics_get_top_level_analytics with the campaign ID and date constraints.
2. It analyzes the reply_rate in the JSON response.
3. Upon detecting a sub-5% rate, Claude calls smartlead_campaigns_update_campaign_status with status: "PAUSED".
4. It queries the email accounts via list_all_smartlead_campaign_email_accounts.
5. It issues create_a_smartlead_email_account_warmup_setting with the new integer limits.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Smartlead as Smartlead API

    User->>Claude: "Triage deliverability for campaign..."
    Claude->>Truto: call: smartlead_analytics_get_top_level_analytics
    Truto->>Smartlead: GET /v1/campaigns/{id}/analytics
    Smartlead-->>Truto: { "reply_rate": 3.2 }
    Truto-->>Claude: Result: 3.2%
    Claude->>Truto: call: smartlead_campaigns_update_campaign_status
    Truto->>Smartlead: POST /v1/campaigns/{id}/status<br>{ "status": "PAUSED" }
    Smartlead-->>Truto: 200 OK
    Truto-->>Claude: Campaign Paused
    Claude->>Truto: call: create_a_smartlead_email_account_warmup_setting
    Truto->>Smartlead: POST /v1/email-accounts/{id}/warmup<br>{ "total_warmup_per_day": 40, "reply_rate_percentage": 80 }
    Smartlead-->>Truto: 200 OK
    Truto-->>Claude: Warmup Updated
    Claude-->>User: "I've paused the campaign and aggressively increased the warmup parameters."

Workflow 2: Sequence Refactoring

Campaign sequences cannot be modified while running. Claude handles this state constraint naturally by sequencing the pause, update, and restart operations.

"I want to update the second email in the 'Q4 Upsell' sequence to mention our new pricing. Pause the campaign, fetch the current sequence steps, update step 2 with the new copy, and then start the campaign again."

Execution steps:

1. Claude calls smartlead_campaigns_update_campaign_status with status: "PAUSED".
2. It calls list_all_smartlead_campaign_sequences to retrieve the active copy.
3. It isolates sequence number 2 and modifies the email_body.
4. It calls update_a_smartlead_campaign_sequence_by_id with the new payload.
5. It calls smartlead_campaigns_update_campaign_status with status: "START".

flowchart TD
    A["Call: update_campaign_status<br>status: PAUSED"] --> B["Call: list_campaign_sequences"]
    B --> C["Analyze JSON<br>Extract sequence_number: 2"]
    C --> D["Call: update_campaign_sequence_by_id<br>Inject new HTML copy"]
    D --> E["Call: update_campaign_status<br>status: START"]

Workflow 3: Inbox Management and Reply Drafting

AI agents can act as tier-1 SDRs, categorizing replies and drafting contextual responses based on campaign history.

"Check the master inbox for unread messages today. For any lead that asks about pricing, update their category to 'Interested', and draft a reply that links to our pricing page while maintaining the thread."

Execution steps:

1. Claude calls smartlead_inbox_get_messages filtered by unread status and today's date.
2. It iterates through the text bodies, semantically identifying pricing questions.
3. For matches, it calls smartlead_inbox_update_category with the target category ID.
4. It executes smartlead_campaign_leads_reply_to_lead, passing the email_stats_id to maintain thread continuity and injecting the drafted response.

Security and Access Control

When granting an LLM access to your primary email distribution system, security is paramount. The Truto MCP architecture provides multiple layers of control over what Claude can see and do:

• Method Filtering: Limit an MCP server to read-only operations. By setting config.methods: ["read"] during creation, you prevent the LLM from accidentally deleting campaigns, sending rogue emails, or pausing infrastructure.
• Tag Filtering: Restrict tool discovery to specific functional domains. Setting config.tags: ["analytics"] ensures the server only exposes reporting endpoints, keeping inbox and campaign mutations out of the model's context.
• Token Authentication: By passing require_api_token_auth: true during configuration, the MCP URL alone is no longer sufficient. The connecting client must also supply a valid Truto API token via the Authorization header, preventing lateral access if the URL leaks.
• Time-to-Live Expirations: If you are provisioning an agent for a temporary audit or a specific sprint, attach an expires_at timestamp. The underlying infrastructure will automatically destroy the server access when the window closes.

Strategic Architecture for AI Outbound

Managing Smartlead infrastructure via natural language fundamentally changes outbound operations. Instead of clicking through deeply nested UI menus to pause a failing campaign or writing custom Python scripts to bulk-update warmup parameters, you simply ask Claude to do it.

By offloading the complexities of rate limits, state machine validation, and API authentication to a managed MCP layer, your engineering team stops maintaining fragile integration code. You can focus strictly on the system prompts and orchestration logic, letting the Truto server handle the mechanics of translating intent into secure, deterministic API execution.