SMS Campaigns

Create and manage bulk SMS campaigns.

WARNING

SMS Live Mode Only: All SMS endpoints require a live mode API key (sk_live_*).

Create SMS Campaign

Create a new SMS campaign to send bulk messages.

Endpoint: POST /v1/sms/campaigns

Authentication: Required

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Campaign name
`message_body`	string	Yes*	Campaign message (required if `template_id` not provided)
`template_id`	string	Yes*	Template ID (required if `message_body` not provided)
`template_params`	object	No	Template parameters
`sender_id`	string	No	Custom sender ID
`contact_ids`	array	No	Array of contact IDs to send to
`group_ids`	array	No	Array of group IDs to send to
`scheduled_at`	string	No	Schedule campaign for later (ISO 8601)
`is_draft`	boolean	No	Save as draft (default: `false`)

Campaign Statuses:

draft - Not sent yet

scheduled - Scheduled for future sending

sending - Currently sending

completed - All messages sent

failed - Campaign failed

cancelled - Campaign cancelled

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "camp_abc123",
    "organization_id": "org_xyz789",
    "name": "Summer Promotion",
    "message_template_id": null,
    "sender_id_config_id": null,
    "status": "draft",
    "scheduled_at": null,
    "started_at": null,
    "completed_at": null,
    "created_by": "user_123",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "details": {
      "total_message_count": 2,
      "total_sent_messages": 0,
      "total_failed_messages": 0,
      "total_pending_messages": 2,
      "total_segments_used": 0,
      "delivery_rate": 0.0,
      "failure_rate": 0.0,
      "pending_rate": 100.0,
      "status_breakdown": {
        "pending": 2
      }
    }
  }
}

TIP

Campaign Statistics: The details object provides real-time statistics about your campaign including delivery rates, message counts, and status breakdowns.

Get SMS Campaign

Get details of a specific SMS campaign.

Endpoint: GET /v1/sms/campaigns/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

List SMS Campaigns

Get a paginated list of SMS campaigns.

Endpoint: GET /v1/sms/campaigns

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`status`	string	No	Filter by status (`draft`, `scheduled`, `sending`, `completed`, `failed`, `cancelled`)

Example:

HTTP

TypeScript

Python

Update SMS Campaign

Update an existing SMS campaign (only draft campaigns can be updated).

Endpoint: PUT /v1/sms/campaigns/{id}

Authentication: Required

Request Body:

Field	Type	Required	Description
`name`	string	No	Campaign name
`message_body`	string	No	Campaign message
`template_id`	string	No	Template ID
`template_params`	object	No	Template parameters
`sender_id`	string	No	Custom sender ID
`contact_ids`	array	No	Array of contact IDs
`group_ids`	array	No	Array of group IDs
`scheduled_at`	string	No	Schedule time (ISO 8601)

INFO

Only draft campaigns can be updated. Once a campaign has started sending, it cannot be modified.

Send SMS Campaign

Start sending an SMS campaign.

Endpoint: POST /v1/sms/campaigns/{id}/send

Authentication: Required

Request Body:

Field	Type	Required	Description
`scheduled_at`	string	No	Optional time to schedule the campaign

Example:

HTTP

TypeScript

Python

Send Campaign Asynchronously

Send a large SMS campaign asynchronously for better performance.

Endpoint: POST /v1/sms/campaigns/{id}/send-async

Authentication: Required

Example:

HTTP

TypeScript

Python

TIP

Large Campaigns: Use send-async for campaigns with many recipients. The campaign will be queued and processed in the background.

Get Campaign Statistics

Get detailed statistics for an SMS campaign.

Endpoint: GET /v1/sms/campaigns/{id}/statistics

Authentication: Required

Example:

HTTP

TypeScript

Python

Get Campaign Messages

Get a list of messages sent in a campaign.

Endpoint: GET /v1/sms/campaigns/{id}/messages

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`status`	string	No	Filter by status (`queued`, `sending`, `sent`, `delivered`, `failed`)

Resend Failed Campaign Messages

Resend all failed messages in a campaign.

Endpoint: POST /v1/sms/campaigns/{id}/resend-failed

Authentication: Required

Example:

HTTP

TypeScript

Python

Delete SMS Campaign

Delete an SMS campaign (only draft campaigns can be deleted).

Endpoint: DELETE /v1/sms/campaigns/{id}

Authentication: Required

Success Response (204): No content

SMS Campaigns

Create SMS Campaign#

Get SMS Campaign#

List SMS Campaigns#

Update SMS Campaign#

Send SMS Campaign#

Send Campaign Asynchronously#

Get Campaign Statistics#

Get Campaign Messages#

Resend Failed Campaign Messages#

Delete SMS Campaign#

Create SMS Campaign

Get SMS Campaign

List SMS Campaigns

Update SMS Campaign

Send SMS Campaign

Send Campaign Asynchronously

Get Campaign Statistics

Get Campaign Messages

Resend Failed Campaign Messages

Delete SMS Campaign