lemlist

lemlist is a sales engagement platform for cold outreach. It lets you find leads, enrich contact data, create multi-channel campaigns (email, LinkedIn, phone, WhatsApp), and manage replies — all from one place.

Prefer MCP over REST API

lemlist has a Model Context Protocol (MCP) server that wraps the API with better ergonomics for AI agents. Use it when available.

MCP endpoint: https://app.lemlist.com/mcp
Auth: OAuth (automatic) or X-API-Key header

Setup for Claude Code:

claude mcp add --transport http lemlist https://app.lemlist.com/mcp

Setup for Claude Desktop / Cursor: see MCP Setup

If MCP is not available, use the REST API at https://api.lemlist.com/api with Basic auth (username is always empty, password is the API key):

Authorization: Basic {base64(":YOUR_API_KEY")}

Common workflows

1. Find leads and launch a campaign

The most common workflow: find your ideal customers, create a campaign, and start outreach.

Steps:

1. Search the People Database (450M+ B2B contacts) by role, industry, company size, location
2. Create a campaign with an email sequence
3. Add leads to the campaign (with optional email enrichment)
4. Review and start the campaign

MCP tools: lemleads_search → create_campaign_with_sequence → add_sequence_step → add_lead_to_campaign → set_campaign_state

API equivalent:

POST /people-database/search
POST /campaigns
POST /campaigns/{id}/sequences
POST /campaigns/{id}/leads
PUT  /campaigns/{id}/start

Important:

• Always confirm with the user before starting a campaign
• Adding leads with enrichment consumes credits
• Campaigns need at least one connected sending channel (email, LinkedIn, etc.)

2. Enrich contacts

Find emails, phone numbers, and professional data for your leads. Enrichment is asynchronous — you submit the request and poll for results.

Steps:

1. Submit enrichment request (single or bulk, max 500)
2. Poll for results using the enrichment ID
3. Optionally push enriched data to CRM contacts

MCP tools: enrich_data or bulk_enrich_data → get_enrichment_result → push_leads_to_contacts

API equivalent:

POST /enrich              (single, async)
POST /enrich/bulk         (batch, async)
GET  /enrich/{id}/result  (poll status)

Important:

• Enrichment costs credits — always warn the user before proceeding
• Poll with reasonable intervals (5-10 seconds), results typically arrive within 30 seconds
• Bulk enrichment accepts up to 500 contacts per request

3. Monitor campaign performance

Analyze how campaigns are performing and identify what needs attention.

Steps:

1. List campaigns (filter by status: running, paused, draft)
2. Get stats for specific campaigns or bulk reports across all campaigns
3. Compare metrics: open rate, click rate, reply rate, bounce rate

MCP tools: get_campaigns → get_campaign_stats or get_campaigns_reports

API equivalent:

GET /campaigns
GET /campaigns/{id}/stats?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
GET /campaigns/reports

Key metrics to track: sent, opened, clicked, replied, bounced, unsubscribed. Reports include 65+ detailed metrics.

4. Handle inbox replies

Read and respond to lead replies across all channels (email, LinkedIn, SMS, WhatsApp).

Steps:

1. List inbox conversations (filter by channel, status, campaign)
2. Read conversation thread for context
3. Compose and send a reply on the appropriate channel

MCP tools: get_inbox_conversations → get_inbox_conversation → send_inbox_email / send_inbox_linkedin / send_inbox_sms / send_whatsapp_message

API equivalent:

GET  /inbox/conversations
GET  /inbox/conversations/{id}
POST /inbox/conversations/{id}/email
POST /inbox/conversations/{id}/linkedin
POST /inbox/conversations/{id}/sms
POST /inbox/conversations/{id}/whatsapp

5. Sync with your CRM

Keep lemlist and your CRM (HubSpot, Salesforce, Pipedrive, etc.) in sync.

Push leads to CRM contacts:

MCP tools: get_contact_lists → push_leads_to_contacts

Update lead data from external sources:

MCP tools: search_campaign_leads → update_lead_variables

API equivalent:

GET  /contacts/lists
POST /contacts/push
GET  /campaigns/{id}/leads?search=email@example.com
PATCH /campaigns/{id}/leads/{leadId}/variables

Tip: Use custom variables to store CRM IDs, deal stages, or any metadata on leads.

6. Check email deliverability

Ensure your sending infrastructure is healthy before launching campaigns.

Steps:

1. Check domain DNS health (MX, SPF, DMARC, blacklists)
2. Connect an email account (custom SMTP/IMAP)
3. Test connectivity

MCP tools: check_domain_health → connect_email_account → test_email_account

7. Set up webhook automations

Get real-time notifications when events happen in lemlist (replies, clicks, bounces, etc.).

Steps:

1. List existing webhooks
2. Create a webhook for specific events
3. Your endpoint receives POST requests with event data

MCP tools: get_webhooks → create_webhook

API equivalent:

GET    /webhooks
POST   /webhooks
DELETE /webhooks/{id}

Common webhook events: emailReplied, emailClicked, emailBounced, emailUnsubscribed, linkedinInviteAccepted

8. Write outreach sequences

Create or improve multi-step email sequences with best practices.

Steps:

1. Get current campaign sequences to review existing content
2. Compose new messages or improve existing ones
3. Add or update sequence steps (email, LinkedIn, phone, delay)

MCP tools: get_campaign_sequences → compose_messages → add_sequence_step or update_sequence_step

Best practices:

• Keep emails under 100 words
• One clear call-to-action per email
• Personalize beyond {{firstName}} — mention company, industry, recent news
• Space follow-ups: Day 3, 7, 14 pattern
• Mix channels: email → LinkedIn → phone

Constraints

Constraint	Detail
Rate limit	20 requests per 2 seconds per API key
Credit costs	Email enrichment, phone enrichment, email verification, and lead addition with enrichment all consume credits. Always check get_team_info for remaining credits and warn the user.
Async enrichment	Enrichment requests return an ID — you must poll get_enrichment_result for the actual data.
Campaign safety	Never start, pause, or delete a campaign without explicit user confirmation.
Lead vs Contact	A "lead" belongs to a campaign. A "contact" lives in the CRM. They are separate objects — pushing leads to contacts creates a copy.
Bulk limits	Bulk enrichment: max 500 per request. People Database search: paginated results.
Auth format	REST API uses Basic auth with an empty username and the API key as password. Do not use Bearer tokens with the REST API.

Reference

• API Documentation
• MCP Server Setup
• Help Center
• Guides & Tutorials