Configure Campaign

Configure a campaign's sender identity, reply-to address, audience, and variant metadata in a single call. The campaign must be in DRAFT status.

Endpoint

PATCH https://api.campaignlark.com/v1/campaigns/:id/configure

Path Parameters

Parameter	Type	Required	Description
`id`	string	required	The campaign ID.

Request Body

All top-level fields are optional — include only the sections you want to update. Omitted sections are left unchanged. When provided, sender and audience fully replace the existing configuration. All three must be configured (across one or more calls) before the campaign can be scheduled.

Field	Type	Required	Description
`sender`	object	optional	Sender identity configuration. Replaces the existing sender when provided.
`sender.sender_identity_id`	integer	required (if `sender` provided)	ID of the sender identity to use. Must exist in the workspace.
`sender.reply_to`	object	optional	Reply-to identity with `display_name`, `local_part`, and `domain_name`.
`audience`	object	optional	Audience targeting configuration. Replaces the existing audience when provided.
`audience.type`	string	required (if `audience` provided)	`ENTIRE_AUDIENCE`, `TAGS`, or `SEGMENTS`.
`audience.include_tag_ids`	array of integers	required if type is `TAGS`	Tag IDs to send to.
`audience.include_segment_ids`	array of integers	required if type is `SEGMENTS`	Segment IDs to send to.
`audience.exclude_tag_ids`	array of integers	optional	Tag IDs to exclude from the audience.
`audience.exclude_segment_ids`	array of integers	optional	Segment IDs to exclude from the audience.
`variants`	array of objects	optional	Variant subject/preview text configuration. Omit to leave variants unchanged.
`variants[].type`	string	required	`A` or `B`.
`variants[].subject`	string	required	Subject line (3–90 characters).
`variants[].preview_text`	string	optional	Preview text (max 120 characters).

Sample Request

PATCH https://api.campaignlark.com/v1/campaigns/64f1a2b3c4d5e6f7a8b9c0d1/configure
Content-Type: application/json

{
  "sender": {
    "sender_identity_id": 12,
    "reply_to": {
      "display_name": "Support",
      "local_part": "support",
      "domain_name": "example.com"
    }
  },
  "audience": {
    "type": "SEGMENTS",
    "include_segment_ids": [2, 7],
    "exclude_segment_ids": [4]
  },
  "variants": [
    {
      "type": "A",
      "subject": "Don't miss our Summer Sale!",
      "preview_text": "Up to 50% off everything"
    },
    {
      "type": "B",
      "subject": "Summer Sale — Last Chance!",
      "preview_text": "Ends tonight at midnight"
    }
  ]
}

Response

Success — `200 OK`

Returns the updated campaign configuration:

{
  "error": null,
  "data": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Summer Sale Campaign",
    "type": "SINGLE_VARIANT",
    "sender_identity": {
      "display_name": "My Store",
      "local_part": "hello",
      "domain_name": "example.com"
    },
    "reply_to": {
      "display_name": "Support",
      "local_part": "support",
      "domain_name": "example.com"
    },
    "audience": [
      {
        "type": "TAGS",
        "include_tag_ids": [1, 3],
        "exclude_tag_ids": [5]
      }
    ],
    "variants": [
      {
        "id": "64f1a2b3c4d5e6f7a8b9c0d2",
        "type": "A",
        "subject": "Don't miss our Summer Sale!",
        "preview_text": "Up to 50% off everything",
        "template_type": "EDITOR",
        "preview_url": "https://usercontent.campaignlark.com/image/abc123.png"
      }
    ]
  }
}

Errors

Status	Message	Cause
`400`	`Please provide a campaign ID.`	`id` path param is missing.
`400`	`Invalid request body.`	Request body could not be parsed.
`400`	`We could not find the campaign you are looking for.`	Campaign not found.
`400`	`The campaign must be in draft mode before it can be configured.`	Campaign is not in `DRAFT` status.
`400`	`Invalid sender identity DomainID.`	`sender_identity_id` is invalid.
`400`	`The sender identity could not be found.`	Sender identity does not exist in the workspace.
`400`	`Invalid audience type. Must be 'ENTIRE_AUDIENCE', 'TAGS', or 'SEGMENTS'.`	Invalid audience type.
`400`	`At least one tag is required when audience type is 'TAGS'.`	`include_tag_ids` is empty when type is `TAGS`.
`400`	`One or more tags could not be found.`	A provided tag ID does not exist.
`400`	`At least one segment is required when audience type is 'SEGMENTS'.`	`include_segment_ids` is empty when type is `SEGMENTS`.
`400`	`One or more segments could not be found.`	A provided segment ID does not exist.
`400`	`One or more exclude tags could not be found.`	An exclude tag ID does not exist.
`400`	`One or more exclude segments could not be found.`	An exclude segment ID does not exist.
`400`	`Invalid variant type. Must be 'A' or 'B'.`	Variant type is not `A` or `B`.
`400`	`Single variant campaigns cannot have a 'B' variant.`	Tried to add variant B to a `SINGLE_VARIANT` campaign.
`400`	`Single variant campaigns must include variant 'A'.`	Variant A is missing for a `SINGLE_VARIANT` campaign.
`400`	`A/B testing campaigns must include both variant 'A' and variant 'B'.`	Missing a variant for an `AB_TESTING` campaign.
`400`	`Please provide a subject for this variant.`	Variant subject is empty.
`400`	`The subject must be at least 3 characters long.`	Subject is too short.
`400`	`The subject must be 90 characters or less.`	Subject exceeds 90 characters.
`400`	`The preview text must be 120 characters or less.`	Preview text exceeds 120 characters.

Endpoint​

Path Parameters​

Request Body​

Sample Request​

Response​

Success — 200 OK​

Errors​