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.

While the API key of your project can be distributed freely, do not publish the API secret.

Admin operations

All API requests that perform an admin operation (like fetch all users or create notifications) require:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGIBCELL-API-SECRET header containing your MagicBell project's API secret
curl https://api.magicbell.com/notifications \
  --request POST \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]' \
  --data '{
    "notification": {
      "title": "Ticket assigned to you: Do you offer demos?",
      "recipients": [{
        "email": "richard@example.com"
      }]
    }
  }'

Other operations

Your users can perform some operations over their notifications (like fetch and delete them). All API requests to endpoints that perform these operations require:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGICBELL-USER-EXTERNAL-ID header containing the ID of the user performing the request
  • the X-MAGICBELL-USER-HMAC header containing the computed hash for the user ID
curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-USER-EXTERNAL-ID: [USER_ID]'
  --header 'X-MAGICBELL-USER-HMAC: [USER_ID_HMAC]'

On the other hand, if you identify users in your app by email, set the X-MAGICBELL-USER-EMAIL header instead:

curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-USER-EMAIL: [USER_EMAIL]'
  --header 'X-MAGICBELL-USER-HMAC: [USER_EMAIL_HMAC]'

Notice that in this scenario, you should use your API secret to compute an HMAC of the user's email, instead of the user's id.

If you set both the email and the external ID in the HTTP headers when performing a request the external ID will take precedence over the email.

If you're yet to turn to HMAC authentication for your MagicBell project, you don't have to provide the X-MAGICBELL-USER-HMAC header. However, we highly recommend turning on HMAC authentication before releasing MagicBell to your users. This will help preventing users from fetching data from other users of your app.

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.

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 your have enabled for your MagicBell project.

HTTP headers

  • X-MAGICBELL-API-KEYrequired

    API key of your MagicBell project.

    string

  • X-MAGICBELL-API-SECRETrequired

    API secret of your MagicBell project.

    string

Body Parameters

    notification.titlerequired

    Title of the notification.

    string

    notification.category

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

    string

    notification.content

    Content of the notification. If you provide HTML content, the notification inbox will render it correctly.

    string

    notification.action_url

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

    string

    notification.recipientsrequired

    Users to send the notification to. You can specify up to 1000 users at once. Use matches to send a notification to everyone.

    array

    notification.custom_attributes

    Set of key-value pairs that you can attach to a notification. 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.topic

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

    string

Fetch notifications

Fetch a user's notifications

HTTP headers

  • X-MAGICBELL-API-KEYrequired

    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 a notification

Fetch a user's notification by its ID.

HTTP headers

  • X-MAGICBELL-API-KEYrequired

    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

    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

    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

    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

    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

    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

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

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

    API key of your MagicBell project.

    string

  • X-MAGICBELL-API-SECRETrequired

    API secret of your MagicBell project.

    string

Body Parameters

    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

    user.email

    The user's email

    string

    user.first_name

    The user's first name

    string

    user.last_name

    The user's last name

    string

    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

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

    API key of your MagicBell project.

    string

  • X-MAGICBELL-API-SECRETrequired

    API secret of your MagicBell project.

    string

Body Parameters

    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

    user.email

    The user's email

    string

    user.first_name

    The user's first name

    string

    user.last_name

    The user's last name

    string

    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

Delete a user

Delete a user by id, email or external_id.

We will delete the user completely 7 days after. If the user makes a request to the API, the deletion will be canceled. This will happen when the notification inbox for this user is loaded in your app, for example.

HTTP headers

  • X-MAGICBELL-API-KEYrequired

    API key of your MagicBell project.

    string

  • X-MAGICBELL-API-SECRETrequired

    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

    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.new_message.email

    A flag to enable or disable email messages for this category when a new notification is created.

    boolean

    notification_preferences.categories.new_message.in_app

    Whether to send new notifications to the notification inbox or not.

    boolean

    notification_preferences.categories.new_message.mobile_push

    A flag to enable or disable mobile push notifications for this category when a new notification is created.

    boolean

    notification_preferences.categories.new_message.web_push

    A flag to enable or disable browser push notifications for this category when a new notification is created.

    boolean

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

    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

Register a device

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

    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

    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

    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

Unregister a device

Remove the subscription of a device to mobile push notifications. The device will be discarded immediately.

HTTP headers

  • X-MAGICBELL-API-KEYrequired

    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