ACTION_ID: instantly_add_to_campaign
NAME: Instantly: Add Leads to a Campaign
CATEGORY: Integration
CREDITS: 0

Add a lead to a campaign in Instantly.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their Instantly account
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click Instantly and complete the OAuth flow

If the user has not connected Instantly, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the Instantly connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Where it fits in a workflow
  5. When to use

================================================================================
1. INPUTS
================================================================================

campaign_id (string, required)
  Campaign ID. The id of the campaign you want to add the lead to.
  Must be a valid campaign id from the user's connected Instantly
  workspace — the user picks this from a dropdown of their existing
  campaigns when configuring the action in the UI.

email (email, required)
  Email. The email address of the lead.

first_name (string, optional)
  First Name. The first name of the lead.

last_name (string, optional)
  Last Name. The last name of the lead.

company_name (string, optional)
  Company Name. The company name of the lead.

personalization (string, optional)
  Personalization. Personalization text to merge into the email
  template for this lead.

custom_variables (jsonArray, optional)
  Custom Variables. `[{name, value}]` — the values are merged into
  the Instantly campaign template at send time wherever it references
  `{{custom_variable}}` placeholders. The most common use is passing
  AI-generated personalized email content from upstream `llm_models`
  steps so every lead receives a unique email.
  Each item's `name` must match a `{{custom_variable}}` placeholder
  in the Instantly campaign template.

skip_if_lead_is_in_workspace (boolean, optional)
  Skip if Lead is in Workspace. When `true`, skips the lead if it
  already exists in any campaign in the connected Instantly workspace.

================================================================================
2. OUTPUTS
================================================================================

status (string) — Status. Status/Response of the request (e.g.
"completed").

================================================================================
3. HOW TO CONFIGURE
================================================================================

Resolve the campaign list via Get Action Field Options:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/campaign_id
       (body: {})
       → user's Instantly campaigns. `value` is the campaign ID.

Configure Action body:

{
  "inputs": {
    "campaign_id": "<instantly_campaign_id>",
    "email": "{{input.email}}",
    "first_name": "{{input.first_name}}",
    "last_name": "{{input.last_name}}",
    "company_name": "{{input.company_name}}",
    "custom_variables": [
      { "name": "custom_email_body", "value": "{{llm_models_1.generated_content}}" },
      { "name": "custom_subject",    "value": "{{llm_models_2.generated_content}}" }
    ],
    "skip_if_lead_is_in_workspace": true
  }
}

Field-by-field:
  - campaign_id                   Instantly campaign ID from the
                                  `campaign_id` options call.
  - email                         Lead's email — usually `{{input.email}}`.
  - first_name / last_name /
    company_name                  Lead profile fields. Optional.
  - personalization               Free-form text passed alongside
                                  the lead. Optional.
  - custom_variables              `[{name, value}]` merged into the
                                  campaign template's
                                  `{{custom_variable}}` placeholders at
                                  send time. The primary slot for
                                  AI-generated per-lead content from
                                  upstream `llm_models` steps.
  - skip_if_lead_is_in_workspace  `true` to skip leads already in any
                                  campaign in this Instantly workspace.

================================================================================
4. WHERE IT FITS IN A WORKFLOW
================================================================================

UPSTREAM — how leads reach this action
  Typically a terminal step at the end of an AI-personalization chain.
  The exact upstream actions depend on the user's workflow, but the
  minimum useful pattern is:

    enrich_person_linkedin_profile (gather profile context per lead)
      -> llm_models (one or more: generate personalized email body,
                     subject line, opening line, etc. — each output
                     becomes one entry in custom_variables)
      -> THIS ACTION

THIS ACTION
  Adds the lead to the selected Instantly campaign and passes the
  AI-generated personalized content via custom_variables so
  Instantly can merge it into the campaign's email template at send
  time. Every lead in the campaign receives a uniquely personalized
  email.

  This is the terminal action — when a workflow's purpose is to send
  via an Instantly campaign, this is the last step.

================================================================================
5. WHEN TO USE
================================================================================

- Send AI-personalized cold email at scale. Generate per-lead email
  body / subject / opening line with llm_models upstream, push the
  output through custom_variables so every lead receives a
  unique, personalized email from an Instantly campaign. This is the
  primary reason Floqer is used with Instantly.
- Enroll enriched, email-verified outbound leads into an Instantly cold
  email sequence at the end of a discovery / enrichment workflow.
- Push prospects from a CSV (or any sourced list) into an Instantly
  campaign for nurture.

================================================================================

This file is maintained manually. Last updated: 2026-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt