Navigation
SuperSend

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:

ParameterTypeRequiredDescription
namestringYesCampaign name
TeamIdstring (UUID)YesTeam identifier
track_domainstringNoTracking domain (team default used if omitted)
trackbooleanNoEnable open and click tracking. Default: false.
category_idstring (UUID) or nullNoCampaign category (folder) ID
nodesarrayNoInitial sequence nodes
edgesarrayNoInitial sequence edges
is_draftbooleanNoDraft status (default: true)
custom_variablesarrayNoCustom variable definitions for contacts
templateIdstring (UUID)NoTemplate used to create this campaign
send_to_risk_levelsarray or nullNoList Health levels to send to
bccarray of emails or nullNoBCC email addresses
bcc_replies_onlybooleanNoWhen true, BCC only applies to reply emails
timezonestringNoCampaign schedule timezone
daysobjectNoDays of week to send
hoursarrayNoSending hours windows
startstring (ISO 8601) or nullNoCampaign start date
endstring (ISO 8601) or nullNoCampaign end date
unsubscribebooleanNoEnable opt-out link in emails
unsubscribe_messagestring or nullNoKeyword to detect opt-out in replies
blacklistIfUnsubscribebooleanNoAdd contact to blacklist when they opt out
blacklistIfBouncedbooleanNoAdd contact to blacklist when email bounces
blacklistDomainOnReplybooleanNoBlacklist contact domain when reply received
list_unsubscribe_headerbooleanNoAdd List-Unsubscribe header to emails
failureConfigurationobjectNoSequence 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:

ParameterTypeRequiredDescription
TeamIdstringYesTeam identifier
searchstringNoSearch in campaign name or track_domain
statusnumberNoFilter by status (1=active, 2=inactive)
archivedstringNoInclude archived campaigns ("true" or "false", default: "false")
sortBystringNoSort field: newest (default), oldest, last_modified, name
limitnumberNoResults per page (default: 50)
offsetnumberNoPagination offset


Contact Metrics:

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

FieldDescription
totalTotal non-archived contacts
not_startedContacts waiting in queue (haven't started the sequence yet)
in_progressContacts currently progressing through the sequence
finishedContacts that completed the sequence
pausedContacts 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",
        "reply_link_clicks": 12,
        "createdAt": "2025-11-01T10:00:00Z",
        "updatedAt": "2025-11-27T15:30:00Z"
      },
      "request_id": "req_a1b2c3d4e5f6789012345678"
    }

    reply_link_clicks: Deduplicated count of inbox reply link clicks attributed to this campaign — at most one per (contact, link, UTC calendar day). Separate from sequence-step clicks on campaign emails. See List Campaign Inbox Reply Link Clicks.

    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:

    ParameterTypeRequiredDescription
    namestringNoCampaign name
    track_domainstringNoTracking domain
    trackbooleanNoEnable open and click tracking. When false, no pixels or link rewrites; replies/bounces still tracked.
    category_idstring (UUID) or nullNoCampaign category (folder) ID. Set to null to uncategorize. See Campaign Categories.
    nodesarrayNoCampaign sequence nodes
    edgesarrayNoCampaign sequence edges (connections between nodes)
    statusnumberNoStatus (1=ACTIVE, 2=INACTIVE)
    is_draftbooleanNoDraft status
    max_per_daynumber or nullNoMax emails per day from all senders (1–100000). null = no campaign limit.
    send_to_risk_levelsarray or nullNoList Health levels to send to (SAFE, LOW, MEDIUM, HIGH, INVALID). null = send to all.
    bccarray of emails or nullNoBCC email addresses
    bcc_replies_onlybooleanNoWhen true, BCC only applies to reply emails
    timezonestringNoCampaign schedule timezone (e.g. America/Los_Angeles)
    daysobjectNoDays of week to send: { monday: true, tuesday: true, ... }
    hoursarrayNoSending hours: [{ start: "09:00", end: "17:00" }]
    startstring (ISO 8601) or nullNoCampaign start date
    endstring (ISO 8601) or nullNoCampaign end date
    unsubscribebooleanNoEnable opt-out link in emails
    unsubscribe_messagestring or nullNoKeyword to detect opt-out in replies
    blacklistIfUnsubscribebooleanNoAdd contact to blacklist when they opt out
    blacklistIfBouncedbooleanNoAdd contact to blacklist when email bounces
    blacklistDomainOnReplybooleanNoBlacklist contact domain when reply received
    list_unsubscribe_headerbooleanNoAdd List-Unsubscribe header to emails
    failureConfigurationobjectNoSequence 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,
        "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",
        "SenderIds": ["sender-id-1", "sender-id-2"],
        "TeamId": "team-uuid",
        "CampaignId": "campaign-uuid"
      }'
    # Response
    {
      "success": true,
      "message": "Campaign updated successfully"
    }

    Subsequences {#subsequences}

    Subsequences are linked child campaigns used with Move To Another Campaign steps. They require the subsequences_enabled feature for your organization. API endpoints return 404 when the feature is off.

    Rules:

  • Max 3 subsequences per parent campaign

  • One level deep — a subsequence cannot have its own subsequences

  • GET /v2/campaigns excludes subsequences by default; pass include_subsequences=true to include them

  • Creating with parentCampaignId sets the parent link; the child inherits normal campaign behavior

    • List subsequences

    bash
    curl -X GET 'https://api.supersend.io/v2/campaigns/{parentCampaignId}/subsequences' \
      -H "Authorization: Bearer YOUR_API_KEY"

    Get parent campaign

    bash
    curl -X GET 'https://api.supersend.io/v2/campaigns/{campaignId}/parent' \
      -H "Authorization: Bearer YOUR_API_KEY"

    Response includes isSubsequence and parentCampaign when applicable.

    Create subsequence

    Pass parentCampaignId on POST /v2/campaigns (same body as create campaign). See Create Campaign.

    Move behavior: When a contact is moved to a subsequence target, interest is preserved on the new copy, the parent contact is finished, and source campaign metadata is stored on the contact for journey tracking.

    Inbox Reply Link Tracking {#inbox-reply-link-tracking}

    SuperSend can wrap http:// and https:// URLs in Super Inbox outbound email replies with trackable redirect links. When a recipient clicks, SuperSend records the click and can append UTM parameters to the destination URL at redirect time.

    This is separate from sequence-step link tracking (track: true on campaign emails). Inbox reply link tracking is configured in the app at org and team (Super Inbox settings) levels.

    Rollup: When a click is attributed to a campaign (CampaignId on the link), reply_link_clicks on the campaign increments (deduplicated per contact, link, and UTC day). The contact's reply_link_clicked flag is set and a reply_link_click webhook may fire.

    For end-user setup (toggles, UTM templates, tokens), see Inbox Reply Link Tracking in the SuperSend help center.

    List Campaign Inbox Reply Link Clicks {#inbox-link-clicks}

    Returns paginated inbox reply link clicks attributed to a campaign.

    V2 API

    bash
    curl -X GET 'https://api.supersend.io/v2/campaigns/campaign-uuid/inbox-link-clicks?limit=25&page=1' \
      -H "Authorization: Bearer YOUR_API_KEY"
    # Response (200 OK)
    {
      "success": true,
      "data": {
        "campaign_id": "campaign-uuid",
        "clicks": [
          {
            "id": "click-uuid",
            "link_id": "link-uuid",
            "original_url": "https://your-site.com/pricing",
            "final_url": "https://your-site.com/pricing?utm_source=supersend&utm_medium=inbox_reply&utm_campaign=q3-outreach",
            "clicked_at": "2026-06-08T14:32:15.123Z",
            "is_first_today": true,
            "ip": "203.0.113.10",
            "contact": {
              "id": "contact-uuid",
              "email": "john@example.com",
              "name": "John Doe"
            },
            "sender_email": "sales@company.com",
            "sequence_step": 2
          }
        ],
        "pagination": {
          "page": 1,
          "limit": 25,
          "total": 42,
          "total_pages": 2
        }
      },
      "request_id": "req_a1b2c3d4e5f6789012345678"
    }

    V2 Query Parameters:

    ParameterTypeDescription
    pagenumberPage number (default: 1)
    limitnumberResults per page (default: 25, max: 100)
    contact_idstring (UUID)Filter to a specific contact
    date_fromstring (ISO 8601)Earliest click timestamp
    date_tostring (ISO 8601)Latest click timestamp
    first_onlybooleanWhen true, return only the first click per (contact, link, UTC day)


    Notes:

  • final_url includes UTM parameters when UTM attribution is enabled; otherwise it may be null.

  • Raw clicks are returned here; reply_link_clicks on GET /v2/campaigns/:id is the deduplicated rollup counter.

    • 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

    Archive (soft delete) a campaign and its contacts. Draft campaigns are permanently removed.

    bash
    curl -X DELETE 'https://api.supersend.io/v2/campaigns/campaign-uuid' \
      -H "Authorization: Bearer YOUR_API_KEY"
    # Response (archived campaign)
    {
      "success": true,
      "message": "Campaign archived successfully",
      "data": {
        "id": "campaign-uuid"
      },
      "request_id": "req_..."
    }
    # Response (draft campaign — permanently deleted)
    {
      "success": true,
      "message": "Campaign deleted successfully",
      "request_id": "req_..."
    }

    V1 equivalent: DELETE /v1/campaign/:id

    Campaign Status Values

    StatusDescription
    1Active - Campaign is running
    2Inactive - Campaign is paused


    V1 vs V2 Endpoint Mapping

    ActionV1 EndpointV2 Endpoint
    CreatePOST /v1/campaignPOST /v2/campaigns
    ListGET /v1/campaigns/overviewGET /v2/campaigns
    GetGET /v1/campaign/:idGET /v2/campaigns/:id
    UpdatePUT /v1/campaign/:idPATCH /v2/campaigns/:id
    DeleteDELETE /v1/campaign/:idDELETE /v2/campaigns/:id
    ClonePOST /v1/campaign/:id/cloneNot available in V2