Instantly MCP Server

MCP Server for the Instantly API v2, providing access to email campaign and lead management functionality.

About Instantly API

The Instantly API v2 is a RESTful API that provides access to various resources and functions of the Instantly platform, including:

• Campaign management
• Lead management
• Email handling and verification
• Analytics
• Account management
• Blocklist management
• And more

This MCP server implements a subset of these endpoints to provide easy access to the most commonly used features.

API Reference

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

Tools

This MCP server implements the following tools that map to Instantly API v2 endpoints:

1. instantly_create_lead
   • API Endpoint: POST /api/v2/leads
   • Create a new lead
   • Inputs:
     • 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)
2. instantly_get_lead
   • API Endpoint: GET /api/v2/leads/{id}
   • Get details of a lead by ID
   • Input: id (string, uuid)
   • Returns: lead details
3. instantly_list_leads
   • API Endpoint: POST /api/v2/leads/list
   • List leads with optional filters
   • Inputs:
     • campaign (optional string, uuid)
     • list_id (optional string, uuid)
     • limit (optional number)
     • starting_after (optional string)
   • Returns: array of leads
4. instantly_update_lead
   • API Endpoint: PATCH /api/v2/leads/{id}
   • Update a lead's information
   • 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)
5. instantly_delete_lead
   • API Endpoint: DELETE /api/v2/leads/{id}
   • Delete a lead
   • Input: id (string, uuid)
6. instantly_list_campaigns
   • API Endpoint: GET /api/v2/campaigns
   • List campaigns with pagination support
   • Inputs:
     • limit (optional number, default 5, max 100)
     • starting_after (optional string) - For pagination, use the next_starting_after value from the previous response
     • status (optional number) - Filter campaigns by status (0: Draft, 1: Active, 2: Paused, 3: Completed, 4: Running Subsequences)
   • Returns: array of campaigns with pagination information
   • Pagination:
     • First request: Call without starting_after
     • Subsequent pages: Use the next_starting_after value from the previous response
     • When there are no more pages, the response will not contain a next_starting_after value
   • Example: To get only active campaigns, use status: 1
7. instantly_get_campaign
   • API Endpoint: GET /api/v2/campaigns/{id}
   • Get details of a campaign
   • Input: id (string, uuid)
   • Returns: campaign details
8. instantly_get_warmup_analytics
   • API Endpoint: POST /api/v2/accounts/warmup-analytics
   • Get warmup analytics for specified email accounts
   • Input: emails (array of strings)
   • Returns: Health scores and metrics for email warmup performance
   • Useful for monitoring email deliverability and account health
9. instantly_test_account_vitals
   • API Endpoint: POST /api/v2/accounts/test/vitals
   • Test the health and connectivity of email accounts in your Instantly workspace
   • Input: accounts (array of strings) - Can test multiple email addresses at once
   • Returns:
     • Overall test status
     • Summary of successful and failed accounts
     • Detailed information for each account including provider details
     • Troubleshooting recommendations for failed accounts
   • Helps identify issues with email account configuration, authentication, and API access
   • Example: {"accounts": ["user@example.com", "sales@company.com"]}
10. instantly_get_campaign_analytics
    • API Endpoint: GET /api/v2/campaigns/analytics
    • Get performance metrics for campaigns over a specified time period
    • Inputs:
      • id (optional string) - Campaign ID for a specific campaign
      • start_date (string) - Start date in YYYY-MM-DD format
      • end_date (string) - End date in YYYY-MM-DD format
    • Returns: Comprehensive metrics including open rates, reply rates, lead counts and opportunity data

Analytics Endpoints

The Instantly API provides powerful analytics endpoints to monitor the performance of your email campaigns and accounts:

1. Get Warmup Analytics
   • API Endpoint: POST /api/v2/accounts/warmup-analytics
   • Description: Retrieves warmup analytics data for specified email accounts
   • Required Scopes: accounts:read, accounts:all, all:read, or all:all
   • Request Body:
     { "emails": ["user@example.com"] }
   • Response: Provides daily and aggregate data about sent emails, inbox placement, spam placement, and received emails, along with health scores for each account
2. Test Account Vitals
   • API Endpoint: POST /api/v2/accounts/test/vitals
   • Description: Tests the health and connectivity of email accounts
   • Required Scopes: accounts:read, accounts:all, all:read, or all:all
   • Request Body:
     { "accounts": ["user@example.com"] }
   • Response: Returns success and failure lists with detailed information about account status and any detected issues
3. Get Campaign Analytics
   • API Endpoint: GET /api/v2/campaigns/analytics
   • Description: Retrieves performance metrics for one or multiple campaigns
   • Query Parameters:
     • id (optional): Campaign ID for a specific campaign
     • start_date: Start date for the analytics period
     • end_date: End date for the analytics period
   • Response: Returns comprehensive campaign statistics including:
     • Total leads count
     • Contacted leads count
     • Email open count
     • Reply count
     • Bounced count
     • Unsubscribed count
     • Completed count
     • Emails sent count
     • New leads contacted count
     • Total opportunities
     • Total opportunity value

For detailed information on request parameters and response formats, see the Instantly Analytics API documentation.

Additional Instantly API Endpoints

The Instantly API v2 includes many other endpoints not implemented in this MCP server, including:

• Campaign Management:
  • Create campaign: POST /api/v2/campaigns
  • Activate campaign: POST /api/v2/campaigns/{id}/activate
  • Pause campaign: POST /api/v2/campaigns/{id}/pause
  • Update campaign: PATCH /api/v2/campaigns/{id}
• Email:
  • Reply to email: POST /api/v2/emails/reply
  • List emails: GET /api/v2/emails
  • Get email: GET /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:
  • Create list: POST /api/v2/lead-lists
  • List lead lists: GET /api/v2/lead-lists

For a complete reference of all available endpoints, see the Instantly API Explorer.

Setup

API Key

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)

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

Docker

NPX

Build

Docker build:

Authentication

The Instantly API v2 uses Bearer token authentication. Your API key should be included in the Authorization header of all requests:

The MCP server handles this automatically when you provide your API key through the environment variable.

License

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.

Account Management Tools

This MCP server implements the following tools for account management:

1. instantly_create_account
   • API Endpoint: POST /api/v2/accounts
   • Create a new email account in Instantly
   • Inputs:
     • email (string): Email address of the account
     • first_name (string): First name associated with the account
     • last_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 username
     • imap_password (string): IMAP password
     • imap_host (string): IMAP host (e.g. imap.gmail.com)
     • imap_port (number): IMAP port (e.g. 993)
     • smtp_username (string): SMTP username
     • smtp_password (string): SMTP password
     • smtp_host (string): SMTP host (e.g. smtp.gmail.com)
     • smtp_port (number): SMTP port (e.g. 587)
     • daily_limit (optional number): Daily email sending limit
     • tracking_domain_name (optional string): Tracking domain name
2. instantly_list_accounts
   • API Endpoint: GET /api/v2/accounts
   • List email accounts in Instantly with automatic pagination
   • Inputs:
     • limit (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 pagination
     • search (optional string): Search term to filter accounts
     • status (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:
     • Default behavior: Returns a single page of results with a link to the next page
     • With fetch_all=true: Automatically fetches all pages and returns a comprehensive summary of all accounts, including:
       • Total account count
       • Account distribution by provider
       • Account distribution by status
       • Sample of accounts for reference
3. instantly_get_account
   • API Endpoint: GET /api/v2/accounts/{email}
   • Get details of a specific email account in Instantly
   • Input: email (string): Email address of the account to retrieve
4. instantly_update_account
   • API Endpoint: PATCH /api/v2/accounts/{email}
   • Update an existing email account in Instantly
   • Inputs:
     • email (string): Email address of the account to update
     • first_name (optional string): First name associated with the account
     • last_name (optional string): Last name associated with the account
     • daily_limit (optional number): Daily email sending limit
     • tracking_domain_name (optional string): Tracking domain name
     • skip_cname_check (optional boolean): Whether to skip CNAME check for tracking domain
     • remove_tracking_domain (optional boolean): Whether to remove tracking domain from the account
5. instantly_delete_account
   • API Endpoint: DELETE /api/v2/accounts/{email}
   • Delete an email account from Instantly
   • Input: email (string): Email address of the account to delete
6. instantly_pause_account
   • API Endpoint: POST /api/v2/accounts/{email}/pause
   • Pause an email account in Instantly
   • Input: email (string): Email address of the account to pause
7. instantly_resume_account
   • API Endpoint: POST /api/v2/accounts/{email}/resume
   • Resume a paused email account in Instantly
   • Input: email (string): Email address of the account to resume

Tool Testing Status

We'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:

For more details about the testing process and results, see Testing.md in the repository.

Known Issues

• The 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:
  • Using the contacts array parameter for email searches
  • Implementing automatic retries with empty request bodies
  • Various parameter formatting approaches

  We'll continue to work on resolving this issue in future releases.

Setup for Development

If you want to contribute to this project or run it locally for development:

1. Clone the repository:
   git clone https://github.com/bcharleson/Instantly-MCP.git cd Instantly-MCP
2. Install dependencies:
   npm install
3. Create a .env file in the root directory with your Instantly API key:
   INSTANTLY_API_KEY=your_api_key_here

   ⚠️ Important: Never commit your .env file or API key to version control. The .env file is included in .gitignore to prevent accidental commits.

4. Build the project:
   npm run build
5. Run the server:
   node dist/index.js

Contributing

Contributions are welcome! If you'd like to contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

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