Create campaign

Create a draft campaign from the public simplified sequence model. Best for new campaigns or rewrites that fit the supported public step types; this endpoint does not preserve arbitrary internal editor-only graph wiring from an existing campaign.

Responses include direct Enginy app URLs when available. Responses include an appUrl that opens the created campaign in Enginy. MCP agents should return those URLs to users whenever they are present in the response.

Create a draft campaign from the public steps format.

How to structure the request:

• Start steps with the first action that should happen.
• Keep adding the next action in the order it should run.
• Use condition when you want to branch on lead data.
• Use linkedin_connection with waitForAcceptance when you want to branch on connection acceptance after sending a connection request. Omit waitForAcceptance for a fire-and-forget connection request.
• Use linkedin_message with content, attachment, or both. Attachment-only messages are valid.
• Use whatsapp_message only when the workspace and sending identity are configured for WhatsApp.
• Put shared follow-up work after the branching step instead of duplicating the same steps inside both branches.

AI-generated messages (message library):

• 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.
• To reuse a prompt-library (“message library”) prompt, list entries with GET /v1/prompt-library/ai-messages and pass the entry id as the step aiMessageId. The step gets its own copy automatically.
• To reuse or create a workspace AI message, use GET /v1/ai-variables/ai-messages or POST /v1/ai-variables/ai-messages (full control over prompt, toneId, model, outputLength, and splitMessages), then pass its id as aiMessageId.
• The AI message channel must match the step type (EMAIL, LINKEDIN, LINKEDIN_INMAIL, or LINKEDIN_CONNECTION).
• Never combine aiMessageId with manual content or subject on the same step — for email and linkedin_inmail the AI message generates the subject too.

Before you send a request:

• Send an ordered steps array that describes the campaign flow from first action to last action.
• Use branch arrays on condition and linkedin_connection steps to describe branch-specific work.
• Place shared follow-up steps after a branching step when both live branches should continue together.
• waitForAcceptance.unit must be days and waitForAcceptance.value must be an integer greater than or equal to 1.
• Use GET /v1/tasks/owners first when your campaign includes task steps. If owners are returned, every task step must include ownerId.
• Validation errors use full paths like steps[0].onTrue[1].subject so nested input issues are easy to fix.
• Personalization placeholders use Enginy single-brace syntax such as {firstName}, {companyName}, and {identity.name}. Do not send Handlebars-style placeholders like {{firstName}}.
• Placeholders must reference real fields — discover them with GET /v1/contacts/fields. Unknown placeholders are rejected with a 422. The company aliases {company}, {companyName}, and {companyDomain} are accepted and stored as the canonical company columns.
• To modify an existing DRAFT campaign in place, prefer PATCH /v1/campaign/{campaignId} over creating a new one. To rewrite into a new campaign, start from the steps returned by GET /v1/campaign/{campaignId}. Either way the read-only stepId, connectionId, nextConnectionId, and advanced fields are accepted and ignored, but fill in messages that come back empty (their content is AI-generated per contact — recreate them with aiMessageId where the step type supports it, or provide manual content).

Supported condition.type values:

• has_linkedin_profile: onTrue runs when the lead has a LinkedIn profile.
• has_professional_email: onTrue runs when the lead has a professional email.
• is_already_connected: onTrue runs when the lead is already a LinkedIn connection.
• has_been_contacted: onTrue runs when the lead has already been contacted.
• has_whatsapp_account: onTrue runs when the lead has a WhatsApp account.
• email_opened: onTrue runs when the lead opens the preceding email within waitFor. Must follow an email step. Requires waitFor (value, unit).
• email_clicked: onTrue runs when the lead clicks a link in the preceding email within waitFor. Must follow an email step. Requires waitFor (value, unit).
• linkedin_message_viewed: onTrue runs when the lead views the preceding LinkedIn message within waitFor. Must follow a LinkedIn message step (linkedin_message, linkedin_message_bundle, linkedin_voice_message, or linkedin_inmail). Requires waitFor (value, unit).
• task_completed: onTrue runs when the preceding task step is marked complete within waitFor. Must follow a task step. Requires waitFor (value, unit).
• connection_accepted: onTrue runs when the lead accepts a previous LinkedIn connection request within waitFor. Requires waitFor (value, unit).
• lead_field: onTrue runs when the contact field matches the operator (and value, where applicable). Use this to branch on any built-in column or custom field. Requires field and operator. value is required for every operator except IS_EMPTY and IS_NOT_EMPTY. Supported operators: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUALS, LESS_THAN_OR_EQUALS, IS_EMPTY, IS_NOT_EMPTY.

Branch fields:

• condition uses onTrue and onFalse.
• linkedin_connection uses onAccepted and onNotAccepted only when waitForAcceptance is set.
• Use [{ "type": "end" }] when a branch should stop explicitly.

Routing into another campaign:

• Use add_to_another_campaign with a campaignId to route the lead into an existing campaign in the same workspace.
• The referenced campaignId must belong to the same client as the API key. If you are cloning campaigns across workspaces, remap each campaignId to the equivalent campaign in the destination workspace before posting.
• Can be followed by additional steps in the same branch.

For examples and a full step-by-step guide, see /api-reference/campaigns-guide in the docs site.

Required scope: CAMPAIGNS_WRITE

Rate limit: 30 requests per minute