List SMS Campaigns

Retrieve a paginated list of SMS campaigns in the workspace.

---

Endpoint

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

---

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	optional	1	Page number.
limit	integer	optional	50	Items per page. Values are sanitised to the supported range and capped at 100.
status	string	optional	—	Filter by status: DRAFT, QUEUED, COMPLETED, CANCELLED, or ARCHIVED.

---

Sample Request

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

---

Response

Success — 200 OK

{
  "error": null,
  "data": {
    "campaigns": [
      {
        "id": "64f1a2b3c4d5e6f7a8b9c0d1",
        "name": "Summer Sale SMS",
        "message": "Summer sale: 20% off today. https://example.com/sale",
        "audience": [
          {
            "type": "SEGMENTS",
            "include_segment_ids": [2, 7],
            "exclude_segment_ids": [4]
          }
        ],
        "status": "COMPLETED",
        "scheduled_at": "2025-07-01T09:00:00Z",
        "statistics": {
          "sent": 4820,
          "delivered": 4600,
          "clicked": 412,
          "failed": 23,
          "unsubscribed": 8,
          "suppressed": 189
        },
        "created_at": "2025-06-30T12:00:00Z",
        "updated_at": "2025-07-01T09:05:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total_pages": 3,
      "total_count": 25
    }
  }
}

Audience Object

Field	Type	Description
type	string	ENTIRE_AUDIENCE, TAGS, or SEGMENTS.
include_tag_ids	array of integers | null	Tag IDs included when type is TAGS.
include_segment_ids	array of integers | null	Segment IDs included when type is SEGMENTS.
exclude_tag_ids	array of integers | null	Tag IDs excluded from the audience.
exclude_segment_ids	array of integers | null	Segment IDs excluded from the audience.

SMS Campaign Object

Field	Type	Description
id	string	Unique campaign ID (MongoDB ObjectID hex).
workspace_id	integer	Workspace that owns the campaign.
name	string	Campaign name.
message	string	SMS message body.
audience	array	Audience configuration objects.
status	string	DRAFT, QUEUED, COMPLETED, CANCELLED, or ARCHIVED.
scheduled_at	string | null	RFC3339 timestamp when scheduled for later.
statistics	object	Aggregate SMS statistics for the campaign.
created_at	string	Campaign creation timestamp.
updated_at	string	Last update timestamp.

SMS Audience Eligibility

Audience selection uses tags and segments in the same way as email campaigns. Sending eligibility is determined by each contact's sms_status: contacts with SUBSCRIBED status, or contacts created before SMS status was introduced, are eligible. UNSUBSCRIBED, CLEANED, and BLOCKED contacts are excluded. Email opt-out state has no effect on SMS eligibility, and SMS opt-out state has no effect on email eligibility.

SMS Campaign Lifecycle

SMS campaigns use DRAFT, QUEUED, COMPLETED, CANCELLED, and ARCHIVED statuses.

• DRAFT: The campaign can be configured and scheduled.
• QUEUED: The campaign is scheduled or being expanded into per-recipient SMS jobs.
• COMPLETED: The audience has been fully expanded into per-recipient messages. It does not mean every message was delivered; delivery outcomes are available through statistics and SMS history.
• CANCELLED: Sending is stopped. Recipients whose messages never reached a provider are refundable; recipients already handed to a carrier remain charged.
• ARCHIVED: The campaign is archived.

There is no per-campaign conversions endpoint. Conversions are tracked through the existing Track a Conversion endpoint.

---

Errors

Status	Message	Cause
400	Invalid status '<value>'.	The status query parameter is not one of the supported SMS campaign statuses.