SuprSend User API
The User API from SuprSend — 9 operation(s) for user.
OpenAPI Specification
openapi: 3.1.1
info:
title: SuprSend Broadcast User API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: User
paths:
/v1/user/{distinct_id}/preference/category/:
get:
summary: All Categories
security:
- BearerAuth: []
description: API to fetch user preferences across all categories.
operationId: get-user-preference-all-categories
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be fetched
schema:
type: string
required: true
- name: tenant_id
in: query
description: to fetch user preferences for a particular tenant
schema:
type: string
- name: show_opt_out_channels
in: query
description: set this flag to `true` if you want to fetch channel list for opt-out categories.
schema:
type: boolean
default: false
- name: tags
in: query
description: 'Filter preference categories with tags assigned to them. Used to filter preference categories relevant to the user on UI based on their roles, department or teams.
You can apply single tag filter like `tags=tag1` or build nested conditions using logical operators - `and`, `or`, `not`, `exists`.
Example:
```
tags=admin
tags={"or":[{"and":["admin","sales"]},{"and":["admin","manager"]}]}
tags={"not":"admin"}
tags={"exists":true}
'
schema:
type: string
- name: locale
in: query
description: "Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch preference translations in user's locale. When provided, the API looks for category and section names and descriptions in the respective locale file. \nIf a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available).\n"
schema:
type: string
example: es
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
meta:
count: 12
limit: 10
offset: 0
results:
- name: Newsletter
category: newsletter
description: Send me updates on new product updates
original_preference: null
preference: opt_in
is_editable: false
channels:
- channel: email
preference: opt_in
is_editable: false
- channel: ms_teams
preference: opt_in
is_editable: false
schema:
type: object
properties:
meta:
type: object
properties:
count:
type: integer
example: 12
limit:
type: integer
example: 10
offset:
type: integer
example: 0
results:
type: array
items:
type: object
properties:
name:
type: string
example: Newsletter
category:
type: string
example: newsletter
description:
type: string
example: Send me updates on new product updates
original_preference:
type: string
description: default preference of the category
nullable: true
example: null
preference:
type: string
enum:
- opt_in
- opt_out
example: opt_in
description: updated user preference of the category
is_editable:
type: boolean
description: false when category default preference is set to `can't unsubscribe`
example: false
channels:
type: array
description: channel level preference in the category
items:
type: object
properties:
channel:
type: string
description: channel name
example: email
preference:
type: string
description: user preference for this channel (opt_in, opt_out)
example: opt_in
is_editable:
type: boolean
description: whether the user can edit this channel preference
example: false
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
message: 'user [distinct_id: ''user1''] not found'
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: 'user [distinct_id: ''user1''] not found'
deprecated: false
tags:
- User
/v1/user/{distinct_id}/preference/channel_preference/:
get:
summary: All Channels
security:
- BearerAuth: []
description: API to retrieve user preferences for all channels.
operationId: get-user-preference-channel
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be fetched
schema:
type: string
required: true
- name: tenant_id
in: query
description: to fetch user preferences for a particular tenant
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
channel_preferences:
- channel: androidpush
is_restricted: false
- channel: email
is_restricted: false
schema:
type: object
properties:
channel_preferences:
type: array
items:
type: object
properties:
channel:
type: string
description: channel name
example: androidpush
is_restricted:
type: boolean
description: True means notification will be sent in categories where this channel is marked as mandatory channel. False means opt_in on channel.
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
message: 'user [distinct_id: ''user1''] not found'
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: 'user [distinct_id: ''user1''] not found'
deprecated: false
tags:
- User
patch:
summary: Overall Channel level
security:
- BearerAuth: []
description: API to update user preferences across all channels.
operationId: update-user-preference-channel
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be fetched
schema:
type: string
required: true
- name: tenant_id
in: query
description: to fetch user preferences for a particular tenant
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
channel_preferences:
type: array
description: Use this to update channel level user preferences. Set `is_restricted - true` if the channel is opted_out by the user. This will only send critical notifications to the user which can't be opted out
items:
properties:
channel:
type: string
description: Add channel as `email`, `inbox`, `sms`, `whatsapp`, `androidpush`, `slack`, `iospush`, `webpush`
default: email
is_restricted:
type: boolean
description: set `is_restricted = true` if user wants to receive notification in mandatory categories on this channel. Mandatory categories are `can't unsubscribe` categories and the above channel is added as `mandatory channel` in that category
default: false
type: object
responses:
'202':
description: '202'
content:
application/json:
examples:
Result:
value:
channel_preferences:
- channel: email
is_restricted: true
- channel: inbox
is_restricted: false
schema:
type: object
properties:
channel_preferences:
type: array
items:
type: object
properties:
channel:
type: string
example: email
is_restricted:
type: boolean
example: 'true'
'400':
description: 400 - Bad Request
content:
application/json:
examples:
Result:
value:
code: 400
detail:
channel_preferences[0].channel: must be one of ["sms", "email", "androidpush" "iospush", "webpush", "inbox", "whatsapp", "slack", "ms_teams"]
message: '{"channel_preferences[0].channel": must be one of ["sms", "email", "androidpush" "iospush", "webpush", "inbox", "whatsapp", "slack", "ms_teams"]'
schema:
type: object
properties:
code:
type: integer
example: 400
detail:
type: object
description: error details
message:
type: string
description: error message
deprecated: false
tags:
- User
/v1/user/{distinct_id}/preference/category/{category_slug}/:
patch:
summary: Category and Channel within Category
security:
- BearerAuth: []
description: API to update user preferences for a specific notification category.
operationId: update-user-preference-category
x-codeSamples:
- lang: cURL
label: Update User Category Preference - Opt Out Channel
source: "curl -X PATCH \"https://hub.suprsend.com/v1/user/user123/preference/status-update-alert/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"preference\": \"opt_in\",\n \"opt_out_channels\": [\"email\", \"slack\"]\n }'\n"
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be fetched
schema:
type: string
required: true
- name: tenant_id
in: query
description: to fetch user preferences for a particular tenant
schema:
type: string
- name: category_slug
in: path
description: notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page
schema:
type: string
required: true
- name: locale
in: query
description: 'Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch translated category and section names and descriptions. When provided, the API returns category and section names and descriptions in the specified language if translations are available. If a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available).
'
schema:
type: string
example: es
requestBody:
content:
application/json:
schema:
type: object
properties:
preference:
type: string
description: 'choose one of the options: `opt_in` if the user has allowed notification in this category and `opt_out` if user wants to discontinue notification in this category'
default: opt_in
opt_out_channels:
type: array
description: Add array of channels if user wants to unsubscribe from particular channels in this category. Add channels as `email`, `sms`, `whatsapp`, `androidpush`, `inbox`, `iospush`, `slack`, `webpush`
items:
type: string
opt_in_channels:
type: array
description: You can either pass opt_out_channels when user opts out from a channel in the category or opt_in_channels when user opts in to a channel in the category. Add channels as `email`, `sms`, `whatsapp`, `androidpush`, `inbox`, `iospush`, `slack`, `webpush`
items:
type: string
responses:
'202':
description: '202'
content:
application/json:
examples:
Result:
value:
name: Status Update Alert
category: status-update-alert
description: Send me updates when account status changes
original_preference: opt_in
preference: opt_in
is_editable: true
channels:
- channel: email
preference: opt_in
is_editable: true
- channel: ms_teams
preference: opt_in
is_editable: true
- channel: slack
preference: opt_in
is_editable: true
schema:
type: object
properties:
name:
type: string
example: Status Update Alert
category:
type: string
example: status-update-alert
description:
type: string
example: Send me updates when account status changes
original_preference:
type: string
description: default preference of the category
example: opt_in
preference:
type: string
description: final user preference of the category
example: opt_in
is_editable:
type: boolean
description: false for categories where default preference is set to can't unsubscribe
example: true
channels:
type: array
items:
type: object
properties:
channel:
type: string
example: email
preference:
type: string
enum:
- opt_in
- opt_out
example: opt_in
is_editable:
type: boolean
example: true
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
message: category '_category_slug_' not found
schema:
type: object
description: error code and message detailing the error
deprecated: false
tags:
- User
get:
summary: Single Category
security:
- BearerAuth: []
description: API to fetch user preferences for a given category.
operationId: get-user-preferences-single-category
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be fetched
schema:
type: string
required: true
- name: tenant_id
in: query
description: to fetch user preferences for a particular tenant
schema:
type: string
- name: category_slug
in: path
description: notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page
schema:
type: string
required: true
- name: show_opt_out_channels
in: query
description: set this flag to `true` if you want to fetch channel list for opt-out categories.
schema:
type: boolean
default: false
- name: locale
in: query
description: 'Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch preference translations in user''s locale. When provided, the API looks for category and section names and descriptions in the respective locale file.
If a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available).
'
schema:
type: string
example: es
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
name: Newsletter
category: newsletter
description: Send me updates on new product updates
original_preference: null
preference: opt_in
is_editable: false
channels:
- channel: email
preference: opt_in
is_editable: false
- channel: ms_teams
preference: opt_in
is_editable: false
schema:
type: object
properties:
name:
type: string
description: name of the notification category
example: Newsletter
category:
type: string
description: category slug identifier
example: newsletter
description:
type: string
description: description of the notification category
example: Send me updates on new product updates
original_preference:
type: string
description: default preference of the category
nullable: true
example: null
preference:
type: string
description: updated user preference of the category
example: opt_in
is_editable:
type: boolean
description: false when category default preference is set to `can't unsubscribe`
example: false
channels:
type: array
description: channel level preference in the category
items:
type: object
properties:
channel:
type: string
description: channel name
example: email
preference:
type: string
description: user preference for this channel (opt_in, opt_out)
example: opt_in
is_editable:
type: boolean
description: whether the user can edit this channel preference
example: false
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
message: category 'category_slug' not found
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: category 'category_slug' not found
deprecated: true
tags:
- User
/v1/user/{distinct_id}/preference/:
get:
summary: Full Preference
security:
- BearerAuth: []
description: API to fetch user preferences across all channels and categories.
operationId: get-user-full-preference
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be fetched
schema:
type: string
required: true
- name: tenant_id
in: query
description: to fetch user preferences for a particular tenant
schema:
type: string
- name: show_opt_out_channels
in: query
description: set this flag to `true` if you want to fetch channel list for opt-out categories.
schema:
type: boolean
default: false
- name: tags
in: query
description: 'Filter preference categories with tags assigned to them. Used to filter preference categories relevant to the user on UI based on their roles, department or teams.
You can apply single tag filter like `tags=tag1` or build nested conditions using logical operators - `and`, `or`, `not`, `exists`.
Example:
```
tags=admin
tags={"or":[{"and":["admin","sales"]},{"and":["admin","manager"]}]}
tags={"not":"admin"}
tags={"exists":true}
'
schema:
type: string
- name: locale
in: query
description: 'Locale code (e.g., `es`, `fr`, `es-AR`) to fetch preference translations in user''s locale. When provided, the API looks for category and section names and descriptions in the respective locale file.
If a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available).
'
schema:
type: string
example: es
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
sections:
- subcategories:
- name: Newsletter
category: newsletter
description: Send me updates on new product updates
preference: opt_in
is_editable: true
channels:
- channel: androidpush
preference: opt_in
is_editable: true
- channel: email
preference: opt_in
is_editable: true
channel_preferences:
- channel: email
is_restricted: false
schema:
type: object
properties:
sections:
type: array
items:
type: object
properties:
subcategories:
type: array
items:
type: object
properties:
name:
type: string
example: Newsletter
category:
type: string
example: newsletter
description:
type: string
example: Send me updates on new product updates
preference:
type: string
enum:
- opt_in
- opt_out
example: opt_in
is_editable:
type: boolean
description: false when category default preference is set to can't unsubscribe
channels:
type: array
items:
type: object
properties:
channel:
type: string
example: email
preference:
type: string
enum:
- opt_in
- opt_out
example: opt_in
is_editable:
type: boolean
description: false when category default preference is set to can't unsubscribe
channel_preferences:
type: array
items:
type: object
properties:
channel:
type: string
description: channel name
example: androidpush
is_restricted:
type: boolean
description: True means notification will be sent in categories where this channel is marked as mandatory channel. False means opt_in on channel.
'404':
description: '404'
content:
application/json:
examples:
Result:
value:
code: 404
message: 'user [distinct_id: ''user1''] not found'
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: 'user [distinct_id: ''user1''] not found'
deprecated: false
tags:
- User
patch:
summary: Update User Full Preference
security:
- BearerAuth: []
description: API to update user preferences across all channels and categories with translated names and descriptions in the response.
operationId: update-user-full-preference
parameters:
- name: distinct_id
in: path
description: distinct_id of the user whose preferences should be updated
schema:
type: string
required: true
- name: tenant_id
in: query
description: to update user preferences for a particular tenant
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
channel_preferences:
type: array
description: Use this to update channel level user preferences. Set `is_restricted - true` if the channel is opted_out by the user. This will only send critical notifications to the user which can't be opted out
items:
type: object
properties:
channel:
type: string
description: Add channel as `email`, `inbox`, `sms`, `whatsapp`, `androidpush`, `slack`, `iospush`, `webpush`
is_restricted:
type: boolean
description: set `is_restricted = true` if user wants to receive notification in mandatory categories on this channel. Mandatory categories are `can't unsubscribe` categories and the above channel is added as `mandatory channel` in that category
categories:
type: array
description: Use this to update user preference across categories and channels inside a category.
items:
type: object
properties:
category:
type: string
description: notification category slug
preference:
type: string
enum:
- opt_in
- opt_out
description: set `opt_in` to turn on notifications on all or selected channels, `opt_out` to turn-off notifications
opt_out_channels:
type: array
description: List of channels to opt-out from this category. Only applicable when preference is `opt_in`
items:
type: string
opt_in_channels:
type: array
description: List of channels to opt-in for this category. Only applicable when preference is `opt_in`
items:
type: string
examples:
Update Preferences:
value:
channel_preferences:
- channel: email
is_restricted: false
categories:
- category:
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-user-api-openapi.yml