Navigation
SuperSend

V2 API Overview

Introduction to SuperSend's V2 API with improved error handling and standardized responses


SuperSend V2 API provides a more consistent, developer-friendly experience with standardized error handling, proper HTTP status codes, and request tracking.

What's New in V2

FeatureV1V2

Error formatMixed formatsStandardized JSON
HTTP status codesOften 200 with errorCorrect codes (400, 401, 404, 500)
Request trackingNoneUnique request_id on every response
Error codesString parsingMachine-readable codes
Response formatInconsistentStandardized { success, data, request_id }

Base URL

https://api.supersend.io/v2

All V2 endpoints are prefixed with /v2. V1 endpoints continue to work at /v1.

Authentication

V2 uses the same API key authentication as V1:

bash
curl -X GET 'https://api.supersend.io/v2/teams' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Get your API key from the Organization Admin Settings.

Response Format

Success Responses

Single Resource (200 OK)

json
{
  "success": true,
  "data": {
    "id": "abc-123",
    "email": "john@example.com",
    "first_name": "John"
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

List with Pagination (200 OK)

json
{
  "success": true,
  "data": [
    { "id": "1", "email": "a@example.com" },
    { "id": "2", "email": "b@example.com" }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

Action Message (200 OK)

json
{
  "success": true,
  "message": "Contact deleted successfully",
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

Error Responses

All errors follow this format:

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

See Error Handling for complete error code reference.

Available V2 Endpoints

Core Resources

Teams


MethodEndpointDescription

GET/v2/teamsList all teams
GET/v2/teams/:idGet a team
POST/v2/teamsCreate a team
PATCH/v2/teams/:idUpdate a team
GET/v2/teams/:id/usageGet team usage/capacity

Contacts


MethodEndpointDescription

POST/v2/contactsCreate a contact
GET/v2/contactsList contacts
GET/v2/contacts/:idGet a contact
PATCH/v2/contacts/:idUpdate a contact
DELETE/v2/contacts/:idDelete a contact
DELETE/v2/contactsDelete by email/linkedin_url

Campaigns


MethodEndpointDescription

POST/v2/campaignsCreate a campaign
GET/v2/campaignsList campaigns
GET/v2/campaigns/:idGet a campaign
PATCH/v2/campaigns/:idUpdate a campaign

Senders


MethodEndpointDescription

GET/v2/sendersList senders
GET/v2/senders/:idGet a sender
PATCH/v2/senders/:idUpdate a sender

Events


MethodEndpointDescription

GET/v2/eventsList events
GET/v2/events/:idGet an event

Email Infrastructure

Sender Profiles


MethodEndpointDescription

GET/v2/sender-profilesList sender profiles
GET/v2/sender-profiles/:idGet a sender profile
POST/v2/sender-profilesCreate a sender profile
PATCH/v2/sender-profiles/:idUpdate a sender profile
DELETE/v2/sender-profiles/:idDelete a sender profile

Domains


MethodEndpointDescription

GET/v2/domainsList managed domains
GET/v2/domains/:idGet a domain

Placement Tests


MethodEndpointDescription

GET/v2/placement-testsList placement tests
GET/v2/placement-tests/:idGet a placement test
POST/v2/placement-testsCreate a placement test

Blacklist


MethodEndpointDescription

GET/v2/blacklistList blacklist items
POST/v2/blacklistAdd to blacklist
DELETE/v2/blacklist/:idRemove from blacklist

Integration Resources

Labels


MethodEndpointDescription

GET/v2/labelsList labels
GET/v2/labels/:idGet a label
POST/v2/labelsCreate a label
PATCH/v2/labels/:idUpdate a label
DELETE/v2/labels/:idDelete a label

Identities (LinkedIn/Twitter)


MethodEndpointDescription

GET/v2/identitiesList identities
GET/v2/identities/:idGet an identity
PATCH/v2/identities/:idUpdate an identity
DELETE/v2/identities/:idDelete an identity

Conversations


MethodEndpointDescription

GET/v2/conversationsList conversations
GET/v2/conversations/:idGet a conversation
PATCH/v2/conversations/:idUpdate a conversation
POST/v2/conversations/:id/messagesSend a message
GET/v2/conversations/:id/messagesGet messages

Webhooks


MethodEndpointDescription

GET/v2/webhooksList webhooks
GET/v2/webhooks/:idGet a webhook
POST/v2/webhooksCreate a webhook
PATCH/v2/webhooks/:idUpdate a webhook
DELETE/v2/webhooks/:idDelete a webhook
POST/v2/webhooks/:id/testTest a webhook
GET/v2/webhooks/:id/deliveriesList delivery logs
GET/v2/webhooks/:id/deliveries/:deliveryIdGet delivery details
POST/v2/webhooks/:id/deliveries/:deliveryId/retryRetry failed delivery

See Webhooks Documentation for full details on delivery logs and retry functionality.

Utility

MethodEndpointDescription

GET/v2/healthAPI health check (no auth)
GET/v2/openapi.yamlOpenAPI spec (YAML)
GET/v2/openapi.jsonOpenAPI spec (JSON)

Request ID

Every V2 response includes a unique request_id:

  • In response body: "request_id": "req_a1b2c3d4e5f6789012345678"

  • In response header: X-Request-Id: req_a1b2c3d4e5f6789012345678

    • Use request IDs for:

  • Debugging failed requests

  • Contacting support

  • Correlating logs

    • Always log request IDs in your application:

    javascript
    const response = await fetch(url, options)
    const requestId = response.headers.get('X-Request-Id')
    const data = await response.json()
    console.log(Request ${requestId}: ${response.status})
    if (!data.success) {
      console.error(Error: ${data.error.code} - ${data.error.message})
    }

    Pagination

    List endpoints support pagination with limit and offset:

    bash
    # First page (50 items)
    GET /v2/contacts?TeamId=xxx&limit=50&offset=0
    # Second page
    GET /v2/contacts?TeamId=xxx&limit=50&offset=50

    Pagination Response:

    json
    {
      "pagination": {
        "total": 150,
        "limit": 50,
        "offset": 50,
        "has_more": true
      }
    }

    Use has_more to know if there are more pages.

    V1 vs V2 Comparison

    Error Handling

    V1 (inconsistent):

    javascript
    // Sometimes 200 with error in body
    { "error": "Campaign not found" }
    // Sometimes proper status
    // Status 404
    { "success": false, "error": "Not found" }

    V2 (consistent):

    javascript
    // Always correct HTTP status with structured error
    // Status 404
    {
      "error": {
        "type": "not_found_error",
        "code": "campaign_not_found",
        "message": "Campaign not found"
      },
      "request_id": "req_..."
    }

    Success Responses

    V1:

    javascript
    // Various formats
    { "message": "Success", "contact": {...} }
    { "success": true, "data": {...} }
    { "contacts": [...] }

    V2:

    javascript
    // Always consistent
    {
      "success": true,
      "data": {...},
      "request_id": "req_..."
    }

    Migration Guide

    Migrating from V1 to V2 is straightforward:

  • Change base URL: /v1/ → /v2/

  • Update endpoints: Some endpoints have cleaner paths

    • - /v1/contact/create → POST /v2/contacts
    - /v1/auto/contacts → GET /v2/contacts
  • Update error handling: Use error codes instead of parsing messages

  • Add request ID logging: Capture request_id for debugging

    • See V1 to V2 Migration for detailed migration guide.

    Need Help?

  • Error Handling Reference

  • Rate Limits

  • API Changelog

  • Email: support@supersend.io