get-some-leads

Create and manage Instantly.ai email campaigns via API. Use when the user wants to create a cold email campaign, add leads to Instantly, configure email sequences with variables, set up A/B testing variants, activate a campaign, or manage outbound email automation. Triggers on any mention of Instantly, cold email campaign, outbound sequence, email outreach, lead import, or campaign activation.

Instantly Campaign Builder

Build and manage Instantly.ai cold email campaigns via API v2.

Auth

All requests require:

text

Authorization: Bearer {INSTANTLY_API_KEY}
Content-Type: application/json
Base URL: https://api.instantly.ai

Workflow — Follow this order

Step 1: Create the campaign

POST /api/v2/campaigns

Required fields:

• name — campaign name
• email_list — array of sender email addresses
• sequences — message steps (see Step 2)

Optional but recommended:

• daily_limit — max emails per day
• daily_max_leads — max new leads contacted per day
• email_gap — seconds between sends
• open_tracking, link_tracking — boolean
• stop_on_reply, stop_on_auto_reply, stop_for_company — boolean
• text_only, first_email_text_only — boolean
• campaign_schedule — object with start_date, end_date, schedules (times/days/timezone)

Step 2: Configure sequences (messages)

The sequences field is an array but only the first element is used. Put all steps in one item.

Each step has:

• type: always "email"
• delay: number (wait before this step)
• delay_unit: "minutes", "hours", or "days"
• variants: array of message variants (A/B testing)

Each variant has:

• subject: email subject line
• body: email body (HTML or plain text)
• v_disabled: boolean (set true to disable a variant)

Variable syntax in subject and body: {{variableName}}

Core variables: {{firstName}}, {{lastName}}, {{companyName}}, {{email}}, {{phone}}, {{website}}

Custom variables: any name, e.g. {{city}}, {{offer}}, {{icebreaker}}

Example 3-step ARA sequence:

json

{
  "sequences": [
    {
      "steps": [
        {
          "type": "email",
          "delay": 0,
          "delay_unit": "days",
          "variants": [
            {
              "subject": "{{firstName}}, {{offer}}",
              "body": "Bonjour {{firstName}},\n\n{{icebreaker}}\n\nNous proposons {{offer}} pour les entreprises à {{city}}.\n\nCordialement"
            }
          ]
        },
        {
          "type": "email",
          "delay": 3,
          "delay_unit": "days",
          "variants": [
            {
              "subject": "Re: {{firstName}}, suite à mon message",
              "body": "{{firstName}},\n\nJe me permets de relancer..."
            }
          ]
        },
        {
          "type": "email",
          "delay": 5,
          "delay_unit": "days",
          "variants": [
            {
              "subject": "Dernière relance {{firstName}}",
              "body": "{{firstName}},\n\nDernier message de ma part..."
            }
          ]
        }
      ]
    }
  ]
}

Step 3: Declare campaign variables

POST /api/v2/campaigns/{campaign_id}/variables

json

{
  "variables": ["firstName", "companyName", "city", "offer", "icebreaker"]
}

Declare every custom variable name used in your sequences here.

Step 4: Add leads

Single lead: POST /api/v2/leads

json

{
  "email": "[e-mail]",
  "first_name": "Jean",
  "last_name": "Dupont",
  "company_name": "Acme SAS",
  "campaign": "campaign-uuid",
  "custom_variables": {
    "city": "Paris",
    "offer": "audit IA gratuit",
    "icebreaker": "J'ai vu votre post LinkedIn sur la transformation digitale"
  }
}

Bulk (max 1000 per request): POST /api/v2/leads/add

json

{
  "campaign_id": "campaign-uuid",
  "leads": [
    {
      "email": "[e-mail]",
      "first_name": "Jean",
      "last_name": "Dupont",
      "company_name": "Acme SAS",
      "custom_variables": { "city": "Paris", "offer": "audit IA gratuit" }
    },
    {
      "email": "[e-mail]",
      "first_name": "Marie",
      "last_name": "Martin",
      "company_name": "Beta Corp",
      "custom_variables": { "city": "Lyon", "offer": "démo chatbot" }
    }
  ]
}

Notes:

• Use campaign_id OR list_id, not both
• If campaign is provided on single lead, email is required
• Deduplication flags: skip_if_in_campaign, skip_if_in_workspace, skip_if_in_list

Step 5: Activate the campaign

POST /api/v2/campaigns/{campaign_id}/activate

Only activate after leads are added and sequences are configured.

Modifying an existing campaign

PATCH /api/v2/campaigns/{campaign_id}

Same sequences structure as creation. Use this to update messages after campaign is created.

A/B Testing

Add multiple variants per step:

json

{
  "type": "email",
  "delay": 0,
  "delay_unit": "days",
  "variants": [
    {
      "subject": "Version A — {{firstName}}",
      "body": "Approche directe...",
      "v_disabled": false
    },
    {
      "subject": "Version B — {{firstName}}",
      "body": "Approche soft...",
      "v_disabled": false
    }
  ]
}

Required API Scopes

• Leads: leads:create, leads:all, all:create, or all:all
• Campaigns: campaigns:create, campaigns:all, all:create, or all:all
• Campaign update: campaigns:update, campaigns:all, all:update, or all:all

Checklist before activation

1. Campaign created with sequences and variables in subject/body
2. Variables declared via /campaigns/{id}/variables
3. Leads added with matching custom_variables
4. Sender emails configured and warmed up
5. Schedule set if needed
6. Campaign activated via /campaigns/{id}/activate