Navigation
SuperSend

Label API

Interfaces to manage labels and label assignments


Labels allow you to organize and categorize conversations. You can create, update, and delete labels, as well as assign or remove them from conversations.

ℹ️

V2 API Available

V2 provides standardized responses for label endpoints.

List Labels

Get all labels for your organization.

V2 API (Recommended)

bash
curl -X GET 'https://api.supersend.io/v2/labels?team_id=xxx' \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response (200 OK)
{
  "success": true,
  "data": [
    {
      "object": "label",
      "id": "label-uuid",
      "name": "interested",
      "color": "#4CAF50",
      "team_id": "team-uuid",
      "org_id": "org-uuid",
      "created_at": "2025-11-27T10:30:00Z",
      "updated_at": "2025-11-27T10:30:00Z"
    },
    {
      "object": "label",
      "id": "label-uuid-2",
      "name": "not interested",
      "color": "#F44336",
      "team_id": null,
      "org_id": "org-uuid",
      "created_at": "2025-11-27T10:30:00Z",
      "updated_at": "2025-11-27T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

V2 Query Parameters:

ParameterTypeRequiredDescription

team_idstringYesTeam identifier (UUID)
searchstringNoSearch by label name
limitnumberNoResults per page (default: 50, max: 100)
offsetnumberNoPagination offset (default: 0)

Note: Returns both team-scoped labels and legacy org-wide labels (where team_id is null).

V1 API

bash
curl -X GET 'https://api.supersend.io/v1/labels?search=interest' \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response
{
  "success": true,
  "data": [...]
}

Get Label

Get a specific label by ID.

V2 API (Recommended)

bash
curl -X GET 'https://api.supersend.io/v2/labels/label-uuid' \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response (200 OK)
{
  "success": true,
  "data": {
    "object": "label",
    "id": "label-uuid",
    "name": "interested",
    "color": "#4CAF50",
    "team_id": "team-uuid",
    "org_id": "org-uuid",
    "created_at": "2025-11-27T10:30:00Z",
    "updated_at": "2025-11-27T10:30:00Z"
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

Create Label

Create a new label.

V2 API (Recommended)

bash
curl -X POST 'https://api.supersend.io/v2/labels' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Interested",
    "color": "#4CAF50",
    "team_id": "team-uuid"
  }'
# Response (201 Created)
{
  "success": true,
  "data": {
    "object": "label",
    "id": "label-uuid",
    "name": "interested",
    "color": "#4CAF50",
    "team_id": "team-uuid",
    "org_id": "org-uuid",
    "created_at": "2025-11-27T10:30:00Z",
    "updated_at": "2025-11-27T10:30:00Z"
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

V2 Create Parameters:

ParameterTypeRequiredDescription

namestringYesLabel name (1-50 characters, will be lowercased)
colorstringYesHex color code (e.g., #4CAF50)
team_idstringYesTeam identifier (UUID)

Note: If a soft-deleted label with the same name exists, it will be restored instead of creating a new one.

V1 API

bash
curl -X POST 'https://api.supersend.io/v1/labels' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Interested",
    "color": "#4CAF50"
  }'

Update Label

Update a label's name and/or color.

V2 API (Recommended)

bash
curl -X PATCH 'https://api.supersend.io/v2/labels/label-uuid' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Very Interested",
    "color": "#2E7D32"
  }'
# Response (200 OK)
{
  "success": true,
  "data": {
    "object": "label",
    "id": "label-uuid",
    "name": "very interested",
    "color": "#2E7D32",
    "team_id": "team-uuid",
    "org_id": "org-uuid",
    "created_at": "2025-11-27T10:30:00Z",
    "updated_at": "2025-11-27T10:35:00Z"
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

V2 Update Parameters:

ParameterTypeRequiredDescription

namestringNoLabel name (1-50 characters, will be lowercased)
colorstringNoHex color code (e.g., #4CAF50)

Note: At least one parameter (name or color) is required. Label names are automatically lowercased.

V1 API

bash
curl -X PUT 'https://api.supersend.io/v1/labels/label-uuid' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Very Interested",
    "color": "#2E7D32"
  }'

Delete Label

Delete a label (soft delete).

V2 API (Recommended)

bash
curl -X DELETE 'https://api.supersend.io/v2/labels/label-uuid' \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response (200 OK)
{
  "success": true,
  "message": "Label deleted successfully",
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

V1 API

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

Conversation Label Assignment (V1 Only)

Assign Label to Conversation

bash
curl -X POST 'https://api.supersend.io/v1/labels/conversation' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label_id": "label-uuid",
    "conversation_id": "conversation-uuid"
  }'
# Response
{
  "success": true,
  "message": "Label assigned to conversation"
}

Remove Label from Conversation

bash
curl -X DELETE 'https://api.supersend.io/v1/labels/conversation' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label_id": "label-uuid",
    "conversation_id": "conversation-uuid"
  }'

Get Conversation Labels

bash
curl -X GET 'https://api.supersend.io/v1/labels/conversation?conversation_id=xxx' \
  -H "Authorization: Bearer YOUR_API_KEY"

V1 vs V2 Endpoint Mapping

ActionV1 EndpointV2 Endpoint

ListGET /v1/labelsGET /v2/labels
GetNot availableGET /v2/labels/:id
CreatePOST /v1/labelsPOST /v2/labels
UpdatePUT /v1/labels/:idPATCH /v2/labels/:id
DeleteDELETE /v1/labels/:idDELETE /v2/labels/:id
Conversation assignV1 onlyNot available in V2