SuprSend Subscriber List API
The Subscriber List API from SuprSend — 11 operation(s) for subscriber list.
OpenAPI Specification
openapi: 3.1.1
info:
title: SuprSend Broadcast Subscriber List API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: Subscriber List
paths:
/v1/subscriber_list/{list_id}/subscriber/remove/:
post:
summary: Remove Subscribers from List
security:
- BearerAuth: []
description: API to remove users from a list by passing their distinct_ids.
operationId: remove-users-from-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list to which user needs to be updated
required: true
schema:
type: string
default: _list_id_
requestBody:
content:
application/json:
schema:
type: object
properties:
distinct_ids:
type: array
description: Array of subscriber_ids, uniquely identifying the subscribers to be removed from the list.
default:
- _distinct_id1_
items:
type: string
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
success: true
affected_count: 0
schema:
type: object
properties:
success:
type: boolean
description: Indicates whether the operation was successful.
example: true
affected_count:
type: integer
description: Number of subscribers affected by the operation.
example: 0
required:
- success
- affected_count
'404':
description: '404'
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: 'list_id: _list_id_ not found'
detail: 'list_id: _list_id_ not found'
schema:
type: object
properties:
code:
type: integer
description: HTTP status code.
example: 404
error_code:
type: string
description: Machine-readable error code.
example: not_found
type:
type: string
description: Error type classification.
example: NotFound
message:
type: string
description: Human-readable error message.
example: 'list_id: _list_id_ not found'
detail:
type: string
description: Detailed error information.
example: 'list_id: _list_id_ not found'
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/:
get:
summary: Get all Lists
security:
- BearerAuth: []
description: API to fetch a paginated list of all lists created in your workspace.
operationId: get-all-lists
parameters:
- name: limit
in: query
description: number of results to be returned in API response
schema:
type: integer
default: 20
- name: offset
in: query
description: starting position of tenant list
schema:
type: integer
default: 0
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
meta:
count: 53
limit: 2
offset: 0
results:
- drafts: null
source: null
status: active
list_id: list_01
list_name: sample list 01
list_type: static_list
created_at: '2025-04-04T07:33:06.943+00:00'
updated_at: '2025-04-04T07:33:06.943+00:00'
version_id: null
is_readonly: false
track_user_exit: false
list_description: _some sample description_
track_user_entry: false
subscribers_count: 0
requested_for_delete: false
- drafts: null
source: database_sync
status: active
list_id: list_02
list_name: sample list 02
list_type: static_list
created_at: '2024-12-20T12:09:28.727+00:00'
updated_at: '2025-04-04T07:32:32.127275+00:00'
version_id: null
is_readonly: false
track_user_exit: true
list_description: _some sample description_
track_user_entry: true
subscribers_count: 31
requested_for_delete: false
schema:
type: object
properties:
meta:
type: object
properties:
count:
type: integer
description: Total number of lists available.
example: 53
limit:
type: integer
description: Maximum number of results per page.
example: 2
offset:
type: integer
description: Starting position of the results.
example: 0
results:
type: array
items:
type: object
description: List object similar to list upsert function.
'401':
description: '401'
content:
application/json:
examples:
Result:
value: Not Authenticated - could not find Workspace details
schema:
type: object
description: error message details
deprecated: false
tags:
- Subscriber List
post:
summary: Create a List
security:
- BearerAuth: []
description: API to create / manage lists to send notification to a bulk list of users.
operationId: create-list
requestBody:
content:
application/json:
schema:
type: object
required:
- list_id
properties:
list_id:
type: string
description: Unique string identifier of the list. Add an id which defines the type of users who are part of the list
default: _list_id_
list_name:
type: string
description: Name of the List. Add a name which defines the type of users in the list
default: _list_name_
list_description:
type: string
description: Brief description of the list and the type of users in it.
default: _some sample description_
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
list_id: product_updates
list_name: Product Update
list_description: Users subscribed to the newsletter
list_type: static_list
subscribers_count: 3
source: database_sync
is_readonly: false
status: active
track_user_entry: false
track_user_exit: false
requested_for_delete: false
created_at: '2024-02-21T19:10:01.906000Z'
updated_at: '2025-04-04T07:25:43.186475Z'
drafts: null
schema:
type: object
properties:
list_id:
type: string
description: Unique identifier of the list.
example: product_updates
list_name:
type: string
description: Name of the list.
example: Product Update
list_description:
type: string
description: Brief description of the list.
example: Users subscribed to the newsletter
list_type:
type: string
description: Type of the list.
enum:
- static_list
- query_based
subscribers_count:
type: integer
description: number of users in the list
source:
type: string
description: source info on how the list is updated
example: database_sync
is_readonly:
type: boolean
description: Indicates whether the list is read-only.
example: false
status:
type: string
description: Current status of the list (active or draft).
example: active
track_user_entry:
type: boolean
description: Event `$USER_ENTERED_LIST - <list_id>` is generated when user is added this list. Use this to trigger workflow on user entry.
track_user_exit:
type: boolean
description: Event `$USER_EXITED_LIST - <list_id>` is generated when user is removed from this list. Use this to trigger workflow on user exit.
requested_for_delete:
type: boolean
description: Indicates whether the list has been requested for deletion.
example: false
created_at:
type: string
format: date-time
description: Timestamp when the list was created.
example: '2024-02-21T19:10:01.906000Z'
updated_at:
type: string
format: date-time
description: Timestamp when the list was last updated.
example: '2025-04-04T07:25:43.186475Z'
drafts:
type: string
nullable: true
description: would show the draft list created to replace list users.
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
code: 400
error_code: error
type: ValidationError
message: '{"list_id": ["This field may not be blank."]}'
detail:
list_id:
- This field may not be blank.
schema:
type: object
description: error code and related message detailing out the error
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/subscriber/add/:
post:
summary: Add Users to List
security:
- BearerAuth: []
description: API to add users to the list by passing their distinct_ids.
operationId: add-subscribers-to-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list to which user needs to be updated
required: true
schema:
type: string
default: _list_id_
requestBody:
content:
application/json:
schema:
type: object
properties:
distinct_ids:
type: array
description: Array of subscriber_ids, uniquely identifying the subscribers to be added to the list.
default:
- _distinct_id1_
items:
type: string
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
success: true
affected_count: 0
schema:
type: object
properties:
success:
type: boolean
description: Indicates whether the operation was successful.
example: true
affected_count:
type: integer
description: Number of subscribers affected by the operation.
example: 2
'404':
description: '404'
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: 'list_id: _list_id_ not found'
detail: 'list_id: _list_id_ not found'
schema:
type: object
properties:
code:
type: integer
description: HTTP status code.
example: 404
error_code:
type: string
description: Machine-readable error code.
example: not_found
type:
type: string
description: Error type classification.
example: NotFound
message:
type: string
description: Human-readable error message.
example: 'list_id: _list_id_ not found'
detail:
type: string
description: Detailed error information.
example: 'list_id: _list_id_ not found'
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/:
get:
summary: Get List configuration
security:
- BearerAuth: []
description: API to fetch list metadata like list type, count, source, and status. Doesn't include users in the list.
operationId: get-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list.
required: true
schema:
type: string
default: _list_id_
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
list_id: product_updates
list_name: Product Update
list_description: Users subscribed to the newsletter
list_type: static_list
subscribers_count: 3
source: database_sync
is_readonly: false
status: active
track_user_entry: false
track_user_exit: false
requested_for_delete: false
created_at: '2024-02-21T19:10:01.906000Z'
updated_at: '2025-04-04T07:25:43.186475Z'
drafts: null
schema:
type: object
properties:
list_id:
type: string
description: Unique identifier of the list.
example: product_updates
list_name:
type: string
description: Name of the list.
example: Product Update
list_description:
type: string
description: Brief description of the list.
example: Users subscribed to the newsletter
list_type:
type: string
description: Type of the list.
enum:
- static_list
- query_based
subscribers_count:
type: integer
description: number of users in the list
source:
type: string
description: source info on how the list is updated
example: database_sync
is_readonly:
type: boolean
description: Indicates whether the list is read-only.
example: false
status:
type: string
description: Current status of the list (active or draft).
example: active
track_user_entry:
type: boolean
description: Event `$USER_ENTERED_LIST - <list_id>` is generated when user is added this list. Use this to trigger workflow on user entry.
track_user_exit:
type: boolean
description: Event `$USER_EXITED_LIST - <list_id>` is generated when user is removed from this list. Use this to trigger workflow on user exit.
requested_for_delete:
type: boolean
description: Indicates whether the list has been requested for deletion.
example: false
created_at:
type: string
format: date-time
description: Timestamp when the list was created.
example: '2024-02-21T19:10:01.906000Z'
updated_at:
type: string
format: date-time
description: Timestamp when the list was last updated.
example: '2025-04-04T07:25:43.186475Z'
drafts:
type: string
nullable: true
description: would show the draft list created to replace list users.
'404':
description: '404'
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: 'list_id: list_id_01 not found'
detail: 'list_id: list_id_01 not found'
schema:
type: object
properties:
code:
type: integer
description: HTTP status code.
example: 404
error_code:
type: string
description: Machine-readable error code.
example: not_found
type:
type: string
description: Error type classification.
example: NotFound
message:
type: string
description: Human-readable error message.
example: 'list_id: list_id_01 not found'
detail:
type: string
description: Detailed error information.
example: 'list_id: list_id_01 not found'
required:
- code
- error_code
- type
- message
- detail
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/delete/:
patch:
summary: Delete List
security:
- BearerAuth: []
description: API to permanently delete a list.
operationId: delete-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list which you want to delete
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
success: true
schema:
type: object
description: Success message when the list is successfully deleted
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: 'list_id: <list_id> not found'
detail: 'list_id: <list_id> not found'
schema:
type: object
description: Error message that the list requested for delete is not found
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/version/{version_id}/subscriber/add/:
post:
summary: Add Users to Draft List
security:
- BearerAuth: []
description: API to add users in the draft list by passing its `version_id` returned in [Start Sync](/reference/start-sync) API response.
operationId: add-subscribers-to-draft-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list to which user needs to be updated
schema:
type: string
default: _list_id_
required: true
- name: version_id
in: path
description: Unique string identifier of the draft version of the list to which user needs to be updated
schema:
type: string
default: __version_id__
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
distinct_ids:
type: array
description: Array of subscriber_ids, uniquely identifying the subscribers to be added to the list.
default:
- user1
items:
type: string
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
success: true
affected_count: 0
schema:
type: object
properties:
success:
type: boolean
description: Indicates whether the operation was successful.
example: true
affected_count:
type: integer
description: Number of subscribers affected by the operation.
example: 2
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: version_id 01JR6PCW8H9K3H40XZV4 not found for list_id 123
detail: version_id 01JR6PCW8H9K3H40XZV4 not found for list_id 123
schema:
type: object
description: error code and message detailing the reason of failure
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/version/{version_id}/delete/:
patch:
summary: Delete Draft List
security:
- BearerAuth: []
description: API to delete draft version of the list. Use this to discard test or interim versions before publishing the final list.
operationId: delete-draft-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list which you want to delete
schema:
type: string
required: true
- name: version_id
in: path
description: Unique identifier of the draft version of the list which needs to be deleted
schema:
type: string
default: __version_id__
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
success: true
schema:
type: object
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: version_id 01JR6PCW8H9K3H40XZV4A5R not found for list_id _list_id_
detail: version_id 01JR6PCW8H9K3H40XZV4A5R not found for list_id _list_id_
schema:
type: object
description: error code and related message
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/version/{version_id}/finish_sync/:
patch:
summary: Finish Sync
security:
- BearerAuth: []
description: API to finish sync and make the draft list version live.
operationId: finish-sync
parameters:
- name: list_id
in: path
description: Unique string identifier of the list
schema:
type: string
default: _list_id_
required: true
- name: version_id
in: path
description: Unique string identifier of the draft version of the list which needs to be made active(live)
schema:
type: string
default: __version_id__
required: true
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
list_id: _list_id_
list_name: _list_name_
list_description: a brief of what type of users are part of this list
list_type: static_list
subscribers_count: 0
source: null
is_readonly: false
status: draft
track_user_entry: false
track_user_exit: false
requested_for_delete: false
created_at: '2025-04-06T23:18:59.601000Z'
updated_at: '2025-04-06T23:18:59.601000Z'
version_id: null
schema:
type: object
properties:
version_id:
type: string
description: finish sync makes the draft version with the version_id live as well deletes the draft version.
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: version_id 01JR6PCW8H9K3H40XZV4A5R not found for list_id _list_id_
detail: version_id 01JR6PCW8H9K3H40XZV4A5R not found for list_id _list_id_
schema:
type: object
description: error code and related message
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/version/{version_id}/subscriber/remove/:
post:
summary: Remove Subscribers from Draft List
security:
- BearerAuth: []
description: API to remove users from the draft list by passing its `version_id` returned in [Start Sync](/reference/start-sync) API response.
operationId: remove-subscribers-from-draft-list
parameters:
- name: list_id
in: path
description: Unique string identifier of the list to which user needs to be updated
schema:
type: string
default: _list_id_
required: true
- name: version_id
in: path
description: Unique string identifier of the draft version of the list to which user needs to be updated
schema:
type: string
default: __version_id__
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
distinct_ids:
type: array
description: Array of subscriber_ids, uniquely identifying the subscribers to be removed from the list.
default:
- user1
items:
type: string
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
success: true
affected_count: 0
schema:
type: object
properties:
success:
type: boolean
description: Indicates whether the operation was successful.
example: true
affected_count:
type: integer
description: Number of subscribers affected by the operation.
example: 2
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: version_id 01JR6PCW8H9K3H40XZV4 not found for list_id 123
detail: version_id 01JR6PCW8H9K3H40XZV4 not found for list_id 123
schema:
type: object
description: error code and message detailing the reason of failure
deprecated: false
tags:
- Subscriber List
/v1/subscriber_list/{list_id}/start_sync/:
post:
summary: Start Sync
security:
- BearerAuth: []
description: Creates an empty draft version of the list where you can update users to be replaced without affecting the live version.
operationId: start-sync
parameters:
- name: list_id
in: path
description: Unique identifier of the list on which the sync needs to start to create a draft version
schema:
type: string
default: _list_id_
required: true
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
list_id: _list_id_
list_name: _list_name_
list_description: a brief of what type of users are part of this list
list_type: static_list
subscribers_count: 0
source: null
is_readonly: false
status: draft
track_user_entry: false
track_user_exit: false
requested_for_delete: false
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-subscriber-list-api-openapi.yml