REST API Reference

Explore the MagicBell REST API

Broadcasts

A broadcast is a precursor to a notification. When you specify multiple recipients, MagicBell creates a notification for each recipient and delivers it to them based on their preferences.

The broadcast object

Attributes

idstring
The unique id for this broadcast.
titlestring
Title of the broadcast.
max length: 255
contentnullable string
Content of the broadcast.
max length: 4194304
action_urlnullable string
A URL to redirect the user to when they click the notification in their notification inbox.
max length: 2048
categorynullable string
Category the notification belongs to. This is useful to allow users to set their preferences.
max length: 100
topicnullable string
Topic the notification belongs to. This is useful for creating threads or offering topic level unsubscriptions.
max length: 100
custom_attributesnullable object
Nested key-value attributes that can be used for rendering in templates in MagicBell or third-party providers. Limited to 256KB - please see Overrides for another way to send channel specific data.

Create broadcasts
real-time

Create a broadcast to send notifications to upto a 1,000 recipients - users or topic subscribers. You can identify users by their email address or by an external_id.

You don't have to import your users into MagicBell. If a user does not exist we'll create it automatically.

You can send user attributes like first_name, custom_attributes, and more when creating a broadcast.

A new notification will be shown in the inbox of each recipient in real-time. It will also be delivered to each recipient through all channels you have enabled for your project.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Request body

broadcast.titlestringrequired
Title of the broadcast.
max length: 255
broadcast.contentnullable string
Content of the broadcast.
max length: 4194304
broadcast.action_urlnullable string
A URL to redirect the user to when they click the notification in their notification inbox.
max length: 2048
broadcast.recipientsarray of objectsrequired
Users to send the notification to. You can specify up to 1000 users in the request body.
min items: 1
max items: 1000
broadcast.custom_attributesnullable object
Nested key-value attributes that can be used for rendering in templates in MagicBell or third-party providers. Limited to 256KB - please see Overrides for another way to send channel specific data.
broadcast.categorynullable string
Category the notification belongs to. This is useful to allow users to set their preferences.
max length: 100
broadcast.topicnullable string
Topic the notification belongs to. This is useful for creating threads or offering topic level unsubscriptions.
max length: 100

List broadcasts

List all broadcasts. Broadcasts are sorted in descending order by the sent_at timestamp.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Query parameters

pageinteger
The page number of the paginated response. Defaults to 1.
per_pageinteger
The number of items per page. Defaults to 20.

Fetch a broadcast by its ID

Fetch a broadcast by its ID.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

broadcast_idstringrequired
ID of the broadcast.

Fetch notifications by broadcast id.

Fetch the notifications for a broadcast.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

broadcast_idstringrequired
ID of the broadcast.

Query parameters

pageinteger
The page number of the paginated response. Defaults to 1.
per_pageinteger
The number of items per page. Defaults to 20.

Notifications


The notification object

Attributes

idstring
The unique id for this notification.
titlestring
Title of the notification.
max length: 255
contentnullable string
Content of the notification. If you provide HTML content, the notification inbox will render it correctly. It should not exceed 4MB.
action_urlnullable string
A URL to redirect the user to when they click the notification in their notification inbox.
max length: 2048
categorynullable string
Category the notification belongs to. This is useful to allow users to set their preferences.
max length: 100
topicnullable string
Topic the notification belongs to. This is useful to create threads.
max length: 100
custom_attributesnullable object
Set of key-value pairs that you can attach to a notification, 6KB at maximum. It accepts objects for the value of a key. You can use it to share data between channels or to render a custom UI.

Fetch notifications for a user

Fetch a user's notifications. Notifications are sorted in descending order by the sent_at timestamp.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Query parameters

per_pageinteger
A limit on the number of notifications to be returned. It can range between 1 and 100, and the default is 15.
pageinteger
A parameter for use in pagination. Defaults to 1.
readboolean
A filter on the notifications based on the read state. If false, only unread notifications will be returned. Defaults to null.
seenboolean
A filter on the notifications based on the seen state. If false, only unseen notifications will be returned. Defaults to null.
archivedboolean
A filter on the notifications based on the archived state. If false, only unarchived notifications will be returned. Defaults to null.
categoriesarray of strings
A filter on the notifications based on the category. If you want to get uncategorized notifications, use the "uncategorized" value. The value can be either an array of strings or a comma-separated string.
topicsarray of strings
A filter on the notifications based on the topic.

Fetch notification by ID

Fetch a user's notification by its ID.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

notification_idstringrequired
ID of the user notification. The ID of a user notification can be obtained from the "Fetch user notifications" API endpoint or from push events sent to the MagicBell React library.

Delete a notification
real-time

Delete a user's notification by its ID. The notification is deleted immediately and removed from the user's notification inbox in real-time.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

notification_idstringrequired
ID of the user notification. The ID of a user notification can be obtained from the "Fetch user notifications" API endpoint or from push events sent to the MagicBell React library.

Mark a notification as read
real-time

Mark a user notification as read. The notification will be automatically marked as seen, too.

The new state will be reflected in the user's notification inbox in real-time.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

notification_idstringrequired
ID of the user notification. The ID of a user notification can be obtained from the "Fetch user notifications" API endpoint or from push events sent to the MagicBell React library.

Mark a notification as unread
real-time

Mark a user notification as unread. The new state will be reflected in the user's notification inbox in real-time.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

notification_idstringrequired
ID of the user notification. The ID of a user notification can be obtained from the "Fetch user notifications" API endpoint or from push events sent to the MagicBell React library.

Archive a notification
real-time

Mark a user notification as archived.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

notification_idstringrequired
ID of the user notification. The ID of a user notification can be obtained from the "Fetch user notifications" API endpoint or from push events sent to the MagicBell React library.

Unarchive a notification
real-time

Mark a user notification as unarchived.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

notification_idstringrequired
ID of the user notification. The ID of a user notification can be obtained from the "Fetch user notifications" API endpoint or from push events sent to the MagicBell React library.

Mark all notifications as read
real-time

Mark all notifications of a user as read. When you call this endpoint, the notification inboxes of this user will be updated in real-time.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Query parameters

archivedboolean
A filter on the notifications based on the archived state. Specify false to select unarchived notifications. Defaults to null.
readboolean
A filter on the notifications based on the read state. Specify false to select unread notifications. Defaults to null.
seenboolean
A filter on the notifications based on the seen state. Specify false to select unseen notifications. Defaults to null.
categoriesarray of strings
A filter on the notifications based on the category. If you want to get uncategorized notifications, use the "uncategorized" value. The value can be either an array of strings or a comma-separated string.
topicsarray of strings
A filter on the notifications based on the topic.

Mark all notifications as seen
real-time

Mark all notifications of a user as seen. When you call this endpoint, the notification inboxes of this user will be updated in real-time.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Query parameters

archivedboolean
A filter on the notifications based on the archived state. Specify false to select unarchived notifications. Defaults to null.
readboolean
A filter on the notifications based on the read state. Specify false to select unread notifications. Defaults to null.
seenboolean
A filter on the notifications based on the seen state. Specify false to select unseen notifications. Defaults to null.
categoriesarray of strings
A filter on the notifications based on the category. If you want to get uncategorized notifications, use the "uncategorized" value. The value can be either an array of strings or a comma-separated string.
topicsarray of strings
A filter on the notifications based on the topic.

Users


The user object

Attributes

idstring
The unique id for this user.
external_idnullable string
A unique string that MagicBell can utilize to identify the user uniquely. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.
max length: 255
emailnullable string
The user's email.
max length: 255
first_namenullable string
The user's first name.
max length: 50
last_namenullable string
The user's last name.
max length: 50
custom_attributesobject
Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.
phone_numbersarray of strings
An array of phone numbers to use for sending SMS notifications.
max items: 50

Create a user

Create a user. Please note that you must provide the user's email or the external id so MagicBell can uniquely identify the user.

The external id, if provided, must be unique to the user.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Request body

user.idstring
The unique id for this user.
user.external_idnullable string
A unique string that MagicBell can utilize to identify the user uniquely. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.
max length: 255
user.emailnullable string
The user's email.
max length: 255
user.first_namenullable string
The user's first name.
max length: 50
user.last_namenullable string
The user's last name.
max length: 50
user.custom_attributesobject
Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.
user.phone_numbersarray of strings
An array of phone numbers to use for sending SMS notifications.
max items: 50

Fetch users

Fetches users for the project identified by the auth keys. Supports filtering, ordering, and pagination.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Query parameters

pageinteger
The page number of the paginated response. Defaults to 1.
per_pageinteger
The number of items per page. Defaults to 20.
last_seen_at:beforestring
Fetch users seen before the specified last_seen_at timestamp. Please send it in RFC3339 format
last_seen_at:afterstring
Fetch users seen after the specified last_seen_at timestamp. Please send it in RFC3339 format
last_notified_at:beforestring
Fetch users last notified before the specified last_notified_at timestamp. Please send it in RFC3339 format
last_notified_at:afterstring
Fetch users last notified after the specified last_notified_at timestamp. Please send it in RFC3339 format
order_byenum
Use it to order the returned list of users. Defaults to created_at,DESC
Possible enum values:
created_at,ASC
created_at,DESC
last_seen_at,ASC
last_seen_at,DESC
last_notified_at,ASC
last_notified_at,DESC

Update a user

Update a user's data. If you identify users by their email addresses, you need to update the MagicBell data, so this user can still access their notifications.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_idstringrequired
The user id is the MagicBell user id. Alternatively, provide an id like email:theusersemail@example.com or external_id:theusersexternalid as the user id.

Request body

user.idstring
The unique id for this user.
user.external_idnullable string
A unique string that MagicBell can utilize to identify the user uniquely. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.
max length: 255
user.emailnullable string
The user's email.
max length: 255
user.first_namenullable string
The user's first name.
max length: 50
user.last_namenullable string
The user's last name.
max length: 50
user.custom_attributesobject
Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.
user.phone_numbersarray of strings
An array of phone numbers to use for sending SMS notifications.
max items: 50

Get user by ID

Fetch a user by id, for the project identified by the auth keys.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_idstringrequired
The user id is the MagicBell user id. Accepts a UUID

Delete a user

Immediately deletes a user.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_idstringrequired
The user id is the MagicBell user id. Alternatively, provide an id like email:theusersemail@example.com or external_id:theusersexternalid as the user id.

Fetch notifications by user id.

Fetch the notifications and deliveries for a user.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_idstringrequired
The user id is the MagicBell user id. Accepts a UUID

Query parameters

pageinteger
The page number of the paginated response. Defaults to 1.
per_pageinteger
The number of items per page. Defaults to 20.

Update a user identified by email

Update a user's data. If you identify users by their email addresses, you need to update the MagicBell data, so this user can still access their notifications.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_emailstringrequired

Request body

user.idstring
The unique id for this user.
user.external_idnullable string
A unique string that MagicBell can utilize to identify the user uniquely. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.
max length: 255
user.emailnullable string
The user's email.
max length: 255
user.first_namenullable string
The user's first name.
max length: 50
user.last_namenullable string
The user's last name.
max length: 50
user.custom_attributesobject
Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.
user.phone_numbersarray of strings
An array of phone numbers to use for sending SMS notifications.
max items: 50

Delete a user identified by email

Immediately deletes a user.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_emailstringrequired

Update a user identified by external ID

Update a user's data. If you identify users by their email addresses, you need to update the MagicBell data, so this user can still access their notifications.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

external_idstringrequired

Request body

user.idstring
The unique id for this user.
user.external_idnullable string
A unique string that MagicBell can utilize to identify the user uniquely. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.
max length: 255
user.emailnullable string
The user's email.
max length: 255
user.first_namenullable string
The user's first name.
max length: 50
user.last_namenullable string
The user's last name.
max length: 50
user.custom_attributesobject
Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.
user.phone_numbersarray of strings
An array of phone numbers to use for sending SMS notifications.
max items: 50

Delete a user identified by external ID

Immediately deletes a user.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

external_idstringrequired

Fetch user's push subscriptions

Fetch a user's push subscriptions. Returns a paginated list of web and mobile push subscriptions for all platforms.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_idstringrequired
The user id is the MagicBell user id. Accepts a UUID

Query parameters

pageinteger
The page number of the paginated response. Defaults to 1.
per_pageinteger
The number of items per page. Defaults to 20.

Delete user's push subscription

Delete a user's push subscriptions. Identifies the user by the user's ID and the push subscription by the subscription's ID.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

user_idstringrequired
The user id is the MagicBell user id. Accepts a UUID
subscription_idstringrequired
ID of the subscription. The ID of a subscription can be obtained from the "Fetch user subscriptions" API endpoint or from push events sent to the MagicBell React library.

Push subscriptions


The push subscription object

Attributes

idstring
user_idstring
device_tokenstring
platformstring
created_atstring
discarded_atnullable string

Register a device token for a user

Register a device token for push notifications.

Please keep in mind that mobile push notifications will be delivered to this device only if the channel is configured and enabled.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Request body

push_subscription.device_tokenstringrequired
Token that identifies the device. This is usually generated automatically by your app once installed.
max length: 255
push_subscription.platformstringrequired
The platform where the device token was generated from. This value is used to determine the delivery mechanism for mobile push notifications. Either 'ios', 'android' or 'safari'.
min length: 3
push_subscription.app_bundle_idstring
The bundle ID of your app. This value is used to determine the delivery mechanism for mobile push notifications based on your workflow so that you can link several mobile applications to one project.
max length: 155

List user's device tokens

Returns the list of device tokens registered for push notifications.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Delete user's device token

Deletes the registered device token to remove the mobile push subscription.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

device_tokenstringrequired
Token of the device you want to remove

Notification preferences


The notification preference object

Attributes

categoriesarray of objects

Update user notification preferences

Update a user's notification preferences. These preferences will be applied only to channels you enabled for your project.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Request body

notification_preferences.categoriesarray of objects

Fetch user notification preferences

Fetch a user's notification preferences. If a user does not disable a channel explicitly, we would send notifications through that channel as long as your project is enabled.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Subscriptions


Create a topic subscription

Set a user's subscription status to subscribed for a particular topic (and optional categories). If the user previously unsubscribed, the user will be resubscribed.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Request body

subscription.categoriesarray of objectsrequired
A list of hashes containing the category slug and the reason for the subscription
subscription.topicstringrequired
The topic the user should be subscribed to. If the topic does not exist it will be created.

Fetch user's topic subscriptions

Fetch a user's topic subscriptions.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Unsubscribe from a topic

Unusbscribe a user from a particular topic (and optional categories).

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

topicstring
The topic for which we'd like to filter topic subscriptions.

Request body

subscription.categoriesarray of objectsrequired
A list of hashes containing the category slug and the reason for the subscription

Show a topic subscription

Show a user's subscription status for a particular topic and categories.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

topicstring
The topic for which we'd like to filter topic subscriptions.

Delete topic subscription(s)


HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-user-external-idstring
ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.
x-magicbell-user-emailstring
Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.
x-magicbell-user-hmacstring
HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

Path parameters

topicstring
The topic for which we'd like to filter topic subscriptions.

Request body

categoriesarray of objects
A list of hashes containing the category slug and the reason for the subscription. Omiting categories deletes all topic subscriptions beloning to the topic.

Imports


Create a import

Enqueues an import - currently only supported for users. Amongst other things, the users import allows associating slack channels (if you have already setup the oauth apps).

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Request body

import.usersarray of objects

Get the status of an import

Query the status of the import for a summary of imported records and failures for each record that could not be imported successfully.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

import_idstringrequired
ID of the import. The ID of the import is returned when the import is created.

Metrics


The metric object

Attributes

metrics2D array of integers
labelsarray of strings
schemaobject

Get notification metrics

Query the metrics of broadcasts and their recipients.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

import_idstringrequired
ID of the import. The ID of the import is returned when the import is created.

Get notification metrics grouped by category

Query the metrics of broadcasts and their recipients, grouped by category.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

import_idstringrequired
ID of the import. The ID of the import is returned when the import is created.

Get notification metrics grouped by topic

Query the metrics of broadcasts and their recipients, grouped by topic.

HTTP headers

x-magicbell-api-keystringrequired
The (public) API key of your MagicBell project.
x-magicbell-api-secretstringrequired
The API secret of your MagicBell project.

Path parameters

import_idstringrequired
ID of the import. The ID of the import is returned when the import is created.