Campaign Creation Guide

Overview

Use POST /v1/campaigns to create a draft campaign from the public steps format. This endpoint is designed for external integrations. You send a single ordered steps array and Enginy compiles it into the internal campaign graph.

Quick Start

Start steps with the first action that should happen.
Add each next action in the exact order it should run.
Use condition to branch on lead data.
Use linkedin_connection to send a connection request and then branch on acceptance.
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

Step type	Required fields	Optional fields
`email`	`content` or `aiMessageId`	`subject`, `delay`
`linkedin_message`	`content`, `attachment`, or `aiMessageId`	`attachment`, `attachmentName`, `contentType`, `delay`
`linkedin_message_bundle`	`messages`	`delay`
`linkedin_voice_message`	`content`+`voiceId` or `attachment`	`voiceSettings`, `delay`
`linkedin_inmail`	`subject`+`content` or `aiMessageId`	`delay`
`linkedin_visit_profile`	None	`delay`
`linkedin_like_last_post`	None	`delay`, `reactionType`
`whatsapp_message`	`content`	`delay`
`condition`	`condition`	`onTrue`, `onFalse`
`linkedin_connection`	None	`waitForAcceptance`, `delay`, `content`, `aiMessageId`, `onAccepted`, `onNotAccepted`
`task`	`taskType`, `title`	`note`, `ownerId`, `delay`
`add_to_another_campaign`	`campaignId`	`delay`
`end`	None	None

email.subject is required for the first email on every live path; follow-up emails in the same thread can omit it. 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.

AI messages on steps (`aiMessageId`)

email, linkedin_message, linkedin_inmail, and linkedin_connection steps accept aiMessageId instead of manual content. The linked AI message writes a personalized message per contact at send time (for email and linkedin_inmail it generates the subject too, so omit subject).

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.

Rules:

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

Manual content/subject accepts single-brace placeholders that must reference real fields — discover them with GET /v1/contacts/fields. Examples: {firstName}, {companyName}, {identity.name}. Unknown placeholders are rejected with a 422. The company aliases {company}, {companyName}, and {companyDomain} are accepted and stored as the canonical company columns ({name}, {domain}).

`linkedin_message_bundle`

Sends several LinkedIn messages back-to-back in the same step. Each entry in messages can carry text, an attachment, or both:

Field	Type	Notes
`content`	`string`	Optional text body. At least one of `content` or `attachment` required.
`attachment`	`string`	Optional URL or storage key of a file to send.
`attachmentName`	`string`	Optional display name for the attachment.
`contentType`	`"AUDIO" \| "IMAGE" \| "FILE" \| "VIDEO"`	Optional. Recommended when `attachment` is set.

`linkedin_voice_message`

Sends a LinkedIn voice message. You can either generate audio from text via text-to-speech (content + voiceId) or provide a pre-recorded audio attachment (attachment with contentType: "AUDIO"). Use GET /v1/voices to discover valid voiceId values (system voices and identity-cloned voices owned by the client).

Field	Type	Notes
`content`	`string`	Optional. Text that will be synthesized to speech using the configured `voiceId`.
`voiceId`	`string`	Optional. ID of a system voice or an identity-cloned voice. Discoverable via `GET /v1/voices`.
`attachment`	`string`	Optional. URL or storage key of a pre-recorded audio file to send instead of synthesized text.
`attachmentName`	`string`	Optional. Display name for the audio attachment.
`contentType`	`"AUDIO"`	Optional. Recommended when `attachment` is set.
`voiceSettings`	`object`	Optional. Fine-tuning of the synthesized voice and background audio (see below).

The step must satisfy one of: (a) both content and voiceId are provided so we synthesize speech, or (b) attachment is provided to send a pre-recorded audio file. voiceSettings only applies in mode (a). voiceSettings fields (all optional):

Field	Type	Notes
`voiceSpeed`	`number`	Speech rate multiplier. Range `0.5`–`2.0`.
`voiceStability`	`number`	Voice stability percentage. Range `0`–`100`. Higher is steadier.
`backgroundNoise`	`string`	Background noise preset (e.g. `none`, `office`).
`backgroundVolume`	`number`	Background noise volume. Range `0`–`100`. Ignored when `backgroundNoise` is `none`.

Branching Step Types

Use this step	When you need it	Branch fields
`condition`	Branch based on what Enginy already knows about the lead	`onTrue`, `onFalse`
`linkedin_connection`	Send a connection request and branch based on acceptance	`onAccepted`, `onNotAccepted`

Condition Types

condition.type supports exactly these values:

Condition type	Extra fields	`onTrue` branch runs when	`onFalse` branch runs when
`has_linkedin_profile`	–	The lead has a LinkedIn profile	The lead does not have a LinkedIn profile
`has_professional_email`	–	The lead has a professional email	The lead does not have a professional email
`is_already_connected`	–	The lead is already a LinkedIn connection	The lead is not already a LinkedIn connection
`has_been_contacted`	–	The lead has already been contacted	The lead has not been contacted yet
`has_whatsapp_account`	–	The lead has a WhatsApp account	The lead does not have a WhatsApp account
`email_opened`	`waitFor` (required)	The lead opens the preceding email within `waitFor`	`waitFor` elapses without the email being opened
`email_clicked`	`waitFor` (required)	The lead clicks a link in the preceding email within `waitFor`	`waitFor` elapses without a link being clicked
`linkedin_message_viewed`	`waitFor` (required)	The lead views the preceding LinkedIn message within `waitFor`	`waitFor` elapses without the message being viewed
`task_completed`	`waitFor` (required)	The preceding `task` step is marked complete within `waitFor`	`waitFor` elapses without the task being marked complete
`connection_accepted`	`waitFor` (required)	The lead accepts an earlier LinkedIn connection request within `waitFor`	`waitFor` elapses without the connection being accepted
`lead_field`	`field`, `operator`, `value` (mostly)	The contact’s `field` matches `operator` (and `value`, where applicable)	The match fails

lead_field lets you branch on any built-in column or custom field. operator accepts: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUALS, LESS_THAN_OR_EQUALS, IS_EMPTY, IS_NOT_EMPTY. value is required for every operator except IS_EMPTY and IS_NOT_EMPTY.

Timed Conditions (`waitFor`)

email_opened, email_clicked, linkedin_message_viewed, task_completed, and connection_accepted require a waitFor object on the condition:

{
  "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 your campaign contains task steps, call GET /v1/tasks/owners first.

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

Voices

If your campaign contains linkedin_voice_message steps, call GET /v1/voices to discover the available voiceId values:

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.

Updating a Draft Campaign

Use PATCH /v1/campaign/{campaignId} to modify a campaign that is still in DRAFT status — both its settings (name, description, identity, tracking flags, …) and its step sequence.

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 that GET emits are accepted and ignored, and rich-text formatting of steps whose text you did not change is preserved automatically.
Reply follow-up emails may keep the subject: "" that GET returns; it means “reply in the existing thread”.
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.

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

Use the campaign creation endpoint to build the sequence first, then use one of the audience endpoints below to start adding contacts to it.

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

Send a short text message followed by a file attachment in the same LinkedIn step.

{
  "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

Follow up on LinkedIn only if the lead clicks the tracked email link within three days, otherwise bump via email.

{
  "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

Wait up to five days for a task to be marked complete; otherwise fall back to another channel.

{
  "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"
      }
    }
  ]
}

API documentation

Endpoints

Overview

Quick Start

Rules

Step Types

AI messages on steps (`aiMessageId`)

Personalization placeholders

`linkedin_message_bundle`

`linkedin_voice_message`

Branching Step Types

Condition Types

Timed Conditions (`waitFor`)

Validation Checklist

Task Owners

Voices

Updating a Draft Campaign

Adding Contacts After Creation

Example: Add a Contact Group to a Campaign

Example: Condition First

Example: LinkedIn Acceptance Branch

Example: LinkedIn Message Bundle

Example: Branch on Email Click

Example: Task Completion Branch

Example: Explicitly Stop One Branch

​Overview

​Quick Start

​Rules

​Step Types

​AI messages on steps (aiMessageId)

​Personalization placeholders

​linkedin_message_bundle

​linkedin_voice_message

​Branching Step Types

​Condition Types

​Timed Conditions (waitFor)

​Validation Checklist

​Task Owners

​Voices

​Updating a Draft Campaign

​Related Endpoints

​Adding Contacts After Creation

​Example: Add a Contact Group to a Campaign

​Example: Condition First

​Example: LinkedIn Acceptance Branch

​Example: LinkedIn Message Bundle

​Example: Branch on Email Click

​Example: Task Completion Branch

​Example: Explicitly Stop One Branch

Overview

Quick Start

Rules

Step Types

AI messages on steps (`aiMessageId`)

Personalization placeholders

`linkedin_message_bundle`

`linkedin_voice_message`

Branching Step Types

Condition Types

Timed Conditions (`waitFor`)

Validation Checklist

Task Owners

Voices

Updating a Draft Campaign

Related Endpoints

Adding Contacts After Creation

Example: Add a Contact Group to a Campaign

Example: Condition First

Example: LinkedIn Acceptance Branch

Example: LinkedIn Message Bundle

Example: Branch on Email Click

Example: Task Completion Branch

Example: Explicitly Stop One Branch