ComposioHQ/Instantly-Automation

Instantly Automation

Automate your cold email outreach with Instantly -- create and manage campaigns with multi-step sequences, configure sending schedules, import leads in bulk, manage sending accounts, and track campaign performance -- all through natural language commands.

Toolkit docs: composio.dev/toolkits/instantly

---

Setup

1. Add the Composio MCP server to your client configuration:

   https://rube.app/mcp
   

2. Connect your Instantly account when prompted (API key authentication).
3. Start issuing natural language commands to manage your outreach campaigns.

---

Core Workflows

1. List Sending Accounts

Retrieve all email accounts configured in your Instantly workspace, with filtering by status and provider.

Tool: INSTANTLY_LIST_ACCOUNTS

Example prompt:

"Show all active sending accounts in my Instantly workspace"

Key parameters:

• status -- Filter by status: 1 (Active), 2 (Paused), -1 (Connection Error), -2 (Soft Bounce Error), -3 (Sending Error)
• provider_code -- Filter by provider: 1 (Custom IMAP/SMTP), 2 (Google), 3 (Microsoft), 4 (AWS)
• search -- Search by email substring or domain
• limit -- Max items (1-100)
• starting_after -- Pagination cursor from previous response
• tag_ids -- Comma-separated tag UUIDs

---

2. Create a Campaign

Launch a new outreach campaign with scheduling, email sequences, A/B testing variants, and sending configuration.

Tool: INSTANTLY_CREATE_CAMPAIGN

Example prompt:

"Create an Instantly campaign called 'Q1 Outreach' that sends Monday-Friday 9am-5pm Central time with a 3-step email sequence"

Key parameters:

• name (required) -- Campaign name
• campaign_schedule (required) -- Schedule configuration:
  • schedules (required) -- Array of schedule objects, each with:
    • name -- Schedule name
    • timing -- {from: "09:00", to: "17:00"} (HH:mm format)
    • days -- Map of day index strings "0" (Sun) to "6" (Sat) to booleans
    • timezone -- Supported values include "America/Chicago", "America/Detroit", "America/Boise", "America/Anchorage"
  • start_date / end_date -- ISO 8601 dates
• email_list -- Array of sending account email addresses (must be pre-configured accounts; use INSTANTLY_LIST_ACCOUNTS to discover valid addresses)
• sequences -- Array (only first element used) containing:
  • steps -- Array of step objects with:
    • type -- Must be "email"
    • delay -- Days before NEXT email (integer, min 0)
    • variants -- Array of {subject, body} objects for A/B testing
• daily_limit -- Daily sending cap
• email_gap -- Minutes between emails
• stop_on_reply -- Stop campaign when lead replies (boolean)
• stop_on_auto_reply -- Stop on auto-replies (boolean)
• open_tracking / link_tracking -- Enable tracking (booleans)

Timezone notes:

• Verified working: "America/Chicago" (Central), "America/Detroit" (Eastern), "America/Boise" (Mountain)
• Auto-mapped: "America/New_York" maps to "America/Detroit", "America/Denver" maps to "America/Boise"
• NOT supported: "America/Los_Angeles", "US/Pacific" -- use "America/Anchorage" or "America/Dawson" as alternatives

---

3. Update Campaign Settings

Modify an existing campaign's schedule, sending limits, sequences, or tracking settings.

Tool: INSTANTLY_UPDATE_CAMPAIGN

Example prompt:

"Update my Instantly campaign to increase the daily limit to 100 and enable open tracking"

Key parameters:

• id (required) -- Campaign UUID
• Any combination of: name, campaign_schedule, email_list, sequences, daily_limit, email_gap, stop_on_reply, open_tracking, link_tracking, etc.
• Set any parameter to null to unset it

---

4. Manage Lead Lists and Bulk Import

Create dedicated lead lists and import prospects in bulk for campaign targeting.

Tools: INSTANTLY_CREATE_LEAD_LIST, INSTANTLY_ADD_LEADS_BULK

Example prompt:

"Create a lead list called 'Q1 Prospects' and add 50 leads to my Instantly campaign"

Key parameters for creating lead lists:

• List name and configuration

Key parameters for bulk lead import:

• Campaign or list ID to import into
• Array of lead objects with email and metadata
• Duplicate handling options
• Lead verification settings

---

5. Review Campaign Details

Retrieve full campaign configuration to verify settings, inspect sequences, or prepare for updates.

Tool: INSTANTLY_GET_CAMPAIGN

Example prompt:

"Show me the full details of my Instantly campaign"

Key parameters:

• id (required) -- Campaign UUID

---

6. List All Campaigns

Enumerate all campaigns in your workspace with optional filters and pagination.

Tool: INSTANTLY_LIST_CAMPAIGNS

Example prompt:

"List all my Instantly campaigns"

Key parameters:

• Optional filters and pagination parameters

---

Known Pitfalls

• Timezone support is limited: The Instantly API accepts a restricted set of timezone strings. Pacific Time ("America/Los_Angeles") is NOT supported. Use "America/Anchorage" (UTC-9/UTC-8) or "America/Dawson" (UTC-7 year-round) as alternatives.
• Invalid schedule payloads cause 400 errors: A malformed campaign_schedule (missing days, from, to, or schedules) triggers HTTP 400. Repeated 400s indicate payload issues, not transient failures.
• Sequences must be complete: Each sequence step requires a valid type ("email"), delay, and at least one variant with both subject and body. Incomplete variants block campaign creation.
• Only first sequence element is used: The API only processes sequences[0]. Additional sequences are ignored.
• email_list must reference existing accounts: The email_list field requires email addresses of pre-configured sending accounts in your Instantly workspace, not arbitrary recipient addresses. Always use INSTANTLY_LIST_ACCOUNTS to discover valid sending addresses.
• 401 scope errors on campaign creation: Campaign creation can fail with "Invalid scope. Required: campaigns:create". Update your API key permissions before retrying writes.
• Read-back fields may differ: Field names in INSTANTLY_GET_CAMPAIGN responses may differ from create payloads (e.g., timing.from_ vs timing.from). Parse defensively.

---

Quick Reference

Action	Tool Slug	Required Params
List sending accounts	INSTANTLY_LIST_ACCOUNTS	None (optional filters)
Create campaign	INSTANTLY_CREATE_CAMPAIGN	name, campaign_schedule
Update campaign	INSTANTLY_UPDATE_CAMPAIGN	id
Get campaign details	INSTANTLY_GET_CAMPAIGN	id
List campaigns	INSTANTLY_LIST_CAMPAIGNS	None (optional filters)
Create lead list	INSTANTLY_CREATE_LEAD_LIST	List name
Bulk import leads	INSTANTLY_ADD_LEADS_BULK	Campaign/list ID, leads

---

Powered by Composio