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

Feature	V1	V2
Error format	Mixed formats	Standardized JSON
HTTP status codes	Often 200 with error	Correct codes (400, 401, 404, 500)
Request tracking	None	Unique `request_id` on every response
Error codes	String parsing	Machine-readable codes
Response format	Inconsistent	Standardized `{ 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.

Rate limits: V2 traffic is subject to infrastructure rate limits (50 req/s, 20 connections, 3,000 req/min per IP). There are no endpoint-specific limits on V2. See Rate Limits for full details.

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

Method	Endpoint	Description
`GET`	`/v2/teams`	List all teams
`GET`	`/v2/teams/:id`	Get a team
`POST`	`/v2/teams`	Create a team
`PATCH`	`/v2/teams/:id`	Update a team
`GET`	`/v2/teams/:id/usage`	Get team usage/capacity

Contacts

Method	Endpoint	Description
`POST`	`/v2/contacts`	Create a contact
`GET`	`/v2/contacts`	List contacts
`GET`	`/v2/contacts/:id`	Get a contact
`PATCH`	`/v2/contacts/:id`	Update a contact
`DELETE`	`/v2/contacts/:id`	Delete a contact
`DELETE`	`/v2/contacts`	Delete by email/linkedin_url

Campaigns

Method	Endpoint	Description
`POST`	`/v2/campaigns`	Create a campaign
`GET`	`/v2/campaigns`	List campaigns
`GET`	`/v2/campaigns/:id`	Get a campaign
`PATCH`	`/v2/campaigns/:id`	Update a campaign

Senders

Method	Endpoint	Description
`GET`	`/v2/senders`	List senders
`GET`	`/v2/senders/:id`	Get a sender
`PATCH`	`/v2/senders/:id`	Update a sender

Events

Method	Endpoint	Description
`GET`	`/v2/events`	List events
`GET`	`/v2/events/:id`	Get an event

Email Infrastructure

Sender Profiles

Method	Endpoint	Description
`GET`	`/v2/sender-profiles`	List sender profiles
`GET`	`/v2/sender-profiles/:id`	Get a sender profile
`POST`	`/v2/sender-profiles`	Create a sender profile
`PATCH`	`/v2/sender-profiles/:id`	Update a sender profile
`DELETE`	`/v2/sender-profiles/:id`	Delete a sender profile

Domains

Method	Endpoint	Description
`GET`	`/v2/domains`	List managed domains
`GET`	`/v2/domains/:id`	Get a domain

Placement Tests

Method	Endpoint	Description
`GET`	`/v2/placement-tests`	List placement tests
`GET`	`/v2/placement-tests/:id`	Get a placement test
`POST`	`/v2/placement-tests`	Create a placement test

Blacklist

Method	Endpoint	Description
`GET`	`/v2/blacklist`	List blacklist items
`POST`	`/v2/blacklist`	Add to blacklist
`DELETE`	`/v2/blacklist/:id`	Remove from blacklist

Integration Resources

Labels

Method	Endpoint	Description
`GET`	`/v2/labels`	List labels
`GET`	`/v2/labels/:id`	Get a label
`POST`	`/v2/labels`	Create a label
`PATCH`	`/v2/labels/:id`	Update a label
`DELETE`	`/v2/labels/:id`	Delete a label

Identities (LinkedIn/Twitter)

Method	Endpoint	Description
`GET`	`/v2/identities`	List identities
`GET`	`/v2/identities/:id`	Get an identity
`PATCH`	`/v2/identities/:id`	Update an identity
`DELETE`	`/v2/identities/:id`	Delete an identity

Conversations

Method	Endpoint	Description
`GET`	`/v2/conversations`	List conversations
`GET`	`/v2/conversations/:id`	Get a conversation
`PATCH`	`/v2/conversations/:id`	Update a conversation
`POST`	`/v2/conversations/:id/messages`	Send a message
`GET`	`/v2/conversations/:id/messages`	Get messages

Webhooks

Method	Endpoint	Description
`GET`	`/v2/webhooks`	List webhooks
`GET`	`/v2/webhooks/:id`	Get a webhook
`POST`	`/v2/webhooks`	Create a webhook
`PATCH`	`/v2/webhooks/:id`	Update a webhook
`DELETE`	`/v2/webhooks/:id`	Delete a webhook
`POST`	`/v2/webhooks/:id/test`	Test a webhook
`GET`	`/v2/webhooks/:id/deliveries`	List delivery logs
`GET`	`/v2/webhooks/:id/deliveries/:deliveryId`	Get delivery details
`POST`	`/v2/webhooks/:id/deliveries/:deliveryId/retry`	Retry failed delivery

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

Utility

Method	Endpoint	Description
`GET`	`/v2/health`	API health check (no auth)
`GET`	`/v2/openapi.yaml`	OpenAPI spec (YAML)
`GET`	`/v2/openapi.json`	OpenAPI 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/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