MagicBell - REST API Reference

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

GET /broadcasts

curl --request GET \
  --url https://api.magicbell.com/broadcasts \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "per_page": 15,
  "current_page": 1,
  "broadcasts": [
    {
      "id": "d5f4f217-9475-4e47-85a3-b395d8134e8f",
      "title": "Pickup Instructions – In-Store",
      "category": "order_ready",
      "topic": "order:33098",
      "recipients": [
        {
          "external_id": "customer_1"
        },
        {
          "email": "[email protected]",
          "last_name": "Doe",
          "first_name": "Person",
          "phone_numbers": [
            "+31612345678"
          ]
        }
      ],
      "status": {
        "errors": [],
        "status": "processed",
        "summary": {
          "total": 2,
          "failures": 0
        }
      },
      "sent_at": "2023-07-14T07:48:29.098493Z",
      "created_at": "2023-07-14T07:48:29.098493Z"
    }
  ]
}

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

GET /broadcasts/{broadcast_id}

curl --request GET \
  --url https://api.magicbell.com/broadcasts/%7Bbroadcast_id%7D \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "broadcast": {
    "id": "d5f4f217-9475-4e47-85a3-b395d8134e8f",
    "title": "Pickup Instructions – In-Store",
    "category": "order_ready",
    "topic": "order:33098",
    "recipients": [
      {
        "external_id": "customer_1"
      },
      {
        "email": "[email protected]",
        "last_name": "Doe",
        "first_name": "Person",
        "phone_numbers": [
          "+31612345678"
        ]
      }
    ],
    "status": {
      "errors": [],
      "status": "processed",
      "summary": {
        "total": 2,
        "failures": 0
      }
    },
    "sent_at": "2023-07-14T07:48:29.098493Z",
    "created_at": "2023-07-14T07:48:29.098493Z"
  }
}

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

GET /broadcasts/{broadcast_id}/notifications

curl --request GET \
  --url https://api.magicbell.com/broadcasts/%7Bbroadcast_id%7D/notifications \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "per_page": 100,
  "current_page": 1,
  "notifications": [
    {
      "id": "4e2e236a-4538-4466-a9d6-30489e910b1f",
      "title": "Your order is ready for pickup",
      "category": null,
      "topic": "order:33098",
      "created_at": "2023-07-14T07:48:29.356351Z",
      "updated_at": "2023-07-14T07:48:29.767895Z",
      "sent_at": "2023-07-14T07:48:29.098493Z",
      "recipient": {
        "user": {
          "id": "501db41e-8780-4173-976d-169899f14f93",
          "email": "[email protected]",
          "external_id": null,
          "first_name": "Person",
          "last_name": "Doe"
        }
      },
      "read_at": null,
      "seen_at": null,
      "status": "unseen",
      "archived_at": null,
      "discarded_at": null,
      "deliveries": [
        {
          "id": "14bf943c-3fb5-4bc3-9dc4-6ed6ab716d58",
          "channel": "sms",
          "status": "sent",
          "scheduled_at": "2023-07-14T07:48:29.560412Z",
          "title": "Your order is ready for pickup"
        },
        {
          "id": "802aaa0e-579b-403e-a872-3bb3e114eb5d",
          "channel": "email",
          "status": "sent",
          "scheduled_at": "2023-07-14T07:48:29.560412Z",
          "title": "Your order is ready for pickup"
        },
        {
          "id": "57178bac-58d7-474c-9d2d-ca8c441fefad",
          "channel": "web_push",
          "status": "sent",
          "scheduled_at": "2023-07-14T07:48:29.560412Z",
          "title": "Your order is ready for pickup"
        },
        {
          "id": "48ecd2dd-afda-438d-921d-3010c74c2b35",
          "channel": "mobile_push",
          "status": "sent",
          "scheduled_at": "2023-07-14T07:48:29.560412Z",
          "title": "Your order is ready for pickup"
        },
        {
          "id": "7d4d820f-5e74-4af6-877a-bdf3f725c754",
          "channel": "in_app",
          "status": "sent",
          "scheduled_at": "2023-07-14T07:48:29.560412Z",
          "title": "Your order is ready for pickup"
        }
      ]
    }
  ]
}

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

POST /notifications

{
  "notification": {
    "title": "We're processing your order",
    "content": "<p>Thank you for your order. We'll notify you when these items are ready.</p>",
    "category": "order_created",
    "topic": "order:33098",
    "recipients": [
      {
        "email": "[email protected]"
      },
      {
        "external_id": "83d987a-83fd034",
        "first_name": "Hana",
        "last_name": "Mohan",
        "custom_attributes": {
          "plan": "enterprise",
          "pricing_version": "v10",
          "preferred_pronoun": "She"
        },
        "phone_numbers": [
          "+15005550001"
        ]
      },
      {
        "matches": "custom_attributes.order.id = 88492"
      }
    ],
    "overrides": {
      "email": {
        "title": "[MagicBell] We're processing your order",
        "content": "Thank you for your order. If you need help, or have any questions please don't hesitate to reach out to us directly at [email protected]"
      }
    }
  }
}

Responses

201
{
  "notification": {
    "id": "ffffff66-ea4f-4da2-afc6-84148b51657a",
    "title": "We're processing your order",
    "content": "<p>Thank you for your order. We'll notify you when these items are ready.</p>",
    "action_url": null,
    "category": "order_created",
    "topic": "order:33098",
    "custom_attributes": null,
    "sent_at": 1625853246
  }
}

422
{
  "errors": [
    {
      "message": "The request was unacceptable due to invalid or missing data."
    }
  ]
}

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

GET /notifications

curl --request GET \
  --url https://api.magicbell.com/notifications \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]'

Responses

200
{
  "project_id": 83,
  "unseen_count": 1,
  "unread_count": 2,
  "total": 2,
  "total_pages": 1,
  "per_page": 15,
  "current_page": 1,
  "notifications": [
    {
      "id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
      "title": "Pickup Instructions – In-Store",
      "action_url": "https://magicbell.com/pricing",
      "content": "<ul><li>Bring your valid government-issued photo ID.</li></ul>",
      "category": "order_ready",
      "topic": "order:33098",
      "custom_attributes": {
        "order_number": "W846MD",
        "part_number": "MRJL74/C"
      },
      "recipient": {
        "id": "dd1502be-1d07-4906-8217-38dbe4c6ea6b",
        "email": "[email protected]",
        "external_id": null,
        "last_name": null,
        "custom_attributes": {}
      },
      "seen_at": null,
      "sent_at": 1601549080,
      "read_at": null,
      "archived_at": 1625852784
    },
    {
      "id": "6ed53e8e-0b07-4354-8b56-44ea3ea0816c",
      "title": "[Billing] Action required to prevent account suspension",
      "action_url": "https://magicbell.com",
      "content": "Unfortunately we were unable to automatically renew your account. It looks like we had trouble processing your credit card.",
      "category": "billing",
      "topic": null,
      "custom_attributes": {
        "sender": {
          "name": "George Taylor",
          "email": "[email protected]"
        }
      },
      "recipient": {
        "id": "dd1502be-1d07-4906-8217-38dbe4c6ea6b",
        "email": "[email protected]",
        "external_id": null,
        "first_name": null,
        "last_name": null,
        "custom_attributes": {}
      },
      "seen_at": 1601388747,
      "sent_at": 1601388730,
      "read_at": null,
      "archived_at": 1625852012
    }
  ]
}

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

GET /notifications/{notification_id}

curl --request GET \
  --url https://api.magicbell.com/notifications/7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]'

Responses

200
{
  "notification": {
    "id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
    "title": "Your Check-in Window to pick up Order W771201863",
    "action_url": "https://magicbell.com/blog/notification-system-design",
    "content": "<p>We look forward to seeing you during your Check-in Window. Please bring your valid government-issued photo ID.</p>",
    "category": "order_ready",
    "topic": "order:33098",
    "custom_attributes": {
      "encoding": "utf-8",
      "word_count": "500"
    },
    "recipient": {
      "id": "dd1502be-1d07-4906-8217-38dbe4c6ea6b",
      "email": "[email protected]",
      "external_id": null,
      "first_name": null,
      "last_name": null,
      "custom_attributes": {}
    },
    "seen_at": null,
    "sent_at": 1601549080,
    "read_at": null,
    "archived_at": 1625852784
  }
}

404
{
  "errors": [
    {
      "message": "A resource with the the given id doesn't exist"
    }
  ]
}

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

GET /users

curl --request GET \
  --url https://api.magicbell.com/users \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "current_page": 1,
  "total_pages": 1,
  "total": 1,
  "per_page": 100,
  "users": [
    {
      "id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
      "external_id": "56780",
      "email": "[email protected]",
      "first_name": "Hana",
      "last_name": "Mohan",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "She"
      }
    },
    {
      "id": "7fb3ce9f-a866-4dff-8ce8-2f79f7c5ddc",
      "external_id": "",
      "email": "[email protected]",
      "first_name": "Example",
      "last_name": "Mc'Example",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "She"
      },
      "phone_numbers": [
        "+15005550001"
      ]
    }
  ]
}

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

GET /users/{user_id}/notifications

curl --request GET \
  --url https://api.magicbell.com/users/358fc24b-5f18-44e2-8613-8d554ce7d614/notifications \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "per_page": 15,
  "current_page": 1,
  "notifications": [
    {
      "id": "d1131e8f-c60b-4fa4-abc7-2ca3f19cddb4",
      "title": "You have a new message",
      "category": null,
      "topic": null,
      "created_at": "2022-12-22T10:36:13.792718Z",
      "updated_at": "2022-12-22T10:36:13.942176Z",
      "sent_at": "2022-12-22T10:36:13.672902Z",
      "recipient": {
        "user": {
          "id": "0d46ed50-ae34-488b-a32f-ad8887e22aa0",
          "email": "[email protected]",
          "external_id": null,
          "first_name": "Person",
          "last_name": "Doe"
        }
      },
      "read_at": null,
      "seen_at": null,
      "status": "unseen",
      "archived_at": null,
      "discarded_at": null,
      "deliveries": [
        {
          "id": "54980355-f813-43aa-a4e2-8e744adb32e6",
          "channel": "sms",
          "status": "sent",
          "scheduled_at": "2022-12-22T10:36:13.846195Z",
          "title": "You have a new message"
        },
        {
          "id": "90f9fcd1-21fa-4bd6-a076-33b2787cba1f",
          "channel": "email",
          "status": "sent",
          "scheduled_at": "2022-12-22T10:36:13.846195Z",
          "title": "You have a new message"
        },
        {
          "id": "f9f28331-4c03-48c8-b2b7-276a2250a4df",
          "channel": "web_push",
          "status": "sent",
          "scheduled_at": "2022-12-22T10:36:13.846195Z",
          "title": "You have a new message"
        },
        {
          "id": "7d5f136a-1f83-4d41-b8b6-cca1793113a2",
          "channel": "mobile_push",
          "status": "sent",
          "scheduled_at": "2022-12-22T10:36:13.846195Z",
          "title": "You have a new message"
        },
        {
          "id": "7bd247da-4a2d-47d9-947e-4416b63da63a",
          "channel": "in_app",
          "status": "sent",
          "scheduled_at": "2022-12-22T10:36:13.846195Z",
          "title": "You have a new message"
        }
      ]
    }
  ]
}

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

PUT /users/email:{user_email}

{
  "user": {
    "external_id": "56780",
    "email": "[email protected]",
    "first_name": "Hana",
    "last_name": "Mohan",
    "custom_attributes": {
      "plan": "enterprise",
      "pricing_version": "v10",
      "preferred_pronoun": "She"
    },
    "phone_numbers": [
      "+15005550001"
    ]
  }
}

Responses

200
{
  "user": {
    "id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
    "external_id": "56780",
    "email": "[email protected]",
    "first_name": "Hana",
    "last_name": "Mohan",
    "custom_attributes": {
      "plan": "enterprise",
      "pricing_version": "v10",
      "preferred_pronoun": "She"
    }
  }
}

404
{
  "errors": [
    {
      "message": "A resource with the the given id doesn't exist"
    }
  ]
}

422
{
  "errors": [
    {
      "message": "The request was unacceptable due to invalid or missing data."
    }
  ]
}

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

PUT /users/external_id:{external_id}

{
  "user": {
    "external_id": "56780",
    "email": "[email protected]",
    "first_name": "Hana",
    "last_name": "Mohan",
    "custom_attributes": {
      "plan": "enterprise",
      "pricing_version": "v10",
      "preferred_pronoun": "She"
    },
    "phone_numbers": [
      "+15005550001"
    ]
  }
}

Responses

200
{
  "user": {
    "id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
    "external_id": "56780",
    "email": "[email protected]",
    "first_name": "Hana",
    "last_name": "Mohan",
    "custom_attributes": {
      "plan": "enterprise",
      "pricing_version": "v10",
      "preferred_pronoun": "She"
    }
  }
}

404
{
  "errors": [
    {
      "message": "A resource with the the given id doesn't exist"
    }
  ]
}

422
{
  "errors": [
    {
      "message": "The request was unacceptable due to invalid or missing data."
    }
  ]
}

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

PUT /notification_preferences

{
  "notification_preferences": {
    "categories": [
      {
        "slug": "billing",
        "channels": [
          {
            "slug": "email",
            "enabled": false
          },
          {
            "slug": "web_push",
            "enabled": false
          }
        ]
      }
    ]
  }
}

Responses

200
{
  "notification_preferences": {
    "categories": [
      {
        "slug": "billing",
        "label": "Billing",
        "channels": [
          {
            "slug": "email",
            "label": "Email",
            "enabled": false
          },
          {
            "slug": "web_push",
            "label": "Web Push",
            "enabled": false
          },
          {
            "slug": "mobile_push",
            "label": "Mobile Push",
            "enabled": false
          }
        ]
      }
    ]
  }
}

404
{
  "errors": [
    {
      "message": "A resource with the the given id doesn't exist"
    }
  ]
}

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

GET /notification_preferences

curl --request GET \
  --url https://api.magicbell.com/notification_preferences \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]'

Responses

200
{
  "notification_preferences": {
    "categories": [
      {
        "slug": "billing",
        "label": "Billing",
        "channels": [
          {
            "slug": "email",
            "label": "Email",
            "enabled": true
          },
          {
            "slug": "web_push",
            "label": "Web Push",
            "enabled": false
          },
          {
            "slug": "mobile_push",
            "label": "Mobile Push",
            "enabled": false
          }
        ]
      },
      {
        "slug": "new_reply",
        "label": "New reply",
        "channels": [
          {
            "slug": "email",
            "label": "Email",
            "enabled": true
          },
          {
            "slug": "web_push",
            "label": "Web Push",
            "enabled": true
          },
          {
            "slug": "mobile_push",
            "label": "Mobile Push",
            "enabled": true
          }
        ]
      }
    ]
  }
}

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

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

POST /imports

{
  "import": {
    "users": [
      {
        "external_id": "ugiabqertz",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "custom_attributes": {
          "age": 32,
          "country": "Spain"
        },
        "channels": {
          "slack": {
            "providers": [
              {
                "oauth": {
                  "channel_id": "U039446XF3Y",
                  "app": {
                    "app_id": "your_slack_app_id",
                    "team_id": "workspace_id_from_slack"
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Responses

201
{
  "import": {
    "id": "67e839ab-98a8-48cf-9bcb-12d2b906c9c3",
    "status": "processing",
    "summary": {},
    "errors": []
  }
}

422
{
  "errors": [
    {
      "message": "The request was unacceptable due to invalid or missing data."
    }
  ]
}

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 /imports/{import_id}

curl --request GET \
  --url https://api.magicbell.com/imports/%7Bimport_id%7D \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "import": {
    "id": "90200969-fcc7-4dee-b62f-928cc3b226d9",
    "status": "processed",
    "summary": {
      "total": 1,
      "failures": 1
    },
    "failures": {
      "users": [
        {
          "email": "invalidEmail",
          "external_id": null,
          "errors": {
            "email": [
              "must be an email address"
            ],
            "channels": {
              "slack": {
                "providers": {
                  "0": {
                    "oauth": {
                      "app": {
                        "app_id": [
                          "could not find the slack app"
                        ]
                      }
                    }
                  },
                  "1": {
                    "oauth": {
                      "app": {
                        "app_id": [
                          "could not find the slack app"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      ]
    }
  }
}

404
{
  "errors": [
    {
      "message": "A resource with the the given id doesn't exist"
    }
  ]
}

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

curl --request GET \
  --url https://api.magicbell.com/metrics \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]'

Responses

200
{
  "metrics": [
    [
      0,
      0,
      0
    ],
    [
      2,
      2,
      2
    ],
    [
      0,
      0,
      0
    ]
  ],
  "labels": [
    "2023-07-18T00:00:00Z",
    "2023-07-19T00:00:00Z",
    "2023-07-20T00:00:00Z"
  ],
  "schema": {
    "metric": [
      {
        "entity": "broadcast",
        "operation": "count"
      },
      {
        "entity": "notification",
        "operation": "count"
      },
      {
        "entity": "user",
        "operation": "count"
      }
    ],
    "label": {
      "name": "day",
      "type": "timestamp"
    }
  }
}

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