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

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 your 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 at once. Use matches to send a notification to everyone.

    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

    Max length: 6000

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

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

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

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

    Max length: 6000

    user.phone_numbers

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

    array

    Max items: 50

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

    Max length: 6000

    user.phone_numbers

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

    array

    Max items: 50

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

Update a user 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.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

    Max length: 6000

    user.phone_numbers

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

    array

    Max items: 50

Delete a user 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 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.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

    Max length: 6000

    user.phone_numbers

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

    array

    Max items: 50

Delete a user 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

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

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

    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

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

    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 project in a workspace

Creates a project in a workspace.

This feature is available to Enterprise customers — get in touch with us, and we'll provide the credentials for you.

HTTP headers

  • Authorizationrequired

    The Bearer JWT token of your MagicBell user.

    string

Body Parameters

    project.name

    Project Name

    string

    Max length: 255

    project.hmac_enabled

    True when hmac is enabled for a project

    boolean

Fetch all projects in a workspace

HTTP headers

  • Authorizationrequired

    The Bearer JWT token of your MagicBell user.

    string

Update a project in a workspace

Updates a project in a workspace.

This feature is available to Enterprise customers — get in touch with us, and we'll provide the credentials for you.

HTTP headers

  • Authorizationrequired

    The Bearer JWT token of your MagicBell user.

    string

Body Parameters

    project.name

    Project Name

    string

    Max length: 255

    project.hmac_enabled

    True when hmac is enabled for a project

    boolean

Fetch a project in a workspace

This feature is available to Enterprise customers — get in touch with us, and we'll provide the credentials for you.

HTTP headers

  • Authorizationrequired

    The Bearer JWT token of your MagicBell user.

    string

Delete a project in a workspace

Deletes a project in a workspace.

This feature is available to Enterprise customers — get in touch with us, and we'll provide the credentials for you.

HTTP headers

  • Authorizationrequired

    The Bearer JWT token of your MagicBell user.

    string