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" }' # Optional: include nodes, edges, category_id, track, bcc, schedule, opt-outs, failureConfiguration # -d 700 dark:text-green-400">'{"name": "Q4 Outreach", "TeamId": "team-uuid", "category_id": "category-uuid", "track": true, "nodes": [...], "edges": [...]}'

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

V2 Create Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Campaign name
`TeamId`	string (UUID)	Yes	Team identifier
`track_domain`	string	No	Tracking domain (team default used if omitted)
`track`	boolean	No	Enable open and click tracking. Default: false.
`category_id`	string (UUID) or null	No	Campaign category (folder) ID
`nodes`	array	No	Initial sequence nodes
`edges`	array	No	Initial sequence edges
`is_draft`	boolean	No	Draft status (default: true)
`custom_variables`	array	No	Custom variable definitions for contacts
`templateId`	string (UUID)	No	Template used to create this campaign
`send_to_risk_levels`	array or null	No	List Health levels to send to
`bcc`	array of emails or null	No	BCC email addresses
`bcc_replies_only`	boolean	No	When true, BCC only applies to reply emails
`timezone`	string	No	Campaign schedule timezone
`days`	object	No	Days of week to send
`hours`	array	No	Sending hours windows
`start`	string (ISO 8601) or null	No	Campaign start date
`end`	string (ISO 8601) or null	No	Campaign end date
`unsubscribe`	boolean	No	Enable opt-out link in emails
`unsubscribe_message`	string or null	No	Keyword to detect opt-out in replies
`blacklistIfUnsubscribe`	boolean	No	Add contact to blacklist when they opt out
`blacklistIfBounced`	boolean	No	Add contact to blacklist when email bounces
`blacklistDomainOnReply`	boolean	No	Blacklist contact domain when reply received
`list_unsubscribe_header`	boolean	No	Add List-Unsubscribe header to emails
`failureConfiguration`	object	No	Sequence step failure handling

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=active, 2=inactive)
`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, "invalidRecipientBounces": 2, "policyBlockBounces": 2, "softBounces": 1, "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": [...], "edges": [...], "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, "nodes": [...], "edges": [...] }'

# 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": [...], "edges": [...], "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
`track`	boolean	No	Enable open and click tracking. When false, no pixels or link rewrites; replies/bounces still tracked.
`category_id`	string (UUID) or null	No	Campaign category (folder) ID. Set to `null` to uncategorize. See Campaign Categories.
`nodes`	array	No	Campaign sequence nodes
`edges`	array	No	Campaign sequence edges (connections between nodes)
`status`	number	No	Status (1=ACTIVE, 2=INACTIVE)
`is_draft`	boolean	No	Draft status
`max_per_day`	number or null	No	Max emails per day from all senders. null = no campaign limit.
`send_to_risk_levels`	array or null	No	List Health levels to send to (SAFE, LOW, MEDIUM, HIGH, INVALID). null = send to all.
`bcc`	array of emails or null	No	BCC email addresses
`bcc_replies_only`	boolean	No	When true, BCC only applies to reply emails
`timezone`	string	No	Campaign schedule timezone (e.g. America/Los_Angeles)
`days`	object	No	Days of week to send: `{ monday: true, tuesday: true, ... }`
`hours`	array	No	Sending hours: `[{ start: "09:00", end: "17:00" }]`
`start`	string (ISO 8601) or null	No	Campaign start date
`end`	string (ISO 8601) or null	No	Campaign end date
`unsubscribe`	boolean	No	Enable opt-out link in emails
`unsubscribe_message`	string or null	No	Keyword to detect opt-out in replies
`blacklistIfUnsubscribe`	boolean	No	Add contact to blacklist when they opt out
`blacklistIfBounced`	boolean	No	Add contact to blacklist when email bounces
`blacklistDomainOnReply`	boolean	No	Blacklist contact domain when reply received
`list_unsubscribe_header`	boolean	No	Add List-Unsubscribe header to emails
`failureConfiguration`	object	No	Sequence step failure handling: `{ strategy, retryAfterDays, notification }`. Strategy: `skip`, `retry`, `pause_contact`, `pause_campaign`.

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

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