Instantly AI FastMCP Integration

This project provides a robust integration between Instantly AI and the FastMCP framework, enabling advanced campaign management, lead operations, sender account setup, and automated email workflows using OpenAI-powered agents. It is designed for users who want to automate and scale their email outreach, lead nurturing, and campaign analytics with minimal manual effort.

Features

• Campaign Creation, Editing, Deletion: Create campaigns with multiple sender addresses, manage sequences, and delete campaigns safely.
• Lead Management: Add, move, and bulk upload leads; create and manage lead lists.
• Sender Account Setup: Add Gmail and other provider accounts with IMAP/SMTP settings and app passwords.
• Automated Sequences & Follow-Ups: Schedule multi-step email sequences and follow-ups with advanced targeting (e.g., stop-on-reply).
• Attachment Handling: Upload files and automatically hyperlink them in email bodies.
• Analytics & Reporting: View campaign and warmup analytics, export data, and monitor deliverability.
• OpenAI Agent Integration: Use natural language prompts to automate all operations.
• Error Handling & API Compliance: Robust handling for all HTTP methods, including fixes for DELETE/POST/PATCH edge cases.

Project Structure

fastmcp_instantlyai/
│
├── instantly_mcp_server/
│   ├── tools/
│   │   ├── campaign.py             # Campaign management tools
│   │   ├── lead.py                 # Lead management tools
│   │   ├── leadlist.py             # Lead list tools
│   │   ├── account.py              # Sender account tools
│   │   ├── campaignsubsequence.py  # Follow-up sequence tools
│   │   ├── s3.py                   # S3 attachment tools
│   │   └── ...                     # Other tool modules
│   ├── client.py                   # HTTP client for Instantly API
│   ├── auth.py                     # Authentication and headers
│   └── ...
│
├── openai_instantly_agent.py       # OpenAI agent configuration and orchestration
├── README.md                       # Project documentation (this file)
└── ...

Installation

1. Clone the repository:

   git clone https://github.com/your-org/fastmcp_instantlyai.git
   cd fastmcp_instantlyai
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables:

   • INSTANTLY_API_KEY (your Instantly API key)
   • OPENAI_API_KEY (your OpenAI API key)
   • Any other required secrets for S3, etc.

Configuration

• API Keys:
  Store your API keys in environment variables or a .env file.
• FastMCP Settings:
  Configure FastMCP in your main server file to register all tools and connect to Instantly.
• OpenAI Agent:
  Edit openai_instantly_agent.py to set model parameters, tool registration, and agent instructions.

Usage

Campaign Management

• Create a campaign:

  Create a campaign called "Spring Sale" with all available sender mail addresses. Generate a sample sequence about spring offers.
  

• Delete a campaign:

  Delete the campaign called "Spring Sale".
  

• Pause/Resume a campaign:

  Pause the campaign "Spring Sale".
  Resume all paused campaigns.
  

Lead Management

• Add leads to a campaign:

  Add leads alice@example.com, bob@example.com to the "Spring Sale" campaign.
  

• Create and manage lead lists:

  Create a lead list called "eficens" and add kirankumarp@eficens.com, vponnada@eficens.com.
  

• Move leads between campaigns:

  Move leads from "Laptop Procurement" to "Spring Sale".
  

Sender Account Management

• Add a Gmail sender account:

  Create sender email sriharshith05ai@gmail.com with Gmail provider, app password ejdieuisjsppilwq, first name Sriharshith, last name AI.
  

• Delete or update sender accounts:

  Delete sender email sriharshith05ai@gmail.com.
  Update sender email sriharshith05ai@gmail.com with new app password.
  

Sequences & Follow-Ups

• Add follow-up emails:

  Add two follow-up emails to the "Spring Sale" campaign related to spring offers.
  

• Schedule follow-ups for non-responders:

  Send follow-ups only to leads who haven't replied.
  

Attachments & Hyperlinks

• Upload and hyperlink attachments:

  Add the uploaded PDF as a hyperlink labeled "Guide" in the campaign email.
  

Analytics & Reporting

• View campaign analytics:

  Show me the analytics for the "Spring Sale" campaign.
  

• Export leads:

  Export all leads from the "Spring Sale" campaign to CSV.
  

API Endpoints

The project wraps and fixes all major Instantly API endpoints, including:

• /api/v2/campaigns (create, list, delete, update)
• /api/v2/leads (add, move, delete)
• /api/v2/leadlists (create, add leads, delete)
• /api/v2/accounts (sender management)
• /api/v2/subsequences (follow-up sequences)
• /api/v2/s3 (attachments)
• ...and more

All endpoints are accessed via the HTTP client in instantly_mcp_server/client.py, with robust error handling for DELETE, POST, PATCH, and GET requests.

Troubleshooting

• 400 Bad Request Errors:
  Ensure all required fields are provided (especially for sender accounts and campaign deletion).
• OAuth for Gmail:
  If app password fails, check if OAuth is required for your organization.
• Duplicate Leads:
  Use "force add" or "move" prompts to ensure leads are added to lists or campaigns.
• Follow-Up Sequence Visibility:
  Check the "Subsequences" tab in the Instantly UI.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with a clear description of your changes.

License

This project is licensed under the MIT License.

Support

For help or feature requests, open an issue on GitHub or contact your system administrator.

Enjoy automating your Instantly AI campaigns with FastMCP and OpenAI!