REST API Reference

Explore the MagicBell REST API

Authentication

The MagicBell REST API utilizes an HTTP header based authentication using your MagicBell's project's API key and secret. Your MagicBell project's API key and secret are available in the "Settings" section of your MagicBell Admin Dashboard. Please see the authentication page.

List notification broadcasts

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Query parameters

  • page

    The page number of the paginated response. Defaults to 1.

    integer
  • per_page

    The number of items per page. Defaults to 20.

    integer

Fetch a notification broadcast by its ID

Fetch a notification broadcast by its ID.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Fetch notifications by broadcast id.

Fetch the notifications on a notification broadcast.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Query parameters

  • page

    The page number of the paginated response. Defaults to 1.

    integer
  • per_page

    The number of items per page. Defaults to 20.

    integer

Create notifications

real-time

Send a notification to one or multiple users. 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 notification.

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Body Parameters

    notification.titleRequired

    Title of the notification.

    string
    Max length: 255

    notification.content

    Content of the notification. If you provide HTML content, the notification inbox will render it correctly. It should not exceed 4MB.

    string

    notification.action_url

    A URL to redirect the user to when they click the notification in their notification inbox.

    string
    Max length: 2048

    notification.recipientsRequired

    Users to send the notification to. You can specify up to 1000 users in the request body or use [matches](https://www.magicbell.com/docs/segments#how-to-create-segments-using-the-api) to send a notification to any number of users.

    array
    Max items: 1000
    Min items: 1

    notification.custom_attributes

    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.

    object

    notification.category

    Category the notification belongs to. This is useful to allow users to set their preferences.

    string
    Max length: 100

    notification.topic

    Topic the notification belongs to. This is useful to create threads.

    string
    Max length: 100

Fetch notifications

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Query parameters

  • per_page

    A limit on the number of notifications to be returned. It can range between 1 and 100, and the default is 15.

    integer
  • page

    A parameter for use in pagination. Defaults to 1.

    integer
  • read

    A filter on the notifications based on the read state. If false, only unread notifications will be returned. Defaults to null.

    boolean
  • seen

    A filter on the notifications based on the seen state. If false, only unseen notifications will be returned. Defaults to null.

    boolean
  • archived

    A filter on the notifications based on the archived state. If false, only unarchived notifications will be returned. Defaults to null.

    boolean
  • categories

    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.

    array
  • topics

    A filter on the notifications based on the topic.

    array

Fetch notification by ID

Fetch a user's notification by its ID.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Archive a notification

real-time

Mark a user notification as archived.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Unarchive a notification

real-time

Mark a user notification as unarchived.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Query parameters

  • archived

    A filter on the notifications based on the archived state. Specify false to select unarchived notifications. Defaults to null.

    boolean
  • read

    A filter on the notifications based on the read state. Specify false to select unread notifications. Defaults to null.

    boolean
  • seen

    A filter on the notifications based on the seen state. Specify false to select unseen notifications. Defaults to null.

    boolean
  • categories

    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.

    array
  • topics

    A filter on the notifications based on the topic.

    array

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Query parameters

  • archived

    A filter on the notifications based on the archived state. Specify false to select unarchived notifications. Defaults to null.

    boolean
  • read

    A filter on the notifications based on the read state. Specify false to select unread notifications. Defaults to null.

    boolean
  • seen

    A filter on the notifications based on the seen state. Specify false to select unseen notifications. Defaults to null.

    boolean
  • categories

    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.

    array
  • topics

    A filter on the notifications based on the topic.

    array

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Body Parameters

    user.id

    The unique id for this user.

    string

    user.external_id

    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.

    string
    Max length: 255

    user.email

    The user's email.

    string
    Max length: 255

    user.first_name

    The user's first name.

    string
    Max length: 50

    user.last_name

    The user's last name.

    string
    Max length: 50

    user.custom_attributes

    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.

    object

    user.phone_numbers

    An array of phone numbers to use for sending SMS notifications.

    array
    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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Query parameters

  • page

    The page number of the paginated response. Defaults to 1.

    integer
  • per_page

    The number of items per page. Defaults to 20.

    integer
  • last_seen_at:before

    Fetch users seen before the specified `last_seen_at` timestamp. Please send it in RFC3339 format

    string
  • last_seen_at:after

    Fetch users seen after the specified `last_seen_at` timestamp. Please send it in RFC3339 format

    string
  • last_notified_at:before

    Fetch users last notified before the specified `last_notified_at` timestamp. Please send it in RFC3339 format

    string
  • last_notified_at:after

    Fetch users last notified after the specified `last_notified_at` timestamp. Please send it in RFC3339 format

    string
  • order_by

    Use it to order the returned list of users. Defaults to `created_at,DESC`

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Body Parameters

    user.id

    The unique id for this user.

    string

    user.external_id

    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.

    string
    Max length: 255

    user.email

    The user's email.

    string
    Max length: 255

    user.first_name

    The user's first name.

    string
    Max length: 50

    user.last_name

    The user's last name.

    string
    Max length: 50

    user.custom_attributes

    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.

    object

    user.phone_numbers

    An array of phone numbers to use for sending SMS notifications.

    array
    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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Delete a user

Immediately deletes a user.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Fetch notifications by user id.

Fetch the notifications and deliveries for a user.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Query parameters

  • page

    The page number of the paginated response. Defaults to 1.

    integer
  • per_page

    The number of items per page. Defaults to 20.

    integer

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Body Parameters

    user.id

    The unique id for this user.

    string

    user.external_id

    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.

    string
    Max length: 255

    user.email

    The user's email.

    string
    Max length: 255

    user.first_name

    The user's first name.

    string
    Max length: 50

    user.last_name

    The user's last name.

    string
    Max length: 50

    user.custom_attributes

    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.

    object

    user.phone_numbers

    An array of phone numbers to use for sending SMS notifications.

    array
    Max items: 50

Delete a user identified by email

Immediately deletes a user.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Body Parameters

    user.id

    The unique id for this user.

    string

    user.external_id

    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.

    string
    Max length: 255

    user.email

    The user's email.

    string
    Max length: 255

    user.first_name

    The user's first name.

    string
    Max length: 50

    user.last_name

    The user's last name.

    string
    Max length: 50

    user.custom_attributes

    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.

    object

    user.phone_numbers

    An array of phone numbers to use for sending SMS notifications.

    array
    Max items: 50

Delete a user identified by external ID

Immediately deletes a user.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Body Parameters

    push_subscription.device_tokenRequired

    Token that identifies the device. This is usually generated automatically by your app once installed.

    string
    Max length: 255

    push_subscription.platformRequired

    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'.

    string
    Min length: 3

    push_subscription.app_bundle_id

    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.

    string
    Max length: 155

List user's device tokens

Returns the list of device tokens registered for push notifications.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Delete user's device token

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Query parameters

  • page

    The page number of the paginated response. Defaults to 1.

    integer
  • per_page

    The number of items per page. Defaults to 20.

    integer

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Body Parameters

    notification_preferences.categories

    array

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Body Parameters

    subscription.categoriesRequired

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

    array

    subscription.topicRequired

    The topic the user should be subscribed to. If the topic does not exist it will be created.

    string

Fetch user's topic subscriptions

Fetch a user's topic subscriptions.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Unsubscribe from a topic

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Body Parameters

    subscription.categoriesRequired

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

    array

Show a topic subscription

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Delete topic subscription(s)

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    string
  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    string
  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    string

Body Parameters

    categories

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

    array

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Body Parameters

    import.users

    array

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-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Get notification metrics

Query the metrics of notification broadcasts and their recipients.

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Get notification metrics grouped by category

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string

Get notification metrics grouped by topic

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

HTTP headers

  • X-MAGICBELL-API-KEYRequired

    The (public) API key of your MagicBell project.

    string
  • X-MAGICBELL-API-SECRETRequired

    The API secret of your MagicBell project.

    string