Campaign API

Interfaces to manage campaigns

A campaign is the configuration for sending out messages. Campaigns need senders, messages, and contacts in order to work properly.

ℹ️

V2 API Recommended

V2 API provides standardized responses and better error handling. See endpoint comparisons below.

Response Format

V2 endpoints and app-compat V1 endpoints return a standardized response with success, data (or message), and request_id. Legacy V1 endpoints may return different shapes. Errors return:

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_campaign_id",
    "message": "CampaignId is required",
    "param": "CampaignId",
    "doc_url": "https://docs.supersend.io/docs/errors#missing_campaign_id"
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

Create Campaign

Create a new campaign.

V2 API (Recommended)

bash

curl -X POST 'https://api.supersend.io/v2/campaigns' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Q4 Outreach Campaign", "TeamId": "team-uuid" }'

# Response (201 Created) { "success": true, "data": { "id": "campaign-uuid", "name": "Q4 Outreach Campaign", "status": 1, "track_domain": null, "is_draft": true, "legacy_sequence": false, "nodes": null, "settings": null, "contact_count": 0, "createdAt": "2025-11-27T10:00:00Z", "updatedAt": "2025-11-27T10:00:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V1 API

bash

curl -X POST 'https://api.supersend.io/v1/campaign' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Q4 Outreach Campaign", "TeamId": "team-uuid" }'

# Response (201 Created) { "success": true, "data": { "campaign": { "id": "campaign-uuid", "name": "Q4 Outreach Campaign", ... } }, "request_id": "req_a1b2c3d4e5f6789012345678" }

List Campaigns

Get campaigns for a team.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/campaigns?TeamId=xxx&limit=20' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "id": "campaign-uuid", "name": "Q4 Outreach Campaign", "status": 1, "track_domain": null, "is_draft": false, "legacy_sequence": false, "nodes": [...], "contact_count": 150, "contact_metrics": { "total": 150, "not_started": 50, "in_progress": 75, "finished": 20, "paused": 5 }, "user_id": "user-uuid", "createdAt": "2025-11-01T10:00:00Z", "updatedAt": "2025-11-27T15:30:00Z" } ], "pagination": { "total": 10, "limit": 20, "offset": 0, "has_more": false }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

Parameter	Type	Required	Description
`TeamId`	string	Yes	Team identifier
`search`	string	No	Search in campaign name or track_domain
`status`	number	No	Filter by status (1=inactive, 2=active)
`archived`	string	No	Include archived campaigns (`"true"` or `"false"`, default: `"false"`)
`sortBy`	string	No	Sort field: `newest` (default), `oldest`, `last_modified`, `name`
`limit`	number	No	Results per page (default: 50)
`offset`	number	No	Pagination offset

Contact Metrics:

The contact_metrics object provides lifecycle breakdown of contacts in the campaign:

Field	Description
`total`	Total non-archived contacts
`not_started`	Contacts waiting in queue (haven't started the sequence yet)
`in_progress`	Contacts currently progressing through the sequence
`finished`	Contacts that completed the sequence
`paused`	Contacts currently paused

ℹ️

Auto-Refill Integration

Use not_started to determine how many contacts are queued and ready. This is useful for auto-refill integrations that need to maintain a minimum queue size.

V1 API (with metrics)

The V1 overview endpoint includes performance metrics:

bash

curl -X GET 'https://api.supersend.io/v1/campaigns/overview?TeamId=xxx&limit=50&includeMetrics=true' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response { "success": true, "campaigns": [ { "id": "campaign-uuid", "name": "Q4 Outreach Campaign", "contactedCount": 150, "openCount": 75, "replyCount": 12, "emailSentCount": 200, "linkedInSentCount": 50, "bounces": 5, "opt_outs": 2, "contactCount": 300, "verifiedContactCount": 280, ... } ], "total": 1 }

V1 Additional Parameters:

search - Search in campaign name

order_by - Sort field (name, status, createdAt, etc.)

order - Sort direction (ASC, DESC)

status - Filter by status (1=active, 2=inactive)

archived - Include archived campaigns

includeMetrics - Include performance metrics

Get Campaign

Get a single campaign by ID.

V2 API (Recommended)

bash

curl -X GET 'https://api.supersend.io/v2/campaigns/campaign-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": { "id": "campaign-uuid", "name": "Q4 Outreach Campaign", "status": 1, "track_domain": null, "is_draft": false, "legacy_sequence": false, "nodes": [...], "timezone": "America/New_York", "days": [1, 2, 3, 4, 5], "max_per_day": 50, "contact_count": 150, "contact_metrics": { "total": 150, "not_started": 50, "in_progress": 75, "finished": 20, "paused": 5 }, "created_by": { "id": "user-uuid", "name": "John Doe", "email": "john@example.com" }, "team_id": "team-uuid", "createdAt": "2025-11-01T10:00:00Z", "updatedAt": "2025-11-27T15:30:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V1 API

bash

curl -X GET 'https://api.supersend.io/v1/campaign/campaign-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response { "success": true, "campaign": {...} }

Update Campaign

Update campaign settings.

V2 API (Recommended)

bash

curl -X PATCH 'https://api.supersend.io/v2/campaigns/campaign-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Campaign Name", "track_domain": "track.example.com", "status": 2, "is_draft": false, "settings": {...}, "nodes": [...] }'

# Response (200 OK) { "success": true, "data": { "id": "campaign-uuid", "name": "Updated Campaign Name", "status": 2, "track_domain": "track.example.com", "is_draft": false, "legacy_sequence": false, "nodes": [...], "settings": {...}, "createdAt": "2025-11-01T10:00:00Z", "updatedAt": "2025-11-27T15:30:00Z" }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Update Parameters:

Parameter	Type	Required	Description
`name`	string	No	Campaign name
`track_domain`	string	No	Tracking domain
`settings`	object	No	Campaign settings
`nodes`	array	No	Campaign sequence nodes
`status`	number	No	Status (1=inactive, 2=active)
`is_draft`	boolean	No	Draft status

Note: Cannot modify nodes or legacy_sequence while campaign is active (status=2).

V1 API

V1 supports additional configuration options:

bash

curl -X PUT 'https://api.supersend.io/v1/campaign/campaign-uuid' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Campaign Name", "status": 1, "warm": false, "unsubscribe": true, "max_per_day": 25, "max_per_day_twitter": 50, "unsubscribe_message": "Click here to unsubscribe", "hours": [ { "start": "09:00", "end": "12:00" }, { "start": "14:00", "end": "17:00" } ], "days": { "monday": true, "tuesday": true, "wednesday": true, "thursday": true, "friday": true, "saturday": false, "sunday": false }, "LinkedinId": "linkedin-account-id", "TwitterId": "twitter-account-id", "SenderIds": ["sender-id-1", "sender-id-2"], "TeamId": "team-uuid", "CampaignId": "campaign-uuid" }'

# Response { "success": true, "message": "Campaign updated successfully" }

Clone Campaign (V1 Only)

Create a copy of an existing campaign with all its messages and settings.

bash

curl -X POST 'https://api.supersend.io/v1/campaign/campaign-uuid/clone' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "TeamId": "team-uuid" }'

# Response { "success": true, "campaign": { "id": "new-campaign-uuid", "name": "Copy of Original Campaign", ... } }

Delete Campaign (V1 Only)

Delete a campaign.

bash

curl -X DELETE 'https://api.supersend.io/v1/campaign/campaign-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response { "success": true, "message": "Campaign deleted successfully" }

Campaign Status Values

Status	Description
1	Active - Campaign is running
2	Inactive - Campaign is paused

V1 vs V2 Endpoint Mapping

Action	V1 Endpoint	V2 Endpoint
Create	`POST /v1/campaign`	`POST /v2/campaigns`
List	`GET /v1/campaigns/overview`	`GET /v2/campaigns`
Get	`GET /v1/campaign/:id`	`GET /v2/campaigns/:id`
Update	`PUT /v1/campaign/:id`	`PATCH /v2/campaigns/:id`
Delete	`DELETE /v1/campaign/:id`	Not available in V2
Clone	`POST /v1/campaign/:id/clone`	Not available in V2