Provides access to Instantly API v2 for email campaign and lead management functionality.
MCP Server for the Instantly API v2, providing access to email campaign and lead management functionality.
The Instantly API v2 is a RESTful API that provides access to various resources and functions of the Instantly platform, including:
This MCP server implements a subset of these endpoints to provide easy access to the most commonly used features.
The full Instantly API v2 documentation is available at: - API Explorer - API Schemas - Analytics Endpoints
The base URL for all API requests is: https://api.instantly.ai/api/v2
This MCP server implements the following tools that map to Instantly API v2 endpoints:
instantly_create_leadPOST /api/v2/leadsInputs:
email (string)first_name (optional string)last_name (optional string)company_name (optional string)campaign (optional string, uuid)list_id (optional string, uuid)personalization (optional string)website (optional string)phone (optional string)custom_variables (optional object)instantly_get_lead
GET /api/v2/leads/{id}id (string, uuid)Returns: lead details
instantly_list_leads
POST /api/v2/leads/listcampaign (optional string, uuid)list_id (optional string, uuid)limit (optional number)starting_after (optional string)Returns: array of leads
instantly_update_lead
PATCH /api/v2/leads/{id}Inputs:
id (string, uuid)first_name (optional string)last_name (optional string)company_name (optional string)personalization (optional string)website (optional string)phone (optional string)custom_variables (optional object)instantly_delete_lead
DELETE /api/v2/leads/{id}Input: id (string, uuid)
instantly_list_campaigns
GET /api/v2/campaignslimit (optional number, default 5, max 100)starting_after (optional string) - For pagination, use the next_starting_after value from the previous responsestatus (optional number) - Filter campaigns by status (0: Draft, 1: Active, 2: Paused, 3: Completed, 4: Running Subsequences)starting_afternext_starting_after value from the previous responsenext_starting_after valueExample: To get only active campaigns, use status: 1
instantly_get_campaign
GET /api/v2/campaigns/{id}id (string, uuid)Returns: campaign details
instantly_get_warmup_analytics
POST /api/v2/accounts/warmup-analyticsemails (array of strings)Useful for monitoring email deliverability and account health
instantly_test_account_vitals
POST /api/v2/accounts/test/vitalsaccounts (array of strings) - Can test multiple email addresses at onceExample: {"accounts": ["[email protected]", "[email protected]"]}
instantly_get_campaign_analytics
GET /api/v2/campaigns/analyticsid (optional string) - Campaign ID for a specific campaignstart_date (string) - Start date in YYYY-MM-DD formatend_date (string) - End date in YYYY-MM-DD formatThe Instantly API provides powerful analytics endpoints to monitor the performance of your email campaigns and accounts:
POST /api/v2/accounts/warmup-analyticsaccounts:read, accounts:all, all:read, or all:all{
"emails": ["[email protected]"]
}Response: Provides daily and aggregate data about sent emails, inbox placement, spam placement, and received emails, along with health scores for each account
Test Account Vitals
POST /api/v2/accounts/test/vitalsaccounts:read, accounts:all, all:read, or all:all{
"accounts": ["[email protected]"]
}Response: Returns success and failure lists with detailed information about account status and any detected issues
Get Campaign Analytics
GET /api/v2/campaigns/analyticsid (optional): Campaign ID for a specific campaignstart_date: Start date for the analytics periodend_date: End date for the analytics periodFor detailed information on request parameters and response formats, see the Instantly Analytics API documentation.
The Instantly API v2 includes many other endpoints not implemented in this MCP server, including:
POST /api/v2/campaignsPOST /api/v2/campaigns/{id}/activatePOST /api/v2/campaigns/{id}/pauseUpdate campaign: PATCH /api/v2/campaigns/{id}
Email:
POST /api/v2/emails/replyGET /api/v2/emailsGET /api/v2/emails/{id}Count unread emails: GET /api/v2/emails/unread/count
Account Management:
These endpoints are now available as tools in this MCP server! See the "Account Management Tools" section below.
Email Verification:
Verify email: POST /api/v2/email-verification
Lead Lists:
POST /api/v2/lead-listsGET /api/v2/lead-listsFor a complete reference of all available endpoints, see the Instantly API Explorer.
Get an Instantly API key from your Instantly account settings: 1. Go to integrations in your Instantly dashboard 2. Click the "API Keys" section in the left sidebar 3. Click the "Create API Key" button 4. Enter a name for your API key 5. Select the scopes you want this key to have access to 6. Create and copy your API key (note: it will only be shown once)
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"instantly": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"INSTANTLY_API_KEY",
"mcp/instantly"
],
"env": {
"INSTANTLY_API_KEY": "<YOUR_API_KEY>"
}
}
}
}{
"mcpServers": {
"instantly": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-instantly"
],
"env": {
"INSTANTLY_API_KEY": "<YOUR_API_KEY>"
}
}
}
}Docker build:
docker build -t mcp/instantly -f Dockerfile .The Instantly API v2 uses Bearer token authentication. Your API key should be included in the Authorization header of all requests:
Authorization: Bearer YOUR_API_KEYThe MCP server handles this automatically when you provide your API key through the environment variable.
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
This MCP server implements the following tools for account management:
instantly_create_accountPOST /api/v2/accountsInputs:
email (string): Email address of the accountfirst_name (string): First name associated with the accountlast_name (string): Last name associated with the account provider_code (number): Provider code (1: Custom IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)imap_username (string): IMAP usernameimap_password (string): IMAP passwordimap_host (string): IMAP host (e.g. imap.gmail.com)imap_port (number): IMAP port (e.g. 993)smtp_username (string): SMTP usernamesmtp_password (string): SMTP passwordsmtp_host (string): SMTP host (e.g. smtp.gmail.com)smtp_port (number): SMTP port (e.g. 587)daily_limit (optional number): Daily email sending limittracking_domain_name (optional string): Tracking domain nameinstantly_list_accounts
GET /api/v2/accountslimit (optional number): The number of accounts to return per page (max 100, default 10)starting_after (optional string): The ID of the last item in the previous page - used for paginationsearch (optional string): Search term to filter accountsstatus (optional number): Status filter (1: Active, 2: Paused, -1: Connection Error, -2: Soft Bounce Error, -3: Sending Error)provider_code (optional number): Provider code filter (1: Custom IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)fetch_all (optional boolean): Whether to automatically fetch all pages and provide a comprehensive summary. Use this to get information about all accounts.Pagination:
fetch_all=true: Automatically fetches all pages and returns a comprehensive summary of all accounts, including:instantly_get_account
GET /api/v2/accounts/{email}Input: email (string): Email address of the account to retrieve
instantly_update_account
PATCH /api/v2/accounts/{email}Inputs:
email (string): Email address of the account to updatefirst_name (optional string): First name associated with the accountlast_name (optional string): Last name associated with the accountdaily_limit (optional number): Daily email sending limittracking_domain_name (optional string): Tracking domain nameskip_cname_check (optional boolean): Whether to skip CNAME check for tracking domainremove_tracking_domain (optional boolean): Whether to remove tracking domain from the accountinstantly_delete_account
DELETE /api/v2/accounts/{email}Input: email (string): Email address of the account to delete
instantly_pause_account
POST /api/v2/accounts/{email}/pauseInput: email (string): Email address of the account to pause
instantly_resume_account
POST /api/v2/accounts/{email}/resumeemail (string): Email address of the account to resumeWe've thoroughly tested all tools implemented in this MCP server to ensure they work correctly with the Instantly API v2. Below is a summary of the testing status:
| # | Tool Name | Status | Notes |
|---|---|---|---|
| 1 | instantly_list_campaigns |
✅ VERIFIED | Successfully lists campaigns with pagination support |
| 2 | instantly_list_leads |
❌ NOT WORKING | Persistent API error - "Invalid email address" when attempting to list leads |
| 3 | instantly_delete_lead |
✅ VERIFIED | Successfully deletes leads by ID or email address |
| 4 | instantly_create_lead |
✅ VERIFIED | Successfully creates new leads with proper data |
| 5 | instantly_get_lead |
✅ VERIFIED | Successfully retrieves lead details by ID |
| 6 | instantly_update_lead |
✅ VERIFIED | Successfully updates existing lead information |
| 7 | instantly_list_accounts |
✅ VERIFIED | Successfully lists all email accounts with statistics |
| 8 | instantly_get_account |
✅ VERIFIED | Successfully retrieves detailed account information |
| 9 | instantly_test_account_vitals |
✅ VERIFIED | Successfully retrieves account health information |
| 10 | instantly_get_warmup_analytics |
✅ VERIFIED | Successfully retrieves warmup data for accounts |
For more details about the testing process and results, see Testing.md in the repository.
instantly_list_leads tool currently returns an "Invalid email address" API error when attempting to list leads without a specific email filter. We've tried multiple approaches to fix this issue, including:contacts array parameter for email searchesWe'll continue to work on resolving this issue in future releases.
If you want to contribute to this project or run it locally for development:
Clone the repository:
git clone https://github.com/bcharleson/Instantly-MCP.git
cd Instantly-MCPInstall dependencies:
npm installCreate a .env file in the root directory with your Instantly API key:
INSTANTLY_API_KEY=your_api_key_here⚠️ Important: Never commit your
.envfile or API key to version control. The.envfile is included in.gitignoreto prevent accidental commits.
Build the project:
npm run buildRun the server:
node dist/index.jsContributions are welcome! If you'd like to contribute:
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)Before submitting a pull request, please ensure: - Your code follows the project's coding style - You've added tests for new functionality - All tests pass - You've updated the documentation if necessary