Campaign Creation Guide

​

Overview

​

Quick Start

1. Start steps with the first action that should happen.
2. Add each next action in the exact order it should run.
3. Use condition to branch on lead data.
4. Use linkedin_connection to send a connection request and then branch on acceptance.
5. Put shared continuation steps after the branch instead of duplicating them inside both sides.

​

Rules

• Build the campaign as an ordered steps array from first action to last action.
• Use condition and linkedin_connection when you need branches.
• Put shared follow-up work after the branching step instead of duplicating the same steps in both branches.
• Use { "type": "end" } only when that branch should stop completely.
• waitForAcceptance.unit must always be days.
• waitForAcceptance.value must be an integer greater than or equal to 1.
• Validation errors return full paths such as steps[0].onTrue[1].subject.

​

Step Types

email.subject is required for the first email on every live path; follow-up emails in the same thread can omit it. email.thread picks Reply or New thread for the step; see Email threading. linkedin_connection.waitForAcceptance is optional — omit it (and the branches) for a fire-and-forget connection request that just sends the invite and continues with whatever follows. add_to_another_campaign.campaignId must reference a campaign owned by the same client as the API key.

​

Email threading (Reply or New thread)

• "reply" sends the email in the thread of the previous email, under its subject. The step needs no subject; if it has one, that subject is only used for a contact who reaches the step without an earlier email.
• "new_thread" starts a separate thread under the step’s own subject, which is required unless the step uses aiMessageId.
• Omitted: a follow-up without subject replies, and one with subject is sent under that subject. For aiMessageId follow-ups that means the generated subject, so set thread: "reply" to keep them in the thread.

{
  "type": "email",
  "content": "Just bumping this up in case it got buried.",
  "thread": "reply",
  "delay": { "value": 3, "unit": "days" }
}

​

AI messages on steps (aiMessageId)

• Reuse a public prompt-library entry: list them with GET /v1/prompt-library/ai-messages and pass the entry id.
• Reuse a workspace AI message: list them with GET /v1/ai-variables/ai-messages.
• Create a new AI message with full control over prompt, toneId, model, outputLength, and splitMessages: POST /v1/ai-variables/ai-messages (tones via GET /v1/ai-variables/ai-message-tones), then reference the returned id. model must be one of the ids the app’s model picker offers; send enginy-default unless a specific model is needed.

• The AI message channel must match the step type: EMAIL, LINKEDIN, LINKEDIN_INMAIL, or LINKEDIN_CONNECTION.
• aiMessageId is mutually exclusive with manual content, subject, and attachment fields — the AI message replaces the step’s message entirely.
• Each step receives its own copy of the AI message; campaign reads return the copy’s id.
• Requires the AI variable split to be enabled for the workspace.

{
  "name": "AI-personalized outreach",
  "identityId": 323,
  "steps": [
    { "type": "email", "aiMessageId": "4f8a7c2e-1b6d-4e5f-9a3c-8d2b7f6e5a41" },
    {
      "type": "linkedin_message",
      "aiMessageId": "9c1d3e5f-7a8b-4c2d-b6e4-0f9a8b7c6d5e",
      "delay": { "value": 2, "unit": "days" }
    }
  ]
}

​

Personalization placeholders

​

linkedin_message_bundle

​

linkedin_voice_message

​

Branching Step Types

​

Condition Types

​

Timed Conditions (waitFor)

{
  "type": "email_opened",
  "waitFor": { "value": 3, "unit": "days" }
}

• waitFor.value must be a positive number.
• waitFor.unit must be one of seconds, minutes, hours, or days.
• email_opened and email_clicked must be placed immediately after an email step.
• linkedin_message_viewed must be placed immediately after a LinkedIn message step (linkedin_message, linkedin_message_bundle, linkedin_voice_message, or linkedin_inmail).
• task_completed must be placed immediately after a task step.
• connection_accepted checks whether the lead has accepted a LinkedIn connection request that was sent earlier in the campaign. Use this when you want to fan out work after the request without inlining the acceptance check on the linkedin_connection step itself.

​

Validation Checklist

• steps must contain at least one step.
• Every branch array you provide must contain at least one step.
• Use { "type": "end" } if a branch should stop explicitly.
• waitForAcceptance.unit must always be days.
• waitForAcceptance.value must be a whole integer greater than or equal to 1.
• If GET /v1/tasks/owners returns owners, every task step must include a valid ownerId.
• Every linkedin_voice_message step must reference a voiceId returned by GET /v1/voices.
• Every aiMessageId must reference a workspace AI message or a prompt-library entry whose channel matches the step type, and must not be combined with manual content/subject.
• Placeholders in manual content must reference fields returned by GET /v1/contacts/fields (unknown placeholders are rejected).
• The sequence must not loop: a step cannot connect back to an earlier step. A cyclic campaign is rejected instead of created (it could be stored before, but never ran — the sending engine requires an acyclic sequence).

​

Task Owners

• If that endpoint returns owners, every task step must include a valid ownerId.
• If no owners are returned, ownerId can be omitted.

​

Senders

• identityId sets a single sender. To send from several identities, pass identityIds with the primary sender first: the campaign spreads its contacts across them. When both fields are sent, identityId must equal identityIds[0].
• More than one sender requires the Multi-identity campaigns beta on the workspace (a workspace admin enables it in Settings > Beta features). Without it the request fails with 400 and details.code: "MULTI_IDENTITY_CAMPAIGNS_NOT_ENABLED"; a single sender always works.
• Every identity must belong to the workspace, must not be deleted, and must be one you may send as. Otherwise the request fails with 400 (404 when cloning) and names the identities that are not usable.
• allowedEmails restricts the mailboxes of a single sender, so it cannot be combined with more than one sender identity.
• Campaign reads (GET /v1/campaign/{campaignId}) return identityIds and senderIdentities with the senders that can still send, primary first; identityId and senderIdentity are the primary.

{
  "name": "Team LinkedIn outreach",
  "identityIds": [323, 324, 325],
  "steps": [
    {
      "type": "linkedin_connection",
      "waitForAcceptance": { "value": 5, "unit": "days" },
      "onAccepted": [{ "type": "linkedin_message", "content": "Thanks for connecting, {firstName}." }],
      "onNotAccepted": [{ "type": "end" }]
    }
  ]
}

​

Voices

• source: "system" voices are available to every client.
• source: "identity" voices are cloned from one of the client’s identities.
• A voiceId that is not in the list will fail validation when creating or validating the campaign.

​

Reading saved campaign content

​

Updating a Draft Campaign

• Every field is optional; provide only what you want to change.
• When steps is provided it replaces the whole stored sequence. Fetch the current steps with GET /v1/campaign/{campaignId}, modify them, and resubmit. The read-only stepId, connectionId, nextConnectionId, and advanced fields are accepted and ignored. Unchanged text retains its saved rich documents; changed email HTML regenerates editor documents with its links and formatting.
• Reply follow-up emails may keep the subject: "" that GET returns; it means “reply in the existing thread”.
• identityIds replaces the whole sender set (primary first), and contacts already added to the draft that have not been contacted yet are re-distributed across the new senders. A different identityId sent on its own replaces the set with that one sender. Echoing back the current senders — or only the current primary as identityId — leaves them unchanged. Changing to more than one sender (or to none) clears allowedEmails.
• Keep the thread value GET returns on email steps. A step sent without it falls back to the omitted-thread behaviour described in Email threading.
• Campaigns that are not in DRAFT status return 409 Conflict: clone them (POST /v1/campaign/{campaignId}/clone) and edit the clone instead. A draft that already has send history from a previous launch also returns 409 for step replacement.

​

Stopping a Campaign

​

Related Endpoints

• POST /v1/campaigns creates the draft campaign.
• PATCH /v1/campaign/{campaignId} updates a draft campaign’s settings and/or steps.
• GET /v1/campaigns lists campaigns after creation.
• GET /v1/tasks/owners returns the valid task owners for task steps.
• GET /v1/voices returns the valid voices for linkedin_voice_message steps.
• POST /v1/add-contact-to-campaign adds one contact to an existing campaign.
• POST /v1/add-contact-group-to-campaign adds every contact in a contact group to an existing campaign.

​

Adding Contacts After Creation

• POST /v1/add-contact-to-campaign is for one contact at a time.
• POST /v1/add-contact-group-to-campaign is for an entire contact group and returns counts for newly added, reactivated, already-present, and skipped contacts.

​

Example: Add a Contact Group to a Campaign

{
  "campaignId": 456,
  "contactGroupId": 123
}

​

Example: Condition First

{
  "name": "Email or fallback task",
  "identityId": 323,
  "steps": [
    {
      "type": "condition",
      "condition": {
        "type": "has_professional_email"
      },
      "onTrue": [
        {
          "type": "email",
          "subject": "Great to connect",
          "content": "Sharing a quick overview."
        }
      ],
      "onFalse": [
        {
          "type": "task",
          "taskType": "TODO",
          "title": "Find email first",
          "ownerId": "owner-1"
        }
      ]
    }
  ]
}

​

Example: LinkedIn Acceptance Branch

{
  "name": "LinkedIn acceptance flow",
  "identityId": 323,
  "steps": [
    {
      "type": "linkedin_connection",
      "delay": {
        "value": 1,
        "unit": "days"
      },
      "waitForAcceptance": {
        "value": 5,
        "unit": "days"
      },
      "onAccepted": [
        {
          "type": "linkedin_message",
          "content": "Thanks for accepting.",
          "delay": {
            "value": 2,
            "unit": "hours"
          }
        }
      ],
      "onNotAccepted": [
        {
          "type": "task",
          "taskType": "TODO",
          "title": "Review no-response path",
          "ownerId": "owner-1"
        }
      ]
    },
    {
      "type": "email",
      "subject": "Following up",
      "content": "Continuing after the LinkedIn decision.",
      "delay": {
        "value": 1,
        "unit": "days"
      }
    }
  ]
}

​

Example: LinkedIn Message Bundle

{
  "name": "LinkedIn bundle intro",
  "identityId": 323,
  "steps": [
    {
      "type": "linkedin_message_bundle",
      "delay": {
        "value": 2,
        "unit": "hours"
      },
      "messages": [
        {
          "content": "Hi {firstName}, great to connect! Sending along a short intro."
        },
        {
          "content": "Here is the deck we discussed.",
          "attachment": "https://cdn.example.com/deck.pdf",
          "attachmentName": "intro-deck.pdf",
          "contentType": "FILE"
        }
      ]
    }
  ]
}

​

Example: Branch on Email Click

{
  "name": "Click-gated follow-up",
  "identityId": 323,
  "steps": [
    {
      "type": "email",
      "subject": "Thought you might find this useful",
      "content": "Here is the landing page with the details."
    },
    {
      "type": "condition",
      "condition": {
        "type": "email_clicked",
        "waitFor": {
          "value": 3,
          "unit": "days"
        }
      },
      "onTrue": [
        {
          "type": "linkedin_message",
          "content": "Saw you checked out the page. Happy to jump on a quick call."
        }
      ],
      "onFalse": [
        {
          "type": "email",
          "subject": "Still interested?",
          "content": "Quick bump in case this got buried."
        }
      ]
    }
  ]
}

​

Example: Task Completion Branch

{
  "name": "Task completion fallback",
  "identityId": 323,
  "steps": [
    {
      "type": "task",
      "taskType": "CALL",
      "title": "Initial discovery call",
      "ownerId": "owner-1"
    },
    {
      "type": "condition",
      "condition": {
        "type": "task_completed",
        "waitFor": {
          "value": 5,
          "unit": "days"
        }
      },
      "onTrue": [
        {
          "type": "email",
          "subject": "Great talking to you",
          "content": "Following up with a quick summary of what we discussed."
        }
      ],
      "onFalse": [
        {
          "type": "linkedin_message",
          "content": "Hey {firstName}, still keen to chat whenever works for you."
        }
      ]
    }
  ]
}

​

Example: Explicitly Stop One Branch

{
  "name": "Accepted-or-stop flow",
  "identityId": 323,
  "steps": [
    {
      "type": "linkedin_connection",
      "content": "Would love to connect and share a few ideas.",
      "waitForAcceptance": {
        "value": 3,
        "unit": "days"
      },
      "onAccepted": [
        {
          "type": "linkedin_message",
          "content": "Thanks for accepting. Sharing a quick follow-up.",
          "delay": {
            "value": 4,
            "unit": "hours"
          }
        }
      ],
      "onNotAccepted": [
        {
          "type": "end"
        }
      ]
    },
    {
      "type": "email",
      "subject": "Resources after connecting",
      "content": "Continuing only for contacts who accepted the connection request.",
      "delay": {
        "value": 1,
        "unit": "days"
      }
    }
  ]
}

​

Working days required to launch or resume

{
  "status": "error",
  "code": "IDENTITY_WORKING_HOURS_EMPTY",
  "message": "Select at least one working day for this identity.",
  "identityId": 123,
  "identityName": "Sender"
}