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!