Instantly

Learn how to use Instantly with Composio

Overview

SLUG: INSTANTLY

Description

Instantly is a platform designed to streamline cold email outreach by automating campaigns, managing leads, and enhancing email deliverability.

Authentication Details

generic_api_key
stringRequired

Connecting to Instantly

Create an auth config

Use the dashboard to create an auth config for the Instantly toolkit. This allows you to connect multiple Instantly accounts to Composio for agents to use.

1

Select App

Navigate to Instantly.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Instantly Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4instantly_auth_config_id = "ac_YOUR_INSTANTLY_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Instantly for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, instantly_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Instantly toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["INSTANTLY"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Check Email Verification Status

Description

Tool to check status of an email verification job. Use after submitting a verification request to retrieve the current status of a specific email address.

Action Parameters

email
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Count Unread Emails

Description

Tool to retrieve the count of unread emails. Use when you need to know how many unread messages are in your inbox before sending new emails.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create AI Enrichment

Description

Tool to create an AI enrichment job for a campaign or lead list. Use when you need to enrich a resource with AI-driven insights.

Action Parameters

auto_update
boolean
input_columns
array
limit
integer
model_version
stringRequired
output_column
stringRequired
overwrite
boolean
prompt
string
resource_id
stringRequired
resource_type
integerRequired
show_state
boolean
skip_leads_without_email
boolean
status
integer
template_id
integer
use_instantly_account
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create API Key

Description

Tool to create a new API key. Use when you need to generate credentials for programmatic access to the Instantly API.

Action Parameters

name
stringRequired
scopes
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Campaign

Description

Tool to create a new campaign. Use when you have campaign details ready and want to launch.

Action Parameters

allow_risky_contacts
boolean
auto_variant_select
object
bcc_list
array
campaign_schedule
objectRequired
cc_list
array
daily_limit
integer
daily_max_leads
integer
disable_bounce_protect
boolean
email_gap
number
email_list
array
email_tag_list
array
first_email_text_only
boolean
insert_unsubscribe_header
boolean
is_evergreen
boolean
link_tracking
boolean
match_lead_esp
boolean
name
stringRequired
open_tracking
boolean
owned_by
string
pl_value
number
prioritize_new_leads
boolean
provider_routing_rules
array
random_wait_max
number
sequences
array
stop_for_company
boolean
stop_on_auto_reply
boolean
stop_on_reply
boolean
text_only
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Inbox Placement Test

Description

Tool to create an inbox placement test. Use when you need to measure deliverability across providers with your prepared email and recipient list.

Action Parameters

automations
array
campaign_id
string
delivery_mode
integer
description
string
email_body
stringRequired
email_subject
stringRequired
emails
arrayRequired
name
stringRequired
not_sending_status
string
recipients_labels
array
run_immediately
boolean
schedule
object
sending_method
integerRequired
status
integer
tags
array
test_code
string
text_only
boolean
timestamp_next_run
string
type
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Lead

Description

Tool to create a new lead. Use when you need to add an individual lead to a campaign.

Action Parameters

campaign
string
company_name
string
email
string
first_name
string
last_name
string
lt_interest_status
integer
personalization
string
phone
string
website
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Lead List

Description

Tool to create a new lead list. Use when you need to organize leads into a dedicated list before importing them into campaigns.

Action Parameters

has_enrichment_task
boolean
name
stringRequired
owned_by
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Webhook

Description

Tool to create a new webhook endpoint. Use when you need to receive Instantly event notifications via HTTP callbacks.

Action Parameters

campaign
string
custom_interest_value
integer
event_type
string
target_hook_url
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete API Key

Description

Tool to delete an API key. Use when you need to remove a specific API key by its ID after confirming its existence.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Campaign

Description

Tool to delete a campaign. Use when you need to remove a specific campaign by ID.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Lead

Description

Tool to delete a lead by its ID. Use when you need to remove a specific lead after confirming its existence.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Lead List

Description

Tool to delete a lead list by ID. Use when you need to remove a specific lead list after confirming its existence.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Webhook

Description

Tool to delete a webhook. Use when you need to remove a specific webhook by its UUID.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Disable Account Warmup

Description

Tool to disable the warm-up process for email accounts. Use when you need to stop warmup for specific or all accounts before sending critical campaigns.

Action Parameters

emails
array
excluded_emails
array
include_all_emails
boolean

Action Response

created_at
stringRequired
data
objectRequired
entity_id
string
entity_type
stringRequired
error
string
id
stringRequired
progress
integerRequired
status
stringRequired
successful
booleanRequired
type
stringRequired
updated_at
stringRequired
user_id
string
workspace_id
stringRequired

Tool Name: Enable Account Warmup

Description

Tool to enable the warm-up process for email accounts. Use when you want to start warming up one or more accounts to improve deliverability.

Action Parameters

emails
array
excluded_emails
array
include_all_emails
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Campaign

Description

Tool to retrieve campaign details. Use when you need full campaign configuration for a given campaign ID.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Campaign Analytics

Description

Tool to retrieve analytics for campaigns. Use when you need performance metrics for one or multiple campaigns.

Action Parameters

end_date
string
exclude_total_leads_count
boolean
id
string
ids
array
start_date
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Daily Campaign Analytics

Description

Tool to retrieve daily analytics for a campaign. Use when you need per-day performance metrics for campaigns.

Action Parameters

campaign_id
string
campaign_status
integer
end_date
string
start_date
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Email Service Provider Options

Description

Tool to retrieve email service provider options for inbox placement tests. Use when you need valid recipients_labels options.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Inbox Placement Test

Description

Tool to retrieve inbox placement test results. Use when you need details for a specific inbox placement test by ID.

Action Parameters

id
stringRequired
with_metadata
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Lead

Description

Tool to retrieve details of a specific lead by its ID. Use when you have the lead UUID and need full lead metadata.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Lead List

Description

Tool to retrieve details of a specific lead list by its ID. Use when you have the lead list UUID and need list metadata.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Lead List Verification Stats

Description

Tool to retrieve verification statistics for a lead list. Use when you need summary counts by verification status for a specific lead list.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Webhook

Description

Tool to retrieve details of a specific webhook subscription. Use when you have the webhook ID and need full webhook configuration.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Webhook Event

Description

Tool to retrieve details of a specific webhook event. Use when you need to inspect a particular webhook event by its ID.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Email Accounts

Description

Tool to list all email accounts for the authenticated user. Use after obtaining auth credentials to retrieve available accounts.

Action Parameters

limit
integer
provider_code
integer
search
string
starting_after
string
status
integer
tag_ids
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List API Keys

Description

Tool to list all API keys. Use when you need to retrieve your API keys with optional pagination after authentication.

Action Parameters

limit
integer
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Campaigns

Description

Tool to list all campaigns. Use when you need to fetch your campaigns list with optional filters and pagination.

Action Parameters

limit
integer
search
string
starting_after
string
tag_ids
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Custom Tags

Description

Tool to list custom tags. Use when you need to retrieve custom tags with optional pagination and filtering.

Action Parameters

limit
integer
resource_ids
string
search
string
starting_after
string
tag_ids
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List DFY Email Account Orders

Description

Tool to list DFY email account orders. Use when you need to fetch your DFY email account orders with pagination.

Action Parameters

limit
integer
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Emails

Description

Tool to list emails. Use when you need to retrieve emails with optional filters and pagination.

Action Parameters

assigned_to
string
campaign_id
string
company_domain
string
eaccount
string
email_type
string
has_reminder
boolean
i_status
integer
is_unread
boolean
lead
string
limit
integer
marked_as_done
boolean
mode
string
preview_only
boolean
scheduled_only
boolean
search
string
sort_order
string
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Inbox Placement Blacklist & SpamAssassin Reports

Description

Tool to list inbox placement blacklist & SpamAssassin reports. Use when you need to retrieve spam and blacklist analytics after running an inbox placement test.

Action Parameters

date_from
string
date_to
string
limit
integer
skip_blacklist_report
boolean
skip_spam_assassin_report
boolean
starting_after
string
test_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Inbox Placement Tests

Description

Tool to list inbox placement tests. Use when you need a paginated overview of tests with optional filtering and sort order.

Action Parameters

limit
integer
search
string
sort_order
string
starting_after
string
status
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Lead Lists

Description

Tool to list all lead lists. Use when you need to fetch the lead lists with optional filters and pagination.

Action Parameters

has_enrichment_task
boolean
limit
integer
search
string
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Leads

Description

Tool to list leads. Use when you need to retrieve leads with optional filters like search, status filters, and pagination.

Action Parameters

campaign
string
contacts
array
excluded_ids
array
filter
string
ids
array
in_campaign
boolean
in_list
boolean
limit
integer
list_id
string
queries
array
search
string
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Email Threads

Description

Tool to list email threads. Use when fetching threads with optional pagination and unread-only filtering. Note: Instantly's public API does not expose a dedicated GET /emails/threads endpoint. Threads can be derived by grouping emails (GET /emails) by their `thread_id`. This action implements that logic by querying /emails and aggregating into threads.

Action Parameters

is_unread
boolean
limit
integer
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Webhook Events

Description

Tool to list webhook events. Use when you need to view received webhook events with optional pagination and filters.

Action Parameters

from_date
string
limit
integer
search
string
starting_after
string
success
boolean
to_date
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Webhooks

Description

Tool to list configured webhooks. Use when you need to retrieve your webhook configurations with optional filters and pagination.

Action Parameters

campaign
string
event_type
string
limit
integer
starting_after
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Mark Thread As Read

Description

Tool to mark all emails in a specific thread as read. Use when you want to update the read status of an email thread after processing.

Action Parameters

thread_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Merge Leads

Description

Tool to merge multiple leads into a single lead. Use after confirming both source and destination lead IDs exist.

Action Parameters

destination_lead_id
stringRequired
lead_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search Campaigns by Lead Email

Description

Tool to search campaigns by a lead's email address. Use when you need to find campaigns containing a specific lead by their email.

Action Parameters

search
stringRequired
sort_column
string
sort_order
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Campaign

Description

Tool to update details of a campaign. Use when you need to modify campaign settings after verifying its ID.

Action Parameters

allow_risky_contacts
boolean
auto_variant_select
object
bcc_list
array
campaign_schedule
object
cc_list
array
daily_limit
integer
daily_max_leads
integer
disable_bounce_protect
boolean
email_gap
integer
email_list
array
email_tag_list
array
first_email_text_only
boolean
id
stringRequired
insert_unsubscribe_header
boolean
is_evergreen
boolean
link_tracking
boolean
match_lead_esp
boolean
name
string
open_tracking
boolean
owned_by
string
pl_value
number
prioritize_new_leads
boolean
provider_routing_rules
array
random_wait_max
integer
sequences
array
stop_for_company
boolean
stop_on_auto_reply
boolean
stop_on_reply
boolean
text_only
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Lead

Description

Tool to update a lead's details. Use when you need to modify fields of an existing lead after identifying its ID.

Action Parameters

company_name
string
first_name
string
id
stringRequired
last_name
string
lt_interest_status
integer
personalization
string
phone
string
website
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Lead Interest Status

Description

Tool to update a lead's interest status. Use when you need to set or reset a lead’s interest status for follow-up actions.

Action Parameters

ai_interest_value
integer
campaign_id
string
disable_auto_interest
boolean
interest_value
integerRequired
lead_email
stringRequired
list_id
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Lead List

Description

Tool to update details of a specific lead list by its ID. Use after verifying the list ID exists.

Action Parameters

has_enrichment_task
boolean
id
stringRequired
name
string
owned_by
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Verify Email

Description

Tool to initiate email verification. Use when you need to verify an email's deliverability before sending emails.

Action Parameters

email
stringRequired
webhook_url
string

Action Response

data
objectRequired
error
string
successful
booleanRequired