List Campaigns

Retrieve a paginated list of campaigns in the workspace.

---

Endpoint

GET https://api.campaignlark.com/v1/campaigns

---

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	optional	1	Page number.
limit	integer	optional	50	Items per page (1–100).
status	string	optional	—	Filter by status. Must be one of: DRAFT, PREPROCESSING, IN_REVIEW, QUEUED, PROCESSING, PAUSED, COMPLETED, CANCELLED, ARCHIVED.

---

Sample Request

GET https://api.campaignlark.com/v1/campaigns?page=1&limit=10&status=COMPLETED

---

Response

Success — 200 OK

{
  "error": null,
  "data": {
    "campaigns": [
      {
        "id": "64f1a2b3c4d5e6f7a8b9c0d1",
        "name": "Summer Sale",
        "type": "SINGLE_VARIANT",
        "status": "COMPLETED",
        "scheduled_at": "2025-07-01T09:00:00Z",
        "updated_at": "2025-07-01T09:05:00Z",
        "preview_url": "https://usercontent.campaignlark.com/image/abc123.png",
        "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"
          }
        ]
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total_pages": 3,
      "total_count": 25
    }
  }
}

---

Campaign Object

Field	Type	Description
id	string	Unique campaign ID (MongoDB ObjectID hex).
name	string	Campaign name.
type	string	SINGLE_VARIANT or AB_TESTING.
sender_identity	object | null	The sender identity attached to the campaign. Contains display_name, local_part, and domain_name.
reply_to	object | null	Optional reply-to identity. Same shape as sender_identity.
audience	array	Array of audience configuration objects.
variants	array	Array of variant objects.
scheduled_at	string | null	ISO 8601 UTC timestamp if scheduled for later.
status	string	One of: DRAFT, PREPROCESSING, IN_REVIEW, QUEUED, PROCESSING, PAUSED, COMPLETED, CANCELLED, ARCHIVED.
updated_at	string	ISO 8601 UTC timestamp of last update.

Variant Object

Field	Type	Description
id	string	Unique variant ID.
type	string	A or B.
subject	string	Email subject line.
preview_text	string	Email preview text.
template_type	string	EDITOR or CODE.
preview_url	string	URL to the variant preview image.

Audience Object

Field	Type	Description
type	string	ENTIRE_AUDIENCE, TAGS, or SEGMENTS.
include_tag_ids	array of integers | null	Tag IDs to include (when type is TAGS).
include_segment_ids	array of integers | null	Segment IDs to include (when type is SEGMENTS).
exclude_tag_ids	array of integers | null	Tag IDs to exclude.
exclude_segment_ids	array of integers | null	Segment IDs to exclude.

Sender Identity Object

Field	Type	Description
display_name	string	The display name shown to recipients.
local_part	string	The part before the @ in the email address.
domain_name	string	The domain part of the email address.

---

Campaign Statuses

Status	Description
DRAFT	The campaign has been created but is not yet scheduled. It can still be edited (sender identity, audience, variants, content). All campaigns start in this state.
PREPROCESSING	The campaign has been scheduled and is undergoing an automated content review. This applies to newer workspaces that have not yet built up a sending history. The system checks the email content and links for policy compliance. If approved, the campaign moves to QUEUED automatically. If flagged, it transitions to IN_REVIEW for manual review.
IN_REVIEW	The campaign is being reviewed for compliance. It remains in this state until approved, at which point it moves to QUEUED. No emails are sent yet.
QUEUED	The campaign is approved and waiting to be processed. If it was scheduled for later, it sits here until the scheduled time arrives.
PROCESSING	The campaign is actively sending emails. The system is working through the contact list, creating and dispatching individual email jobs.
PAUSED	The campaign was paused from QUEUED or PROCESSING. Remaining unsent emails are held. The campaign can be resumed or cancelled.
COMPLETED	All email jobs for the campaign have been processed. This is the normal terminal state for a successful send.
CANCELLED	The campaign was manually cancelled. Any unsent/pending email jobs are deleted. Can be reached from DRAFT, PREPROCESSING, IN_REVIEW, QUEUED, PROCESSING, or PAUSED.
ARCHIVED	The campaign has been archived for organizational purposes. Can only be archived from DRAFT, PAUSED, COMPLETED, or CANCELLED.

---

Errors

Status	Message	Cause
400	Invalid status '<value>'. Allowed values: DRAFT, PREPROCESSING, ...	The status query parameter is not a valid campaign status.