This package provides a convenient interface to query the MagicBell API. Note that some methods depend on your secret key, those methods are not to be used in browsers, as your secret key must be kept secret.
Requirements
Node 18.13 or higher.
When using older versions, you might need to polyfill fetch
. See isomorphic-fetch for more information.
You also might need to polyfill eventsource
when using the listen
method in an environment that doesn't support it. See eventsource for more information.
Installation
Install the package with npm:
shellnpm install magicbell --save
or yarn:
shellyarn add magicbell
Usage
The package needs to be configured with your project's secret key & api key, which are available in the MagicBell Dashboard.
jsimport { ProjectClient } from 'magicbell/project-client';
const magicbell = new ProjectClient({
apiKey: 'your-api-key',
apiSecret: 'your-api-secret',
});
try {
const broadcast = await magicbell.broadcasts.create({
title: 'Sweet!',
content: 'When you see it, you know it!',
recipients: [{ email: 'customer@example.com' }],
});
console.log(broadcast.id);
} catch (error) {
console.error(error);
}
or go old-school with require and promises:
jsconst { ProjectClient } = require('magicbell/project-client');
const magicbell = new ProjectClient({
apiKey: 'your-api-key',
apiSecret: 'your-api-secret',
});
magicbell.broadcasts
.create({
title: 'Sweet!',
content: 'When you see it, you know it!',
recipients: [{ email: 'customer@example.com' }],
})
.then((broadcast) => console.log(broadcast.id))
.catch((error) => console.error(error));
Some endpoints, like notifications.list
are user scoped, and can be consumed via a user specific client, authenticated using apiKey
and userEmail
or apiKey
and userExternalId
option.
jsimport { UserClient } from 'magicbell/user-client';
const magicbell = new UserClient({
apiKey: 'your-api-key',
userEmail: 'you@example.com',
});
const notifications = await magicbell.notifications.list();
Note that every resource method accepts an optional options
object, which can be used to override client defaults and pass additional options to the request.
This can for example be used to increase the network timeout.
jsconst johnsPreferences = await magicbell.notificationPreferences.list({
timeout: 30_000,
});
Using Promises
Every method returns a promise.
jsconst user = await magicbell.users.create({
email: 'person@example.com',
first_name: 'Person',
last_name: 'Doe',
});
List methods return iterable promises and the response can be handled in different ways:
standard promise - this method requires manual iteration to fetch multiple pages.
jsconst firstPage = await magicbell.notifications.list();
// firstPage: { page: 1, total_pages: 5, notifications: [{ id: '…', title: '…', … }, …], … }
const nextPage = await magicbell.notifications.list({ page: firstPage.current_page + 1 });
async iterator - this iterates over all items across multiple pages. Call break
when you wish to step out of the iteration / auto fetching.
jsfor await (const notification of magicbell.notifications.list()) {
console.log(notification.title);
// break to abort and stop fetching/iterating
if (shouldStop()) break;
}
forEach - similar to the iterator, but in a callback style fashion. Return false
when you wish to step out of the iteration / auto fetching.
jsawait magicbell.notifications.list().forEach((notification) => {
console.log(notification.title);
// return false to abort and stop fetching/iterating
if (shouldStop()) return false;
});
toArray - all items across multiple pages are fetched and returned in a single array. This method cannot be cancelled half way, and requires a limit to be set to prevent your process from running out of memory. Use the iterators above if you need to fetch lots of data.
jsconst notifications = await magicbell.notifications.list().toArray({ limit: 1000 });
Configuration
Initialize with config object
The package can be initialized with several options, and in two scopes. There's an project client, and a user client.
Project Scope
The project client is used to make requests on behalf of the project, and requires the apiKey
and apiSecret
options to be set.
jsimport { ProjectClient } from 'magicbell/project-client';
const magicbell = new ProjectClient({
// auth
apiKey: 'your-api-key', // required
apiSecret: 'your-secret-key', // required
// network
timeout: 30_000,
maxRetries: 3,
maxRetryDelay: 60,
telemetry: true,
});
User Scope
The user client is used to make requests on behalf of a user, and requires the apiKey
and one of userEmail
or userExternalId
options to be set. If your project has HMAC enabled, the userHmac
option is also required. As no apiSecret
is needed, this client is suitable for client side usage and safe to be used in the browser.
jsimport { UserClient } from 'magicbell/user-client';
const magicbell = new UserClient({
// auth
apiKey: 'your-api-key', // required
userEmail: 'you@example.com', // required if userExternalId is not set
userExternalId: 'your-external-id', // required if userEmail is not set
userHmac: 'your-user-hmac', // required if HMAC is enabled
// network
timeout: 30_000,
maxRetries: 3,
maxRetryDelay: 60,
telemetry: true,
});
Options
- host String
The current refresh token.
- apiKey String
Your project api key which can be found on the MagicBell Dashboard. This key is required for all calls.
- apiSecret String [project client only]
Your project api secret which can be found on the MagicBell Dashboard. This key is required for project scoped endpoints.
- userEmail String [user client only]
The email of the user you want to make requests for. This key is required for user scoped endpoints when no userExternalId
is set.
- userExternalId String [user client only]
The external-id of the user you want to make requests for. This key is required for user scoped endpoints when no userEmail
is set.
- userHmac String [user client only]
The HMAC of the user you want to make requests for. This key is required for user scoped endpoints when HMAC is enabled.
- timeout Number
A network timeout in milliseconds. Defaults to 30 seconds. Network requests will be canceled if they take longer than this.
- maxRetries Number
The maximum number of times to retry a request. Defaults to 3. Set to 0 to disable retries.
- maxRetryDelay Number
The maximum time in milliseconds to wait between retry requests. Note that subsequent retries can have a longer total duration than this. Defaults to 60 seconds.
- telemetry Boolean
Each request - after the first - includes a header with the response time of the previous request. This helps us to improve the performance of the API. You can opt out of this by setting this option to false
.
- features Record<string, boolean>
A map of feature flags to get access to beta features. See Feature Flags for more information.
- headers Record<string, string>
Custom headers you wish to include on the request, for example to instruct your proxy servers or to decorate your logs.
Configuring Timeout
Timeout can be set globally via the config object:
jsconst magicbell = new MagicBell({
// ...
timeout: 20_000, // 20 seconds
});
And overridden on a per-request basis:
jsmagicbell.notifications.create(
{ title: 'Hi there!' },
{ timeout: 1_000 }, // 1 second
);
Network retries
Automatic network retries can be configured with the maxRetries
option. This will retry network requests - with an exponential backoff - when it makes sense to retry them. For example, a request that failed due to a network error will be retried, but a request that failed due to an invalid API key or incorrect data will not.
Note
Automatic retries are meant to handle short network disturbances. They're handled in-process, and don't use a persistent job queue. They won't survive process restarts. You might need to implement your own persistent workers with retry logic if delivery is crucial to your business.
We'll automatically add idempotency keys if you haven't provided on, to prevent duplication.
A request that was retried, will take longer, but looks exactly the same as a direct success to the caller. The caller will not be notified that a request was retried.
jsconst magicbell = new MagicBell({
maxRetries: 2, // Retry a request twice before giving up
});
Network retries can also be set on a per-request basis:
jsmagicbell.notifications.create(
{ recipients: [{ email: 'person@example.com' }] },
{ maxRetries: 2 }, // Retry this specific request twice before giving up
);
Using in a package
If you're wrapping our SDK, or using it in a specific app, we'd appreciate it if you instantiated your MagicBell client with appInfo
, eg;
jsconst magicbell = new MagicBell({
apiKey: '...',
appInfo: {
name: 'MyAwesomePlugin',
version: '1.2.34', // Optional
url: 'https://myawesomeplugin.info', // Optional
},
});
Request latency telemetry
By default, the library sends request latency telemetry to MagicBell. These numbers help us to improve the overall latency of our API for all users.
You can disable this behavior if you prefer:
jsconst magicbell = new MagicBell({
telemetry: false,
});
Feature Flags
Features that in beta or early release are "hidden" behind a feature flag. You can enable them by passing a features
object to the config, provided with a key for each feature that you wish to enable.
Note that these features are behind a flag for a reason. They may change or be removed at any time and are not covered by our semantic versioning (semver) policy.
jsconst magicbell = new MagicBell({
features: {
'a-new-beta-feature': true,
},
});
Below is a list of features that are currently behind feature flags.
There are no features in beta at this time.
Resource Methods
The SDK is divided in two scopes. Project Resources, and User Resources. Below you'll find the all supported resource methods, with their signatures. The full documentation can be found in our api-reference. When comparing the api-reference with these methods, you'll notice that the SDK removes any wrapping entities for your convenience. Meaning, instead of posting { notification: { title: 'hi' } }
, you'll call create({ title: 'hi' })
.
Apart from the removal of the wrappers, returned entities and provided parameters are identical between our REST API and this SDK.
Project Resource Methods
The project scope contains everything you need to manage your project and send notifications. You'll need to be authenticated using apiKey
and apiSecret
to use these methods.
jsimport { ProjectClient } from 'magicbell/project-client';
const magicbell = new ProjectClient({
apiKey: 'your-api-key', // required
apiSecret: 'your-secret-key', // required
});
Broadcasts
Create broadcasts
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.
jsawait magicbell.broadcasts.create({
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: 'dan@example.com',
},
{
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 hello@magicbell.com",
},
},
},
});
List broadcasts
List all broadcasts. Broadcasts are sorted in descending order by the sent_at timestamp.
jsawait magicbell.broadcasts.list({
page: 1,
per_page: 1,
});
Fetch a broadcast by its ID
Fetch a broadcast by its ID.
jsawait magicbell.broadcasts.get('{broadcast_id}');
Broadcasts Notifications
Fetch notifications by broadcast id.
Fetch the notifications for a broadcast.
jsawait magicbell.broadcasts.notifications.list('{broadcast_id}', {
page: 1,
per_page: 1,
});
Users
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.
jsawait magicbell.users.create({
external_id: '56780',
email: 'hana@supportbee.com',
first_name: 'Hana',
last_name: 'Mohan',
custom_attributes: {
plan: 'enterprise',
pricing_version: 'v10',
preferred_pronoun: 'She',
},
phone_numbers: ['+15005550001'],
});
Fetch users
Fetches users for the project identified by the auth keys. Supports filtering, ordering, and pagination.
jsawait magicbell.users.list({
page: 1,
per_page: 1,
'last_seen_at:before': '…',
'last_seen_at:after': '…',
'last_notified_at:before': '…',
'last_notified_at:after': '…',
order_by: '…',
});
Get user by ID
Fetch a user by id, for the project identified by the auth keys.
jsawait magicbell.users.get('{user_id}');
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.
jsawait magicbell.users.update('{user_id}', {
email: 'hana@magicbell.io',
});
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.
jsawait magicbell.users.updateByEmail('{user_email}', {
external_id: '56780',
email: 'hana@supportbee.com',
first_name: 'Hana',
last_name: 'Mohan',
custom_attributes: {
plan: 'enterprise',
pricing_version: 'v10',
preferred_pronoun: 'She',
},
phone_numbers: ['+15005550001'],
});
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.
jsawait magicbell.users.updateByExternalId('{external_id}', {
external_id: '56780',
email: 'hana@supportbee.com',
first_name: 'Hana',
last_name: 'Mohan',
custom_attributes: {
plan: 'enterprise',
pricing_version: 'v10',
preferred_pronoun: 'She',
},
phone_numbers: ['+15005550001'],
});
Delete a user
Immediately deletes a user.
jsawait magicbell.users.delete('{user_id}');
Delete a user identified by email
Immediately deletes a user.
jsawait magicbell.users.deleteByEmail('{user_email}');
Delete a user identified by external ID
Immediately deletes a user.
jsawait magicbell.users.deleteByExternalId('{external_id}');
Users Notifications
Fetch notifications by user id.
Fetch the notifications and deliveries for a user.
jsawait magicbell.users.notifications.list('{user_id}', {
page: 1,
per_page: 1,
});
Users Push Subscriptions
Fetch user's push subscriptions
Fetch a user's push subscriptions. Returns a paginated list of web and mobile push subscriptions for all platforms.
jsawait magicbell.users.pushSubscriptions.list('{user_id}', {
page: 1,
per_page: 1,
});
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).
jsawait magicbell.imports.create({
users: [
{
external_id: 'ugiabqertz',
email: 'johndoe@example.com',
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',
},
},
},
],
},
},
},
],
});
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.
jsawait magicbell.imports.get('{import_id}');
Metrics
Get notification metrics
Query the metrics of broadcasts and their recipients.
jsawait magicbell.metrics.get();
Metrics Categories
Get notification metrics grouped by category
Query the metrics of broadcasts and their recipients, grouped by category.
jsawait magicbell.metrics.categories.get();
Metrics Topics
Get notification metrics grouped by topic
Query the metrics of broadcasts and their recipients, grouped by topic.
jsawait magicbell.metrics.topics.get();
User Resource Methods
The user scope contains everything a specific user needs to display their notifications and manage their settings. They'll need to be authenticated using apiKey
, either userEmail
or userExternalId
, and userHmac
when HMAC is enabled on your project.
As you don't need to authenticate using the apiSecret
, this scope is safe to use in the browser.
jsimport { UserClient } from 'magicbell/user-client';
const magicbell = new UserClient({
apiKey: 'your-api-key', // required
userEmail: 'you@example.com', // required if userExternalId is not set
userExternalId: 'your-external-id', // required if userEmail is not set
userHmac: 'your-user-hmac', // required if HMAC is enabled
});
Notifications
Archive a notification
Mark a user notification as archived.
jsawait magicbell.notifications.archive('{notification_id}');
Mark all notifications as read
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.
jsawait magicbell.notifications.markAllRead({
archived: true,
read: true,
seen: true,
category: '…',
topic: '…',
});
Mark all notifications as seen
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.
jsawait magicbell.notifications.markAllSeen({
archived: true,
read: true,
seen: true,
category: '…',
topic: '…',
});
Mark a notification as read
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.
jsawait magicbell.notifications.markAsRead('{notification_id}');
Mark a notification as unread
Mark a user notification as unread. The new state will be reflected in the user's notification inbox in real-time.
jsawait magicbell.notifications.markAsUnread('{notification_id}');
Fetch notifications for a user
Fetch a user's notifications. Notifications are sorted in descending order by the sent_at timestamp.
jsawait magicbell.notifications.list({
per_page: 1,
page: 1,
read: true,
seen: true,
archived: true,
category: '…',
topic: '…',
});
Fetch notification by ID
Fetch a user's notification by its ID.
jsawait magicbell.notifications.get('{notification_id}');
Delete a notification
Delete a user's notification by its ID. The notification is deleted immediately and removed from the user's notification inbox in real-time.
jsawait magicbell.notifications.delete('{notification_id}');
Unarchive a notification
Mark a user notification as unarchived.
jsawait magicbell.notifications.unarchive('{notification_id}');
Push Subscriptions
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.
jsawait magicbell.pushSubscriptions.create({
device_token: 'x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV',
platform: 'ios',
});
List user's device tokens
Returns the list of device tokens registered for push notifications.
jsawait magicbell.pushSubscriptions.list();
Delete user's device token
Deletes the registered device token to remove the mobile push subscription.
jsawait magicbell.pushSubscriptions.delete('{device_token}');
Notification Preferences
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.
jsawait magicbell.notificationPreferences.get();
Update user notification preferences
Update a user's notification preferences. These preferences will be applied only to channels you enabled for your project.
jsawait magicbell.notificationPreferences.update({
categories: [
{
slug: 'billing',
channels: [
{
slug: 'email',
enabled: false,
},
{
slug: 'web_push',
enabled: false,
},
],
},
],
});
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.
jsawait magicbell.subscriptions.create({
categories: [
{
slug: 'comments',
reason: 'watching-the-repo',
},
],
topic: 'acme-inc.orders.1234',
});
Unsubscribe from a topic
Unusbscribe a user from a particular topic (and optional categories).
jsawait magicbell.subscriptions.unsubscribe('{topic}', {
categories: [
{
slug: 'comments',
},
],
});
Fetch user's topic subscriptions
Fetch a user's topic subscriptions.
jsawait magicbell.subscriptions.list();
Show a topic subscription
Show a user's subscription status for a particular topic and categories.
jsawait magicbell.subscriptions.get('{topic}');
Delete topic subscription(s)
jsawait magicbell.subscriptions.delete('{topic}', {
categories: [
{
slug: 'comments',
},
],
});
jsconst magicbell = new MagicBell({
apiKey: 'your-api-key',
userEmail: 'someone@example.com',
});
magicbell.listen();
async iterator - this iterates over all events. Call break
when you wish to step out of the iteration and stop listening.
jsfor await (const notification of magicbell.listen()) {
console.log(notification.data.id);
// break to abort and stop listening
if (shouldStop()) break;
}
forEach - similar to the iterator, but in a callback style fashion. Return false
when you wish to stop listening.
jsmagicbell.listen().forEach((notification) => {
console.log(notification.data.id);
// return false to abort and stop listening
if (shouldStop()) return false;
});
close - stop listening. This will close the connection and stop the auto-reconnect.
jsconst listener = magicbell.listen();
listener.forEach((notification) => {
console.log(notification.data.id);
});
// stop listening after 5 seconds
setTimeout(() => {
listener.close();
}, 5_000);
Realtime events
The following events are emitted by the client:
event.name | description |
---|---|
notifications/new | a new notification has been created |
notifications/read | a notification has been read |
notifications/unread | a notification has been marked as unread |
notifications/delete | a notification has been deleted |
notifications/read/all | all notifications have been marked as read |
notifications/seen/all | all notifications have been marked as seen |
Realtime with extended data
Note that the realtime listener returns a limited set of data. We do this intentionally, so that the listener stays fast, and doesn't use more bandwidth or battery than necessary. If you need more data, you can complement it using the notification resource method.
jsfor await (let event of client.listen()) {
if ('id' in event.data) {
const notification = await client.notifications.get(event.data.id);
doSomething({ event, notification });
} else {
doSomething({ event });
}
}
Errors
Errors returned by the SDK are instances of MagicBellError
. This is a subclass of the native Error
class, and contains the properties defined below. Error types can be imported from magicbell/errors
.
- message String
A human-readable message providing more details about the error.
- code String
A short machine-readable string identifying the error.
- status Number
The HTTP status code returned by the API.
- statusText String
The HTTP status text returned by the API.
- responseBody unknown
The raw response body returned by the API
- suggestion String
A suggestion to resolve the error.
- docsUrl String
A link to the documentation for the error.
Support
New features and bug fixes are released on the latest major version of the magicbell
package. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.