REST API Reference

Broadcasts

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

The broadcast object

Attributes

idstring

The unique id for this broadcast.

titlestring

Title of the broadcast.

max length: 255

contentnullable string

Content of the broadcast.

max length: 4194304

action_urlnullable string

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

max length: 2048

categorynullable string

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

max length: 100

topicnullable string

Topic the notification belongs to. This is useful for creating threads or offering topic level unsubscriptions.

max length: 100

custom_attributesnullable object

Nested key-value attributes that can be used for rendering in templates in MagicBell or third-party providers. Limited to 256KB - please see Overrides for another way to send channel specific data.

JSON Schema
{
  "type": "object",
  "additionalProperties": false,
  "description": "A broadcast is a precursor to a notification. When you specify multiple recipients, MagicBell creates a notification for each recipient and delivers it to them based on their preferences.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique id for this broadcast.",
      "readOnly": true
    },
    "title": {
      "type": "string",
      "description": "Title of the broadcast.",
      "nullable": false,
      "maxLength": 255
    },
    "content": {
      "type": "string",
      "description": "Content of the broadcast.",
      "nullable": true,
      "maxLength": 4194304
    },
    "action_url": {
      "type": "string",
      "format": "uri",
      "description": "A URL to redirect the user to when they click the notification in their notification inbox.",
      "nullable": true,
      "maxLength": 2048
    },
    "category": {
      "type": "string",
      "description": "Category the notification belongs to. This is useful to allow users to set their preferences.",
      "nullable": true,
      "maxLength": 100
    },
    "topic": {
      "type": "string",
      "description": "Topic the notification belongs to. This is useful for creating threads or offering topic level unsubscriptions.",
      "nullable": true,
      "maxLength": 100
    },
    "custom_attributes": {
      "type": "object",
      "description": "Nested key-value attributes that can be used for rendering in templates in MagicBell or third-party providers. Limited to 256KB - please see Overrides for another way to send channel specific data.",
      "nullable": true,
      "additionalProperties": true
    },
    "sent_at": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the notification was sent to its recipients.",
      "readOnly": true,
      "nullable": true
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp when the notification was created.",
      "readOnly": true
    },
    "recipients": {
      "type": "array",
      "description": "Users to send the notification to. You can specify up to 1000 users in the request body. Recipient objects need to have at least one of the following attributes: email, external_id, matches, topic.",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "topic"
            ],
            "properties": {
              "topic": {
                "type": "object",
                "description": "The topic to deliver to.",
                "nullable": false,
                "required": [
                  "subscribers"
                ],
                "additionalProperties": false,
                "properties": {
                  "subscribers": {
                    "type": "boolean",
                    "description": "Setting this property triggers delivery to topic subscribers, respecting their unsubscriptions.",
                    "nullable": false
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "matches"
            ],
            "properties": {
              "matches": {
                "type": "string",
                "description": "An expression to match users by their stored attributes. Set it to `*` to match all users.",
                "nullable": false
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": true,
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string",
                "format": "email",
                "description": "The identifying email of the recipient.",
                "nullable": false
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": true,
            "required": [
              "external_id"
            ],
            "properties": {
              "external_id": {
                "type": "string",
                "description": "The identifying external_id of the recipient.",
                "nullable": false
              }
            }
          }
        ]
      },
      "nullable": false,
      "minItems": 1,
      "maxItems": 1000
    },
    "overrides": {
      "type": "object",
      "additionalProperties": true
    },
    "status": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "status",
        "summary",
        "errors"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "enqueued",
            "processing",
            "processed"
          ],
          "readOnly": true,
          "nullable": false
        },
        "summary": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "total",
            "failures"
          ],
          "properties": {
            "total": {
              "type": "integer",
              "description": "The number of recipients that the broadcast was sent to.",
              "readOnly": true,
              "nullable": false
            },
            "failures": {
              "type": "integer",
              "description": "The number of failures while processing the broadcast.",
              "readOnly": true,
              "nullable": false
            }
          }
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "required": [
    "id",
    "title",
    "created_at",
    "recipients",
    "status"
  ]
}

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

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

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

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Request body

broadcast.titlestringrequired

Title of the broadcast.

max length: 255

broadcast.contentnullable string

Content of the broadcast.

max length: 4194304

broadcast.action_urlnullable string

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

max length: 2048

broadcast.recipientsarray of objectsrequired

Users to send the notification to. You can specify up to 1000 users in the request body.

min items: 1

max items: 1000

broadcast.custom_attributesnullable object

Nested key-value attributes that can be used for rendering in templates in MagicBell or third-party providers. Limited to 256KB - please see Overrides for another way to send channel specific data.

broadcast.categorynullable string

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

max length: 100

broadcast.topicnullable string

Topic the notification belongs to. This is useful for creating threads or offering topic level unsubscriptions.

max length: 100

POST /broadcasts

{
  "broadcast": {
    "title": "We're processing your order",
    "content": "Thank you for your order. We'll notify you when these items are ready.",
    "category": "order_created",
    "topic": "order:33098",
    "recipients": [
      {
        "email": "[email protected]"
      },
      {
        "external_id": "83d987a-83fd034",
        "first_name": "Person",
        "last_name": "Doe",
        "custom_attributes": {
          "plan": "enterprise",
          "pricing_version": "v10",
          "preferred_pronoun": "They"
        },
        "phone_numbers": [
          "+1 5005550001"
        ]
      }
    ],
    "overrides": {
      "channels": {
        "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]"
        }
      }
    }
  }
}

Response — HTTP 201
{
  "broadcast": {
    "id": "ffffff66-ea4f-4da2-afc6-84148b51657a",
    "title": "We're processing your order",
    "content": "Thank you for your order. We'll notify you when these items are ready.",
    "action_url": null,
    "category": "order_created",
    "topic": "order:33098",
    "custom_attributes": null,
    "created_at": "2023-10-31T14:18:52.105289128Z",
    "sent_at": "2023-10-31T14:18:52.105289128Z",
    "recipients": [
      {
        "email": "[email protected]"
      }
    ],
    "status": {
      "errors": [],
      "status": "enqueued",
      "summary": {
        "total": 0,
        "failures": 0
      }
    }
  }
}

List broadcasts

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Query parameters

pageinteger

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

per_pageinteger

The number of items per page. Defaults to 20.

GET /broadcasts

magicbell broadcasts list

Response — HTTP 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 broadcast by its ID

Fetch a broadcast by its ID.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

broadcast_idstringrequired

ID of the broadcast.

GET /broadcasts/{broadcast_id}

magicbell broadcasts get d5f4f217-9475-4e47-85a3-b395d8134e8f

Response — HTTP 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 for a broadcast.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

broadcast_idstringrequired

ID of the broadcast.

Query parameters

pageinteger

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

per_pageinteger

The number of items per page. Defaults to 20.

GET /broadcasts/{broadcast_id}/notifications

magicbell broadcasts notifications list d5f4f217-9475-4e47-85a3-b395d8134e8f

Response — HTTP 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"
        }
      ]
    }
  ]
}

Notifications

The notification object

Attributes

idstring

The unique id for this notification.

titlestring

Title of the notification.

max length: 255

contentnullable string

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

action_urlnullable string

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

max length: 2048

categorynullable string

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

max length: 100

topicnullable string

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

max length: 100

custom_attributesnullable object

Set of key-value pairs that you can attach to a notification, 6KB at maximum. It accepts objects for the value of a key. You can use it to share data between channels or to render a custom UI.

JSON Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique id for this notification.",
      "readOnly": true
    },
    "title": {
      "type": "string",
      "description": "Title of the notification.",
      "nullable": false,
      "maxLength": 255
    },
    "content": {
      "type": "string",
      "description": "Content of the notification. If you provide HTML content, the notification inbox will render it correctly. It should not exceed 4MB.",
      "nullable": true
    },
    "action_url": {
      "type": "string",
      "format": "uri",
      "description": "A URL to redirect the user to when they click the notification in their notification inbox.",
      "nullable": true,
      "maxLength": 2048
    },
    "category": {
      "type": "string",
      "description": "Category the notification belongs to. This is useful to allow users to set their preferences.",
      "nullable": true,
      "maxLength": 100
    },
    "topic": {
      "type": "string",
      "description": "Topic the notification belongs to. This is useful to create threads.",
      "nullable": true,
      "maxLength": 100
    },
    "custom_attributes": {
      "type": "object",
      "description": "Set of key-value pairs that you can attach to a notification, 6KB at maximum. It accepts objects for the value of a key.\n\nYou can use it to share data between channels or to render a custom UI.",
      "nullable": true,
      "additionalProperties": true
    },
    "sent_at": {
      "type": "number",
      "description": "The timestamp when the notification was sent to its recipients.",
      "readOnly": true
    }
  },
  "required": [
    "id",
    "title",
    "sent_at"
  ]
}

Fetch notifications for a user

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Query parameters

per_pageinteger

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

pageinteger

A parameter for use in pagination. Defaults to 1.

readboolean

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

seenboolean

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

archivedboolean

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

categorystring

A filter on the notifications based on the category. If you want to get uncategorized notifications, use the "uncategorized" value.

topicstring

A filter on the notifications based on the topic.

GET /notifications

magicbell user notifications list \
  --user-email "[email protected]"

Response — HTTP 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": "Bring your valid government-issued photo ID.",
      "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-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Path parameters

notification_idstringrequired

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

GET /notifications/{notification_id}

magicbell user notifications get 7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c \
  --user-email "[email protected]"

Response — HTTP 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": "We look forward to seeing you during your Check-in Window. Please bring your valid government-issued photo ID.",
    "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
  }
}

readboolean

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

seenboolean

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

categorystring

A filter on the notifications based on the category. If you want to get uncategorized notifications, use the "uncategorized" value.

topicstring

A filter on the notifications based on the topic.

Mark all notifications as seen
real-time

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Query parameters

archivedboolean

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

readboolean

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

seenboolean

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

categorystring

A filter on the notifications based on the category. If you want to get uncategorized notifications, use the "uncategorized" value.

topicstring

A filter on the notifications based on the topic.

Users

The user object

Attributes

idstring

The unique id for this user.

external_idnullable string

A unique string that MagicBell can utilize to identify the user uniquely. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.

max length: 255

emailnullable string

The user's email.

max length: 255

first_namenullable string

The user's first name.

max length: 50

last_namenullable string

The user's last name.

max length: 50

custom_attributesobject

Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.

phone_numbersarray of strings

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

max items: 50

JSON Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique id for this user.",
      "readOnly": true
    },
    "external_id": {
      "type": "string",
      "description": "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.",
      "maxLength": 255,
      "nullable": true
    },
    "email": {
      "type": "string",
      "description": "The user's email.",
      "maxLength": 255,
      "nullable": true
    },
    "first_name": {
      "type": "string",
      "description": "The user's first name.",
      "maxLength": 50,
      "nullable": true
    },
    "last_name": {
      "type": "string",
      "description": "The user's last name.",
      "maxLength": 50,
      "nullable": true
    },
    "custom_attributes": {
      "type": "object",
      "description": "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.",
      "additionalProperties": true
    },
    "phone_numbers": {
      "type": "array",
      "description": "An array of phone numbers to use for sending SMS notifications.",
      "items": {
        "type": "string"
      },
      "maxItems": 50
    }
  }
}

Create a user

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

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Request body

user.idstring

The unique id for this user.

user.external_idnullable string

max length: 255

user.emailnullable string

The user's email.

max length: 255

user.first_namenullable string

The user's first name.

max length: 50

user.last_namenullable string

The user's last name.

max length: 50

user.custom_attributesobject

Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.

user.phone_numbersarray of strings

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

max items: 50

POST /users

{
  "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"
    ]
  }
}

Response — HTTP 201
{
  "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"
    }
  }
}

Fetch users

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Query parameters

pageinteger

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

per_pageinteger

The number of items per page. Defaults to 20.

last_seen_at:beforestring

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

last_seen_at:afterstring

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

last_notified_at:beforestring

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

last_notified_at:afterstring

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

order_byenum

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

Possible enum values:

created_at,ASC

created_at,DESC

last_seen_at,ASC

last_seen_at,DESC

last_notified_at,ASC

last_notified_at,DESC

GET /users

magicbell users list

Response — HTTP 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-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_idstringrequired

The user id is the MagicBell user id. Alternatively, provide an id like email:[email protected] or external_id:theusersexternalid as the user id.

Request body

user.idstring

The unique id for this user.

user.external_idnullable string

max length: 255

user.emailnullable string

The user's email.

max length: 255

user.first_namenullable string

The user's first name.

max length: 50

user.last_namenullable string

The user's last name.

max length: 50

user.custom_attributesobject

Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.

user.phone_numbersarray of strings

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

max items: 50

PUT /users/{user_id}

{
  "user": {
    "email": "[email protected]"
  }
}

Response — HTTP 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"
    }
  }
}

Get user by ID

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_idstringrequired

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

GET /users/{user_id}

magicbell users get 9ef00589-dee8-497b-8a90-60c839638414

Response — HTTP 200
{
  "user": {
    "id": "7c784822-2bac-4df5-951e-6be0cc9e5bfb",
    "external_id": "56780",
    "email": "[email protected]",
    "first_name": "Hana",
    "last_name": "Mohan",
    "custom_attributes": {
      "plan": "enterprise",
      "pricing_version": "v10",
      "preferred_pronoun": "She"
    }
  }
}

Delete a user

Immediately deletes a user.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_idstringrequired

The user id is the MagicBell user id. Alternatively, provide an id like email:[email protected] or external_id:theusersexternalid as the user id.

Fetch notifications by user id.

Fetch the notifications and deliveries for a user.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_idstringrequired

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

Query parameters

pageinteger

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

per_pageinteger

The number of items per page. Defaults to 20.

GET /users/{user_id}/notifications

magicbell users notifications list 9ef00589-dee8-497b-8a90-60c839638414

Response — HTTP 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-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_emailstringrequired

Request body

user.idstring

The unique id for this user.

user.external_idnullable string

max length: 255

user.emailnullable string

The user's email.

max length: 255

user.first_namenullable string

The user's first name.

max length: 50

user.last_namenullable string

The user's last name.

max length: 50

user.custom_attributesobject

Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.

user.phone_numbersarray of strings

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

max items: 50

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"
    ]
  }
}

Response — HTTP 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"
    }
  }
}

Delete a user identified by email

Immediately deletes a user.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_emailstringrequired

Update a user identified by external ID

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

external_idstringrequired

Request body

user.idstring

The unique id for this user.

user.external_idnullable string

max length: 255

user.emailnullable string

The user's email.

max length: 255

user.first_namenullable string

The user's first name.

max length: 50

user.last_namenullable string

The user's last name.

max length: 50

user.custom_attributesobject

Any customer attributes that you'd like to associate with the user. You may want to use these attributes later when writing email templates, for example.

user.phone_numbersarray of strings

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

max items: 50

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"
    ]
  }
}

Response — HTTP 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"
    }
  }
}

Delete a user identified by external ID

Immediately deletes a user.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

external_idstringrequired

Fetch user's push subscriptions

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

user_idstringrequired

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

Query parameters

pageinteger

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

per_pageinteger

The number of items per page. Defaults to 20.

GET /users/{user_id}/push_subscriptions

magicbell users push-subscriptions list 9ef00589-dee8-497b-8a90-60c839638414

Response — HTTP 200
{
  "current_page": 1,
  "per_page": 10,
  "push_subscriptions": [
    {
      "id": "f80a7574-b309-4395-bb26-c503fe697d52",
      "user_id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
      "device_token": "x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV",
      "platform": "ios",
      "created_at": "2021-03-01T12:00:00.000Z",
      "discarded_at": null
    }
  ]
}

Push subscriptions

The push subscription object

Attributes

idstring

user_idstring

device_tokenstring

platformstring

created_atstring

discarded_atnullable string

JSON Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    },
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "device_token": {
      "type": "string"
    },
    "platform": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "discarded_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    }
  }
}

Register a device token for a user

Register a device token for push notifications.

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Request body

push_subscription.device_tokenstringrequired

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

max length: 255

push_subscription.platformstringrequired

The platform where the device token was generated from. This value is used to determine the delivery mechanism for mobile push notifications. Either 'ios', 'android' or 'safari'.

min length: 3

push_subscription.app_bundle_idstring

The bundle ID of your app. This value is used to determine the delivery mechanism for mobile push notifications based on your workflow so that you can link several mobile applications to one project.

max length: 155

POST /push_subscriptions

{
  "push_subscription": {
    "device_token": "x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV",
    "platform": "ios"
  }
}

Response — HTTP 201
{
  "push_subscription": {
    "id": "f80a7574-b309-4395-bb26-c503fe697d52",
    "device_token": "x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV",
    "platform": "ios"
  }
}

List user's device tokens

Returns the list of device tokens registered for push notifications.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

GET /push_subscriptions

magicbell user push-subscriptions list \
  --user-email "[email protected]"

Response — HTTP 200
{
  "current_page": 1,
  "per_page": 10,
  "push_subscriptions": [
    {
      "id": "f80a7574-b309-4395-bb26-c503fe697d52",
      "user_id": "7fb3ce9f-a866-4dff-8ce8-2f64f7c5ed4c",
      "device_token": "x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV",
      "platform": "ios",
      "created_at": "2021-03-01T12:00:00.000Z",
      "discarded_at": null
    }
  ]
}

Delete user's device token

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Path parameters

device_tokenstringrequired

Token of the device you want to remove

Notification preferences

The notification preference object

Attributes

categoriesarray of objects

JSON Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "categories": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "label": {
            "type": "string",
            "description": "The label of the category"
          },
          "slug": {
            "type": "string",
            "description": "The slug of the category."
          },
          "channels": {
            "description": "Preferences for each channel for this category.",
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "label": {
                  "type": "string",
                  "description": "The label of the channel"
                },
                "slug": {
                  "type": "string",
                  "description": "The slug of the channel."
                },
                "enabled": {
                  "type": "boolean",
                  "description": "The current state of the channel."
                }
              }
            }
          }
        }
      }
    }
  }
}

Update user notification preferences

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Request body

notification_preferences.categoriesarray of objects

PUT /notification_preferences

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

Response — HTTP 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
          }
        ]
      }
    ]
  }
}

Fetch user notification preferences

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

GET /notification_preferences

magicbell user notification-preferences get \
  --user-email "[email protected]"

Response — HTTP 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
          }
        ]
      }
    ]
  }
}

Subscriptions

Create a topic subscription

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Request body

subscription.categoriesarray of objectsrequired

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

subscription.topicstringrequired

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

POST /subscriptions

{
  "subscription": {
    "categories": [
      {
        "slug": "comments",
        "reason": "watching-the-repo"
      }
    ],
    "topic": "acme-inc.orders.1234"
  }
}

Response — HTTP 200
{
  "subscription": {
    "categories": [
      {
        "slug": "comments",
        "reason": "watching-the-repo",
        "status": "subscribed"
      }
    ],
    "topic": "acme-inc.orders.1234"
  }
}

Fetch user's topic subscriptions

Fetch a user's topic subscriptions.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

GET /subscriptions

magicbell user subscriptions list \
  --user-email "[email protected]"

Response — HTTP 200
{
  "subscriptions": [
    {
      "categories": [
        {
          "slug": "updates",
          "reason": "watching-the-order",
          "status": "unsubscribed"
        },
        {
          "slug": "comments",
          "reason": "watching-the-order",
          "status": "unsubscribed"
        }
      ],
      "topic": "acme-inc.orders.1234"
    },
    {
      "categories": [
        {
          "slug": "comments",
          "reason": "watching-the-order",
          "status": "unsubscribed"
        }
      ],
      "topic": "acme-inc.orders.2345"
    }
  ]
}

Unsubscribe from a topic

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Path parameters

topicstring

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

Request body

subscription.categoriesarray of objectsrequired

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

POST /subscriptions/{topic}/unsubscribe

{
  "subscription": {
    "categories": [
      {
        "slug": "comments"
      }
    ]
  }
}

Response — HTTP 200
{
  "subscription": {
    "categories": [
      {
        "slug": "comments",
        "reason": "watching-the-repo",
        "status": "unsubscribed"
      }
    ],
    "topic": "acme-inc.orders.1234"
  }
}

Show a topic subscription

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Path parameters

topicstring

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

GET /subscriptions/{topic}

magicbell user subscriptions get  \
  --user-email "[email protected]"

Response — HTTP 200
{
  "subscription": {
    "categories": [
      {
        "slug": "comments",
        "reason": "watching-the-repo",
        "status": "unsubscribed"
      }
    ],
    "topic": "acme-inc.orders.1234"
  }
}

Delete topic subscription(s)

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-user-external-idstring

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

x-magicbell-user-emailstring

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

x-magicbell-user-hmacstring

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

Path parameters

topicstring

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

Request body

categoriesarray of objects

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

Imports

Create a import

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Request body

import.usersarray of objects

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"
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}

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

Get the status of an import

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

import_idstringrequired

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

GET /imports/{import_id}

magicbell imports get

Response — HTTP 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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      ]
    }
  }
}

Metrics

The metric object

Attributes

metrics2D array of integers

labelsarray of strings

schemaobject

JSON Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "metrics",
    "labels",
    "schema"
  ],
  "properties": {
    "metrics": {
      "type": "array",
      "nullable": false,
      "items": {
        "type": "array",
        "items": {
          "type": "integer"
        }
      }
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "metric",
        "label"
      ],
      "properties": {
        "metric": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "entity",
              "operation"
            ],
            "properties": {
              "entity": {
                "type": "string"
              },
              "operation": {
                "type": "string",
                "enum": [
                  "count",
                  "avg",
                  "sum",
                  "min",
                  "max"
                ]
              }
            }
          }
        },
        "label": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "name",
            "type"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "enum": [
                "timestamp",
                "string"
              ]
            }
          }
        }
      }
    }
  }
}

Get notification metrics

Query the metrics of broadcasts and their recipients.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

import_idstringrequired

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

GET /metrics

magicbell metrics get

Response — HTTP 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 broadcasts and their recipients, grouped by category.

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

import_idstringrequired

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

GET /metrics/categories

magicbell metrics categories get

Response — HTTP 200
{
  "metrics": [
    [
      37,
      37,
      31
    ],
    [
      243,
      298,
      49
    ]
  ],
  "labels": [
    "member_invited",
    "new_message"
  ],
  "schema": {
    "metric": [
      {
        "entity": "broadcast",
        "operation": "count"
      },
      {
        "entity": "notification",
        "operation": "count"
      },
      {
        "entity": "user",
        "operation": "count"
      }
    ],
    "label": {
      "name": "category",
      "type": "string"
    }
  }
}

Get notification metrics grouped by topic

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

HTTP headers

x-magicbell-api-keystringrequired

The (public) API key of your MagicBell project.

x-magicbell-api-secretstringrequired

The API secret of your MagicBell project.

Path parameters

import_idstringrequired

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

GET /metrics/topics

magicbell metrics topics get

Response — HTTP 200
{
  "metrics": [
    [
      84,
      123,
      53
    ],
    [
      7,
      12,
      12
    ]
  ],
  "labels": [
    "thread.23",
    "thread.48"
  ],
  "schema": {
    "metric": [
      {
        "entity": "broadcast",
        "operation": "count"
      },
      {
        "entity": "notification",
        "operation": "count"
      },
      {
        "entity": "user",
        "operation": "count"
      }
    ],
    "label": {
      "name": "topic",
      "type": "string"
    }
  }
}

REST API Reference

Attributes

Create broadcastsreal-time

HTTP headers

Request body

HTTP headers

Query parameters

HTTP headers

Path parameters

HTTP headers

Path parameters

Query parameters

Attributes

HTTP headers

Query parameters

HTTP headers

Path parameters

Delete a notificationreal-time

HTTP headers

Path parameters

Mark a notification as readreal-time

HTTP headers

Path parameters

Mark a notification as unreadreal-time

HTTP headers

Path parameters

Archive a notificationreal-time

HTTP headers

Path parameters

Unarchive a notificationreal-time

HTTP headers

Path parameters

Mark all notifications as readreal-time

HTTP headers

Query parameters

Mark all notifications as seenreal-time

HTTP headers

Query parameters

Attributes

HTTP headers

Request body

HTTP headers

Query parameters

HTTP headers

Path parameters

Request body

HTTP headers

Path parameters

HTTP headers

Path parameters

HTTP headers

Path parameters

Query parameters

HTTP headers

Path parameters

Request body

HTTP headers

Path parameters

HTTP headers

Path parameters

Request body

HTTP headers

Path parameters

HTTP headers

Path parameters

Query parameters

Attributes

HTTP headers

Request body

HTTP headers

HTTP headers

Path parameters

Attributes

HTTP headers

Request body

HTTP headers

HTTP headers

Request body

HTTP headers

HTTP headers

Create broadcasts
real-time

Delete a notification
real-time

Mark a notification as read
real-time

Mark a notification as unread
real-time

Archive a notification
real-time

Unarchive a notification
real-time

Mark all notifications as read
real-time

Mark all notifications as seen
real-time