API (v2) Reference

Introduction

Base URL: https://api.magicbell.com/v2

For authentication, rate limits, and errors, please refer to the API documentation.

Broadcasts

Broadcasts let you fan out an announcement to every relevant user or topic. Use these APIs to create announcements, inspect their status, and audit how they generated notifications and deliveries across your project.

Related guides: Broadcast Primitive
ENDPOINTS
  POST /broadcasts
   GET /broadcasts/{broadcast_id}
   GET /broadcasts

The Broadcasts object

Attributes

action_url
nullable string

The URL recipients will be directed to when interacting with the broadcast.

max length: 2048
category
nullable string

The label used to group broadcasts.

max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
content
nullable string

The body content delivered with the broadcast.

max length: 10485760
created_at
string

The timestamp when the broadcast was created.

format: date-time
custom_attributes
nullable object

Arbitrary custom data associated with the broadcast.

id
string

The unique id for this broadcast.

format: uuid
overrides
nullable object

Channel- or provider-specific values that override the defaults.

Show child attributes
providers
object

Overrides that are scoped to specific providers for a channel.

Show child attributes
sendgrid
object

Provider-specific overrides for Sendgrid.

ses
object

Provider-specific overrides for AWS SES.

apns
object

Provider-specific overrides for Apple Push Notification service.

web_push
object

Provider-specific overrides for the web push provider.

teams
object

Provider-specific overrides for Microsoft Teams.

twilio
object

Provider-specific overrides for Twilio.

mailgun
object

Provider-specific overrides for Mailgun.

fcm
object

Provider-specific overrides for Firebase Cloud Messaging.

expo
object

Provider-specific overrides for Expo push notifications.

slack
object

Provider-specific overrides for Slack.

channels
object

Overrides that are scoped to individual delivery channels.

Show child attributes
sms
object

Overrides for SMS notifications.

Show child attributes
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
title
string

The channel-specific title.

min length: 1
max length: 255
in_app
object

Overrides for in-app notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
mobile_push
object

Overrides for mobile push notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
email
object

Overrides for email notifications.

Show child attributes
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
recipients
nullable array required

A collection of users or filters that determine who receives the broadcast.

min items: 1
max items: 1000
Show child attributes
(array item)

The recipient specification for the broadcast.

status
object

The runtime state of the broadcast execution.

Show child attributes
status
string required

The overall processing status of the broadcast.

Possible enum values:
enqueued
processing
processed
summary
object required

The summary counts for total recipients and failures.

Show child attributes
total
integer required

The number of recipients that the broadcast was sent to.

failures
integer required

The number of failures while processing the broadcast.

errors
nullable array required

A list of errors encountered while processing the broadcast.

Show child attributes
(array item)
object
Show child attributes
message
string

The details about the processing error.

title
string required

The subject or headline that will be shown to recipients.

min length: 1
max length: 255
topic
nullable string

The topic that further classifies the broadcast.

max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
The Broadcasts object
{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "I come from broadcast",
  "action_url": "https://example.com",
  "category": "example",
  "topic": "example",
  "custom_attributes": {},
  "recipients": [
    {
      "external_id": "83d987a-83fd034",
      "email": "test@example.com",
      "first_name": "Person",
      "last_name": "Doe",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "They"
      },
      "phone_numbers": [
        "+1 5005550001"
      ]
    }
  ],
  "overrides": {}
}

Create a broadcast

POST/broadcasts
Project JWT

Creates a new broadcast. When a broadcast is created, it generates individual notifications for relevant users within the project.

Request body

action_url
nullable string

The URL recipients will be directed to when interacting with the broadcast.

max length: 2048
category
nullable string

The label used to group broadcasts.

max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
content
nullable string

The body content delivered with the broadcast.

max length: 10485760
created_at
string

The timestamp when the broadcast was created.

format: date-time
custom_attributes
nullable object

Arbitrary custom data associated with the broadcast.

id
string

The unique id for this broadcast.

format: uuid
overrides
nullable object

Channel- or provider-specific values that override the defaults.

Show child attributes
channels
object

Overrides that are scoped to individual delivery channels.

Show child attributes
sms
object

Overrides for SMS notifications.

Show child attributes
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
title
string

The channel-specific title.

min length: 1
max length: 255
in_app
object

Overrides for in-app notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
mobile_push
object

Overrides for mobile push notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
email
object

Overrides for email notifications.

Show child attributes
title
string

The channel-specific title.

min length: 1
max length: 255
content
string

The channel-specific content.

max length: 1048576
action_url
nullable string

The link associated with the channel-specific notification.

max length: 2048
providers
object

Overrides that are scoped to specific providers for a channel.

Show child attributes
slack
object

Provider-specific overrides for Slack.

web_push
object

Provider-specific overrides for the web push provider.

teams
object

Provider-specific overrides for Microsoft Teams.

sendgrid
object

Provider-specific overrides for Sendgrid.

mailgun
object

Provider-specific overrides for Mailgun.

ses
object

Provider-specific overrides for AWS SES.

twilio
object

Provider-specific overrides for Twilio.

fcm
object

Provider-specific overrides for Firebase Cloud Messaging.

expo
object

Provider-specific overrides for Expo push notifications.

apns
object

Provider-specific overrides for Apple Push Notification service.

recipients
nullable array required

A collection of users or filters that determine who receives the broadcast.

min items: 1
max items: 1000
Show child attributes
(array item)

The recipient specification for the broadcast.

status
object

The runtime state of the broadcast execution.

Show child attributes
status
string required

The overall processing status of the broadcast.

Possible enum values:
enqueued
processing
processed
summary
object required

The summary counts for total recipients and failures.

Show child attributes
total
integer required

The number of recipients that the broadcast was sent to.

failures
integer required

The number of failures while processing the broadcast.

errors
nullable array required

A list of errors encountered while processing the broadcast.

Show child attributes
(array item)
object
Show child attributes
message
string

The details about the processing error.

title
string required

The subject or headline that will be shown to recipients.

min length: 1
max length: 255
topic
nullable string

The topic that further classifies the broadcast.

max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/broadcasts' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"id":"d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b","title":"Hello, World!","content":"I come from broadcast","action_url":"https://example.com","category":"example","topic":"example","custom_attributes":{},"recipients":[{"external_id":"83d987a-83fd034","email":"test@example.com","first_name":"Person","last_name":"Doe","custom_attributes":{"plan":"enterprise","pricing_version":"v10","preferred_pronoun":"They"},"phone_numbers":["+1 5005550001"]}],"overrides":{}}'
Response
{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "I come from broadcast",
  "action_url": "https://example.com",
  "category": "example",
  "topic": "example",
  "custom_attributes": {},
  "recipients": [
    {
      "external_id": "83d987a-83fd034",
      "email": "test@example.com",
      "first_name": "Person",
      "last_name": "Doe",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "They"
      },
      "phone_numbers": ["+1 5005550001"]
    }
  ],
  "overrides": {}
}

Fetch a broadcast

GET/broadcasts/{broadcast_id}
Project JWT

Retrieves detailed information about a specific broadcast by its ID. Includes the broadcast's configuration and current status.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/broadcasts/{broadcast_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "I come from broadcast",
  "action_url": "https://example.com",
  "category": "example",
  "topic": "example",
  "custom_attributes": {},
  "recipients": [
    {
      "external_id": "83d987a-83fd034",
      "email": "test@example.com",
      "first_name": "Person",
      "last_name": "Doe",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "They"
      },
      "phone_numbers": ["+1 5005550001"]
    }
  ],
  "overrides": {}
}

List all broadcasts

GET/broadcasts
Project JWT

Retrieves a paginated list of broadcasts for the project. Returns basic information about each broadcast including its creation time and status.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/broadcasts' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
  "title": "Hello, World!",
  "content": "I come from broadcast",
  "action_url": "https://example.com",
  "category": "example",
  "topic": "example",
  "custom_attributes": {},
  "recipients": [
    {
      "external_id": "83d987a-83fd034",
      "email": "test@example.com",
      "first_name": "Person",
      "last_name": "Doe",
      "custom_attributes": {
        "plan": "enterprise",
        "pricing_version": "v10",
        "preferred_pronoun": "They"
      },
      "phone_numbers": ["+1 5005550001"]
    }
  ],
  "overrides": {}
}
],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Channels

Channels represent the mediums such as Email, Push, SMS, Slack, through which deliveries happen. These routes configure how each channel behaves inside a project, ensuring every notification honors user preferences and branding.

Related guides: Channel Primitive

Mobile Push

APIs dedicated to the Mobile Push channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
ENDPOINTS
   PUT /channels/mobile_push/apns/tokens
   GET /channels/mobile_push/apns/tokens/{token_id}
DELETE /channels/mobile_push/apns/tokens/{token_id}
   GET /channels/mobile_push/apns/tokens
   PUT /channels/mobile_push/expo/tokens
   GET /channels/mobile_push/expo/tokens/{token_id}
DELETE /channels/mobile_push/expo/tokens/{token_id}
   GET /channels/mobile_push/expo/tokens
   PUT /channels/mobile_push/fcm/tokens
   GET /channels/mobile_push/fcm/tokens/{token_id}
DELETE /channels/mobile_push/fcm/tokens/{token_id}
   GET /channels/mobile_push/fcm/tokens

The Mobile Push object

Attributes

app_id
string

The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.

pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
created_at
string required

The timestamp when the token was created.

format: date-time
device_token
string required

The APNs device token to register with MagicBell.

min length: 64
discarded_at
nullable string

The timestamp when the token was discarded, if applicable.

format: date-time
id
string required

The unique identifier for the token.

installation_id
string

The APNs environment this token belongs to. If omitted we assume it targets production.

Possible enum values:
development
production
updated_at
nullable string

The timestamp when the token metadata last changed.

format: date-time
The Mobile Push object
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}

Save an APNs token

PUT/channels/mobile_push/apns/tokens
User JWT

Saves the APNs token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

app_id
string

The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.

pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
device_token
string required

The APNs device token to register with MagicBell.

min length: 64
installation_id
string

The APNs environment this token belongs to. If omitted we assume it targets production.

Possible enum values:
development
production
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'
Response
{
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "installation_id": "development"
}

Fetch an APNs token

GET/channels/mobile_push/apns/tokens/{token_id}
User JWT

Fetches details of a specific APNs token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an APNs token

DELETE/channels/mobile_push/apns/tokens/{token_id}
User JWT

Deletes one of the authenticated user's APNs tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all APNs tokens

GET/channels/mobile_push/apns/tokens
User JWT

Lists all APNs tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Save an Expo token

PUT/channels/mobile_push/expo/tokens
User JWT

Saves the Expo token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

device_token
string required

The Expo push token returned by the Expo client.

min length: 1
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"device_token":"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}'
Response
{
  "device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
}

Fetch an Expo token

GET/channels/mobile_push/expo/tokens/{token_id}
User JWT

Fetches details of a specific Expo token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an Expo token

DELETE/channels/mobile_push/expo/tokens/{token_id}
User JWT

Deletes one of the authenticated user's Expo tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all Expo tokens

GET/channels/mobile_push/expo/tokens
User JWT

Lists all Expo tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Save a FCM token

PUT/channels/mobile_push/fcm/tokens
User JWT

Saves the FCM token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

device_token
string required

The Firebase Cloud Messaging device registration token to associate with the user.

min length: 64
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'
Response
{
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "installation_id": "development"
}

Fetch a FCM token

GET/channels/mobile_push/fcm/tokens/{token_id}
User JWT

Fetches details of a specific FCM token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete a FCM token

DELETE/channels/mobile_push/fcm/tokens/{token_id}
User JWT

Deletes one of the authenticated user's FCM tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all FCM tokens

GET/channels/mobile_push/fcm/tokens
User JWT

Lists all FCM tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

In App

APIs dedicated to the In App channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
ENDPOINTS
   PUT /channels/in_app/inbox/tokens
   GET /channels/in_app/inbox/tokens/{token_id}
DELETE /channels/in_app/inbox/tokens/{token_id}
   GET /channels/in_app/inbox/tokens

The In App object

Attributes

connection_id
nullable string

Realtime connection ID to restrict delivery to a specific Ably connection.

created_at
string required

The timestamp when the token was created.

format: date-time
discarded_at
nullable string

The timestamp when the token was discarded, if applicable.

format: date-time
id
string required

The unique identifier for the token.

token
string required

The in-app inbox token generated for this user.

min length: 64
updated_at
nullable string

The timestamp when the token metadata last changed.

format: date-time
The In App object
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "updated_at": "2021-01-01T00:00:00Z"
}

Save an Inbox token

PUT/channels/in_app/inbox/tokens
User JWT

Saves the Inbox token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

connection_id
nullable string

Realtime connection ID to restrict delivery to a specific Ably connection.

token
string required

The in-app inbox token generated for this user.

min length: 64
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt"}'
Response
{
  "token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt"
}

Fetch an Inbox token

GET/channels/in_app/inbox/tokens/{token_id}
User JWT

Fetches details of a specific Inbox token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an Inbox token

DELETE/channels/in_app/inbox/tokens/{token_id}
User JWT

Deletes one of the authenticated user's Inbox tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all Inbox tokens

GET/channels/in_app/inbox/tokens
User JWT

Lists all Inbox tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Slack

APIs dedicated to the Slack channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
ENDPOINTS
   PUT /channels/slack/magicbell_slackbot/tokens
   GET /channels/slack/magicbell_slackbot/tokens/{token_id}
DELETE /channels/slack/magicbell_slackbot/tokens/{token_id}
   GET /channels/slack/magicbell_slackbot/tokens
   PUT /channels/slack/tokens
   GET /channels/slack/tokens/{token_id}
DELETE /channels/slack/tokens/{token_id}
   GET /channels/slack/tokens

The Slack object

Attributes

created_at
string required

The timestamp when the token was created.

format: date-time
discarded_at
nullable string

The timestamp when the token was discarded, if applicable.

format: date-time
id
string required

The unique identifier for the token.

oauth
object
Show child attributes
channel_id
string required

The ID of the Slack channel this installation is associated with

installation_id
string required

A unique identifier for this Slack workspace installation

scope
string

The OAuth scope granted during installation

updated_at
nullable string

The timestamp when the token metadata last changed.

format: date-time
webhook
object

Obtained directly from the incoming_webhook object in the installation response from the Slack API.

Show child attributes
url
string required

The URL for the incoming webhook from Slack

format: uri
min length: 1
The Slack object
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Save a MagicBell SlackBot token

PUT/channels/slack/magicbell_slackbot/tokens
User JWT

Saves the MagicBell SlackBot token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

oauth
object
Show child attributes
scope
string

The OAuth scope granted during installation

channel_id
string required

The ID of the Slack channel this installation is associated with

installation_id
string required

A unique identifier for this Slack workspace installation

webhook
object

Obtained directly from the incoming_webhook object in the installation response from the Slack API.

Show child attributes
url
string required

The URL for the incoming webhook from Slack

format: uri
min length: 1
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"webhook":{"url":"https://example.com/webhook"}}'
Response
{
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Fetch a MagicBell SlackBot token

GET/channels/slack/magicbell_slackbot/tokens/{token_id}
User JWT

Fetches details of a specific MagicBell SlackBot token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Delete a MagicBell SlackBot token

DELETE/channels/slack/magicbell_slackbot/tokens/{token_id}
User JWT

Deletes one of the authenticated user's MagicBell SlackBot tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all MagicBell SlackBot tokens

GET/channels/slack/magicbell_slackbot/tokens
User JWT

Lists all MagicBell SlackBot tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Save a Slack token

PUT/channels/slack/tokens
User JWT

Saves the Slack token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

oauth
object
Show child attributes
channel_id
string required

The ID of the Slack channel this installation is associated with

installation_id
string required

A unique identifier for this Slack workspace installation

scope
string

The OAuth scope granted during installation

webhook
object

Obtained directly from the incoming_webhook object in the installation response from the Slack API.

Show child attributes
url
string required

The URL for the incoming webhook from Slack

format: uri
min length: 1
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/slack/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"webhook":{"url":"https://example.com/webhook"}}'
Response
{
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Fetch a Slack token

GET/channels/slack/tokens/{token_id}
User JWT

Fetches details of a specific Slack token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/slack/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Delete a Slack token

DELETE/channels/slack/tokens/{token_id}
User JWT

Deletes one of the authenticated user's Slack tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/slack/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all Slack tokens

GET/channels/slack/tokens
User JWT

Lists all Slack tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/slack/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Teams

APIs dedicated to the Teams channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
ENDPOINTS
   PUT /channels/teams/tokens
   GET /channels/teams/tokens/{token_id}
DELETE /channels/teams/tokens/{token_id}
   GET /channels/teams/tokens

The Teams object

Attributes

created_at
string required

The timestamp when the token was created.

format: date-time
discarded_at
nullable string

The timestamp when the token was discarded, if applicable.

format: date-time
id
string required

The unique identifier for the token.

updated_at
nullable string

The timestamp when the token metadata last changed.

format: date-time
webhook
object
Show child attributes
url
string
The Teams object
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}

Save a Teams token

PUT/channels/teams/tokens
User JWT

Saves the Teams token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

webhook
object
Show child attributes
url
string
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/teams/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Fetch a Teams token

GET/channels/teams/tokens/{token_id}
User JWT

Fetches details of a specific Teams token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/teams/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete a Teams token

DELETE/channels/teams/tokens/{token_id}
User JWT

Deletes one of the authenticated user's Teams tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/teams/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all Teams tokens

GET/channels/teams/tokens
User JWT

Lists all Teams tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/teams/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

User Preferences

ENDPOINTS
   PUT /channels/user_preferences
   GET /channels/user_preferences

The User Preferences object

Attributes

categories
array
Show child attributes
(array item)
object
Show child attributes
label
nullable string
max length: 255
channels
array
Show child attributes
(array item)
object
Show child attributes
name
string
enabled
boolean
key
string
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
The User Preferences object
{
  "categories": [
    {
      "key": "category_1",
      "label": "Category 1",
      "channels": [
        {
          "name": "email",
          "label": "Email",
          "enabled": true
        }
      ]
    }
  ]
}

Save channel preferences

PUT/channels/user_preferences
User JWT

Save a user's channel preferences.

Request body

categories
array
Show child attributes
(array item)
object
Show child attributes
label
nullable string
max length: 255
channels
array
Show child attributes
(array item)
object
Show child attributes
name
string
enabled
boolean
key
string
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/user_preferences' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"categories":[{"key":"category_1","label":"Category 1","channels":[{"name":"email","label":"Email","enabled":true}]}]}'
Response
{}

Fetch channel preferences

GET/channels/user_preferences
User JWT

Fetch a user's channel delivery preferences.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/user_preferences' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "categories": [
      {
        "key": "category_1",
        "label": "Category 1",
        "channels": [
          {
            "name": "email",
            "label": "Email",
            "enabled": true
          }
        ]
      }
    ]
  }

Web Push

APIs dedicated to the Web Push channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
ENDPOINTS
   PUT /channels/web_push/tokens
   GET /channels/web_push/tokens/{token_id}
DELETE /channels/web_push/tokens/{token_id}
   GET /channels/web_push/tokens

The Web Push object

Attributes

created_at
string required

The timestamp when the token was created.

format: date-time
discarded_at
nullable string

The timestamp when the token was discarded, if applicable.

format: date-time
endpoint
string required

The push subscription URL obtained from PushSubscription.endpoint after calling registration.pushManager.subscribe(). This is the unique URL for this device that push messages will be sent to.

format: uri
id
string required

The unique identifier for the token.

keys
object required

The encryption keys from the PushSubscription.getKey() method, needed to encrypt push messages for this subscription.

Show child attributes
auth
string required

The authentication secret obtained from PushSubscription.getKey('auth'). Used to encrypt push messages for this subscription.

p256dh
string required

The P-256 ECDH public key obtained from PushSubscription.getKey('p256dh'). Used to encrypt push messages for this subscription.

updated_at
nullable string

The timestamp when the token metadata last changed.

format: date-time
The Web Push object
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "id": "123",
  "keys": {
    "auth": "GoIO2ulhtQuyBM64lZuFuw",
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
  },
  "updated_at": "2021-01-01T00:00:00Z"
}

Save a Web Push token

PUT/channels/web_push/tokens
User JWT

Saves the Web Push token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.

Request body

endpoint
string required

The push subscription URL obtained from PushSubscription.endpoint after calling registration.pushManager.subscribe(). This is the unique URL for this device that push messages will be sent to.

format: uri
keys
object required

The encryption keys from the PushSubscription.getKey() method, needed to encrypt push messages for this subscription.

Show child attributes
auth
string required

The authentication secret obtained from PushSubscription.getKey('auth'). Used to encrypt push messages for this subscription.

p256dh
string required

The P-256 ECDH public key obtained from PushSubscription.getKey('p256dh'). Used to encrypt push messages for this subscription.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/channels/web_push/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"endpoint":"https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN","keys":{"p256dh":"BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0","auth":"GoIO2ulhtQuyBM64lZuFuw"}}'
Response
{
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "keys": {
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0",
    "auth": "GoIO2ulhtQuyBM64lZuFuw"
  }
}

Fetch a Web Push token

GET/channels/web_push/tokens/{token_id}
User JWT

Fetches details of a specific Web Push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/web_push/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "id": "123",
  "keys": {
    "auth": "GoIO2ulhtQuyBM64lZuFuw",
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
  },
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete a Web Push token

DELETE/channels/web_push/tokens/{token_id}
User JWT

Deletes one of the authenticated user's Web Push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/channels/web_push/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List all Web Push tokens

GET/channels/web_push/tokens
User JWT

Lists all Web Push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/channels/web_push/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "id": "123",
  "keys": {
    "auth": "GoIO2ulhtQuyBM64lZuFuw",
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
  },
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Events

Events capture everything that happens across deliveries. Query this stream to audit what occurred, troubleshoot delivery issues, and power observability dashboards.

Related guides: Delivery Primitive
ENDPOINTS
   GET /events/{event_id}
   GET /events

The Events object

Attributes

code
integer

The numeric code that categorizes the event.

context
nullable object

Additional contextual attributes for the event.

id
string required

The unique identifier for the event.

level
string

The severity level assigned to the event.

log
nullable string

A human-readable log message.

payload
nullable object

The raw payload delivered by the event source.

timestamp
string required

The time at which the event was recorded.

format: date-time
type
string required

The type of event that occurred.

The Events object
{
  "id": "123",
  "type": "example_type",
  "timestamp": "2021-01-01T00:00:00Z"
}

Fetch an event

GET/events/{event_id}
Project JWT

Fetches a project event by its ID.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/events/{event_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "type": "example_type",
    "timestamp": "2021-01-01T00:00:00Z"
  }

List all events

GET/events
Project JWT

Retrieves a paginated list of events for the project.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/events' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "id": "123",
    "type": "example_type",
    "timestamp": "2021-01-01T00:00:00Z"
  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Integrations

Integrations connect MagicBell to external providers for delivery, data ingestion, and automation. Use these grouped APIs to configure providers, run installation flows, and receive incoming events.

Related guides: Integration Primitive

APNs

Upload APNs credentials to deliver native iOS, iPadOS, and macOS push notifications.
ENDPOINTS
   PUT /integrations/apns
DELETE /integrations/apns
   GET /integrations/apns

The APNs object

Attributes

data
array
Show child attributes
(array item)
links
The APNs object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "app_id": "com.example.myapp",
        "certificate": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----",
        "key_id": "ABCD1234EF",
        "team_id": "ABCD1234EF",
        "badge": "unread"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save an APNs integration

PUT/integrations/apns
Project JWT

Updates or creates the APNs integration for the project.

Request body

app_id
string required

The default bundle identifier of the application that is configured with this project. It can be overriden on a per token basis, when registering device tokens.

pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
badge
string required

Controls whether the app icon badge counts unread or unseen notifications.

Possible enum values:
unread
unseen
certificate
string required

The APNs certificate in P8 format. Generate it at developer.apple.com with the 'Apple Push Notification service (APNs)' option selected.

pattern: ^-+?\s?BEGIN PRIVATE KEY-+\n([A-Za-z0-9+/\r\n]+={0,2})\n-+\s?END PRIVATE KEY+-+\n?$
key_id
string required

The 10-character Key ID from your Apple Developer account used with the P8 certificate.

min length: 10
max length: 10
payload_version
string

Internal payload format version used by MagicBell.

Possible enum values:
1
2
team_id
string required

The Apple Developer Team ID that owns the configured key.

min length: 10
max length: 10
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/apns' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"app_id":"com.example.myapp","certificate":"-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----","key_id":"ABCD1234EF","team_id":"ABCD1234EF","badge":"unread"}'
Response
{
  "app_id": "com.example.myapp",
  "certificate": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----",
  "key_id": "ABCD1234EF",
  "team_id": "ABCD1234EF",
  "badge": "unread"
}

Delete an APNs integration

DELETE/integrations/apns
Project JWT

Deletes the APNs integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/apns' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all APNs integrations

GET/integrations/apns
Project JWT

Retrieves the current APNs integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/apns' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "app_id": "com.example.myapp",
  "certificate": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----",
  "key_id": "ABCD1234EF",
  "team_id": "ABCD1234EF",
  "badge": "unread"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Expo

Send Expo push notifications to React Native apps with zero extra plumbing.
ENDPOINTS
   PUT /integrations/expo
DELETE /integrations/expo
   GET /integrations/expo

The Expo object

Attributes

data
array
Show child attributes
(array item)
links
The Expo object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "access_token": "expo_access_token"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save an Expo integration

PUT/integrations/expo
Project JWT

Updates or creates the Expo integration for the project.

Request body

access_token
string required

The Expo access token used to authenticate push notifications.

min length: 1
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/expo' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"access_token":"expo_access_token"}'
Response
{
  "access_token": "expo_access_token"
}

Delete an Expo integration

DELETE/integrations/expo
Project JWT

Deletes the Expo integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/expo' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Expo integrations

GET/integrations/expo
Project JWT

Retrieves the current Expo integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/expo' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "access_token": "expo_access_token"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

FCM

Connect FCM to reach Android devices and browsers that rely on Google's messaging infrastructure.
ENDPOINTS
   PUT /integrations/fcm
DELETE /integrations/fcm
   GET /integrations/fcm

The FCM object

Attributes

data
array
Show child attributes
(array item)
links
The FCM object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "type": "service_account",
        "project_id": "platform-development",
        "private_key_id": "1935e74178f6ef0bbc23fb3538255f8281093bf2",
        "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n",
        "client_email": "firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com",
        "client_id": "117893100789081023083",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com",
        "universe_domain": "googleapis.com"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a FCM integration

PUT/integrations/fcm
Project JWT

Updates or creates the FCM integration for the project.

Request body

auth_provider_x509_cert_url
string required

URL for Google's OAuth provider x509 certificates used to validate tokens.

auth_uri
string required

OAuth authorization endpoint used when exchanging Firebase credentials.

client_email
string required

The client email address from the Firebase service account.

client_id
string required

The numeric client identifier for the Firebase service account.

client_x509_cert_url
string required

URL to the public x509 certificate for this service account.

private_key
string required

The PEM encoded service account private key used to sign Firebase credentials.

pattern: ^-+?\s?BEGIN[A-Z ]+-+\n([A-Za-z0-9+/\r\n]+={0,2})\n-+\s?END[A-Z ]+-+\n?$
private_key_id
string required

Identifier of the private key inside the downloaded service account JSON.

project_id
string required

The Firebase project ID associated with this service account.

token_uri
string required

OAuth token endpoint used to mint access tokens for FCM.

type
string required

Indicates the kind of Google credential. Service accounts always use the service_account type.

Possible enum values:
service_account
universe_domain
string required

The Google Cloud universe domain hosting the Firebase APIs.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/fcm' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"type":"service_account","project_id":"platform-development","private_key_id":"1935e74178f6ef0bbc23fb3538255f8281093bf2","private_key":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n","client_email":"firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com","client_id":"117893100789081023083","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com","universe_domain":"googleapis.com"}'
Response
{
  "type": "service_account",
  "project_id": "platform-development",
  "private_key_id": "1935e74178f6ef0bbc23fb3538255f8281093bf2",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com",
  "client_id": "117893100789081023083",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

Delete a FCM integration

DELETE/integrations/fcm
Project JWT

Deletes the FCM integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/fcm' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all FCM integrations

GET/integrations/fcm
Project JWT

Retrieves the current FCM integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/fcm' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "type": "service_account",
  "project_id": "platform-development",
  "private_key_id": "1935e74178f6ef0bbc23fb3538255f8281093bf2",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com",
  "client_id": "117893100789081023083",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Inbox

Manage integrations that sync data into the MagicBell Inbox surfaces, including hosted widgets and embeddable inboxes.
ENDPOINTS
   PUT /integrations/inbox/installations
  POST /integrations/inbox/installations/start
   PUT /integrations/inbox
DELETE /integrations/inbox
   GET /integrations/inbox

The Inbox object

Attributes

data
array
Show child attributes
(array item)
links
The Inbox object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "images": {
          "emptyInboxUrl": ""
        },
        "locale": "de",
        "theme": {
          "banner": {
            "backgroundColor": "#F8F5FF",
            "fontSize": "14px",
            "textColor": "#3A424D"
          },
          "dialog": {
            "accentColor": "#5225C1",
            "backgroundColor": "#F5F5F5",
            "textColor": "#313131"
          },
          "footer": {
            "backgroundColor": "#FFFFFF",
            "borderRadius": "16px",
            "fontFamily": "inherit",
            "fontSize": "15px",
            "textColor": "#5225C1"
          },
          "header": {
            "backgroundColor": "#FFFFFF",
            "borderRadius": "16px",
            "fontFamily": "inherit",
            "fontSize": "15px",
            "textColor": "#5225C1"
          },
          "icon": {
            "borderColor": "#EDEDEF",
            "width": "24px"
          },
          "unseenBadge": {
            "backgroundColor": "#F80808"
          }
        }
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save an Inbox installation

PUT/integrations/inbox/installations
User JWT

Creates a new installation of a Inbox integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

Request body

images
nullable object required

Image overrides for assets used in the inbox UI.

Show child attributes
emptyInboxUrl
string required

URL for the illustration shown when the inbox is empty.

locale
nullable string required

Locale code (ISO language tag) used to localize built-in strings.

min length: 2
theme
nullable object required

Visual customization options for the hosted inbox widget.

Show child attributes
icon
object

Launcher icon styling overrides.

Show child attributes
borderColor
string required

CSS color used for the icon border.

width
string required

Width of the launcher icon (any CSS length).

banner
object

Top banner styling options.

Show child attributes
fontSize
string required

Font size for banner text.

backgroundColor
string required

Banner background color.

textColor
string required

Banner text color.

backgroundOpacity
number

Opacity applied to the banner background.

unseenBadge
object

Badge styling for unseen notification counts.

Show child attributes
backgroundColor
string required

Badge background color.

header
object

Header styling for the inbox modal.

Show child attributes
textColor
string required

Header text color.

borderRadius
string required

Border radius applied to the header container.

fontFamily
string required

CSS font family for the header title.

fontSize
string required

Font size used in the header.

backgroundColor
string required

Header background color.

footer
object

Footer styling for the inbox modal.

Show child attributes
fontSize
string required

Font size used in the footer.

backgroundColor
string required

Footer background color.

textColor
string required

Footer text color.

borderRadius
string required

Border radius applied to the footer container.

notification
object

Styling overrides for notification list items.

Show child attributes
default
object required

Base styles applied to every notification item.

Show child attributes
state
object

Accent colors for notification state indicators.

Show child attributes
color
string required

Color used for the state indicator.

margin
string required

CSS margin applied around each notification card.

fontFamily
string required

Font family for notification text.

fontSize
string required

Font size for notification text.

textColor
string required

Default text color for notifications.

borderRadius
string required

Border radius applied to each notification card.

backgroundColor
string required

Background color for notifications in their default state.

hover
object

Styles applied when a notification is hovered.

Show child attributes
backgroundColor
string required

Background color on hover.

unseen
object required

Overrides for unseen notifications.

Show child attributes
textColor
string required

Text color used when a notification is unseen.

backgroundColor
string required

Background color applied to unseen notifications.

hover
object

Hover styles for unseen notifications.

Show child attributes
backgroundColor
string required

Background color on hover for unseen notifications.

state
object

State indicator styling for unseen notifications.

Show child attributes
color
string required

Color for the unseen state indicator.

unread
object required

Overrides for unread notifications.

Show child attributes
state
object

State indicator styling for unread notifications.

Show child attributes
color
string required

Color for the unread state indicator.

textColor
string required

Text color used when a notification is unread.

backgroundColor
string required

Background color applied to unread notifications.

hover
object

Hover styles for unread notifications.

Show child attributes
backgroundColor
string required

Background color on hover for unread notifications.

dialog
object

Styling for confirmation and action dialogs.

Show child attributes
backgroundColor
string required

Dialog background color.

textColor
string required

Dialog text color.

accentColor
string required

Accent color for dialog buttons and highlights.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/inbox/installations' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"images":{"emptyInboxUrl":""},"locale":"de","theme":{"banner":{"backgroundColor":"#F8F5FF","fontSize":"14px","textColor":"#3A424D"},"dialog":{"accentColor":"#5225C1","backgroundColor":"#F5F5F5","textColor":"#313131"},"footer":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"header":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"icon":{"borderColor":"#EDEDEF","width":"24px"},"unseenBadge":{"backgroundColor":"#F80808"}}}'
Response
{
  "images": { "emptyInboxUrl": "" },
  "locale": "de",
  "theme": {
    "banner": {
      "backgroundColor": "#F8F5FF",
      "fontSize": "14px",
      "textColor": "#3A424D"
    },
    "dialog": {
      "accentColor": "#5225C1",
      "backgroundColor": "#F5F5F5",
      "textColor": "#313131"
    },
    "footer": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "header": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "icon": { "borderColor": "#EDEDEF", "width": "24px" },
    "unseenBadge": { "backgroundColor": "#F80808" }
  }
}

Start an Inbox installation

POST/integrations/inbox/installations/start
User JWT

Initiates the installation flow for an Inbox integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/integrations/inbox/installations/start' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "images": { "emptyInboxUrl": "" },
  "locale": "de",
  "theme": {
    "banner": {
      "backgroundColor": "#F8F5FF",
      "fontSize": "14px",
      "textColor": "#3A424D"
    },
    "dialog": {
      "accentColor": "#5225C1",
      "backgroundColor": "#F5F5F5",
      "textColor": "#313131"
    },
    "footer": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "header": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "icon": { "borderColor": "#EDEDEF", "width": "24px" },
    "unseenBadge": { "backgroundColor": "#F80808" }
  }
}

Save an Inbox integration

PUT/integrations/inbox
Project JWT

Updates or creates the Inbox integration for the project.

Request body

images
nullable object required

Image overrides for assets used in the inbox UI.

Show child attributes
emptyInboxUrl
string required

URL for the illustration shown when the inbox is empty.

locale
nullable string required

Locale code (ISO language tag) used to localize built-in strings.

min length: 2
theme
nullable object required

Visual customization options for the hosted inbox widget.

Show child attributes
dialog
object

Styling for confirmation and action dialogs.

Show child attributes
backgroundColor
string required

Dialog background color.

textColor
string required

Dialog text color.

accentColor
string required

Accent color for dialog buttons and highlights.

icon
object

Launcher icon styling overrides.

Show child attributes
width
string required

Width of the launcher icon (any CSS length).

borderColor
string required

CSS color used for the icon border.

banner
object

Top banner styling options.

Show child attributes
fontSize
string required

Font size for banner text.

backgroundColor
string required

Banner background color.

textColor
string required

Banner text color.

backgroundOpacity
number

Opacity applied to the banner background.

unseenBadge
object

Badge styling for unseen notification counts.

Show child attributes
backgroundColor
string required

Badge background color.

header
object

Header styling for the inbox modal.

Show child attributes
fontFamily
string required

CSS font family for the header title.

fontSize
string required

Font size used in the header.

backgroundColor
string required

Header background color.

textColor
string required

Header text color.

borderRadius
string required

Border radius applied to the header container.

footer
object

Footer styling for the inbox modal.

Show child attributes
fontSize
string required

Font size used in the footer.

backgroundColor
string required

Footer background color.

textColor
string required

Footer text color.

borderRadius
string required

Border radius applied to the footer container.

notification
object

Styling overrides for notification list items.

Show child attributes
default
object required

Base styles applied to every notification item.

Show child attributes
hover
object

Styles applied when a notification is hovered.

Show child attributes
backgroundColor
string required

Background color on hover.

state
object

Accent colors for notification state indicators.

Show child attributes
color
string required

Color used for the state indicator.

margin
string required

CSS margin applied around each notification card.

fontFamily
string required

Font family for notification text.

fontSize
string required

Font size for notification text.

textColor
string required

Default text color for notifications.

borderRadius
string required

Border radius applied to each notification card.

backgroundColor
string required

Background color for notifications in their default state.

unseen
object required

Overrides for unseen notifications.

Show child attributes
backgroundColor
string required

Background color applied to unseen notifications.

hover
object

Hover styles for unseen notifications.

Show child attributes
backgroundColor
string required

Background color on hover for unseen notifications.

state
object

State indicator styling for unseen notifications.

Show child attributes
color
string required

Color for the unseen state indicator.

textColor
string required

Text color used when a notification is unseen.

unread
object required

Overrides for unread notifications.

Show child attributes
hover
object

Hover styles for unread notifications.

Show child attributes
backgroundColor
string required

Background color on hover for unread notifications.

state
object

State indicator styling for unread notifications.

Show child attributes
color
string required

Color for the unread state indicator.

textColor
string required

Text color used when a notification is unread.

backgroundColor
string required

Background color applied to unread notifications.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/inbox' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"images":{"emptyInboxUrl":""},"locale":"de","theme":{"banner":{"backgroundColor":"#F8F5FF","fontSize":"14px","textColor":"#3A424D"},"dialog":{"accentColor":"#5225C1","backgroundColor":"#F5F5F5","textColor":"#313131"},"footer":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"header":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"icon":{"borderColor":"#EDEDEF","width":"24px"},"unseenBadge":{"backgroundColor":"#F80808"}}}'
Response
{
  "images": { "emptyInboxUrl": "" },
  "locale": "de",
  "theme": {
    "banner": {
      "backgroundColor": "#F8F5FF",
      "fontSize": "14px",
      "textColor": "#3A424D"
    },
    "dialog": {
      "accentColor": "#5225C1",
      "backgroundColor": "#F5F5F5",
      "textColor": "#313131"
    },
    "footer": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "header": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "icon": { "borderColor": "#EDEDEF", "width": "24px" },
    "unseenBadge": { "backgroundColor": "#F80808" }
  }
}

Delete an Inbox integration

DELETE/integrations/inbox
Project JWT

Deletes the Inbox integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/inbox' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Inbox integrations

GET/integrations/inbox
Project JWT

Retrieves the current Inbox integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/inbox' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "images": { "emptyInboxUrl": "" },
  "locale": "de",
  "theme": {
    "banner": {
      "backgroundColor": "#F8F5FF",
      "fontSize": "14px",
      "textColor": "#3A424D"
    },
    "dialog": {
      "accentColor": "#5225C1",
      "backgroundColor": "#F5F5F5",
      "textColor": "#313131"
    },
    "footer": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "header": {
      "backgroundColor": "#FFFFFF",
      "borderRadius": "16px",
      "fontFamily": "inherit",
      "fontSize": "15px",
      "textColor": "#5225C1"
    },
    "icon": { "borderColor": "#EDEDEF", "width": "24px" },
    "unseenBadge": { "backgroundColor": "#F80808" }
  }
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Magicbell Slackbot

Provision the hosted Slackbot that delivers actionable notifications into Slack without you maintaining an app. Ideal when you want a turnkey shared Slack experience.
ENDPOINTS
   PUT /integrations/magicbell_slackbot/installations
  POST /integrations/magicbell_slackbot/installations/start
  POST /integrations/magicbell_slackbot/installations/finish
   PUT /integrations/magicbell_slackbot
DELETE /integrations/magicbell_slackbot
   GET /integrations/magicbell_slackbot

The Magicbell Slackbot object

Attributes

data
array
Show child attributes
(array item)
links
The Magicbell Slackbot object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "enabled": true
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a MagicBell SlackBot installation

PUT/integrations/magicbell_slackbot/installations
User JWT

Creates a new installation of a MagicBell SlackBot integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

Request body

access_token
string required

Bot token returned from the Slack OAuth exchange.

app_id
string required

Slack app identifier for the installed app.

authed_user
object required
Show child attributes
access_token
string

User token returned from the OAuth exchange.

refresh_token
string

Refresh token for the authed user.

id
string required

Slack user ID for the installer.

token_type
string

Token type value provided by Slack.

expires_in
integer

Seconds until the user token expires.

scope
string

Space-delimited OAuth scopes granted to the user token.

bot_user_id
string

Slack user ID of the installed bot.

enterprise
object
Show child attributes
name
string required

Enterprise grid name.

id
string required

Enterprise grid identifier.

expires_in
integer

Seconds until the bot access token expires.

id
string

Unique identifier MagicBell assigns to the Slack installation.

pattern: ^[A-Z0-9]+-.*$
incoming_webhook
object
Show child attributes
channel
string required

Human readable name for the webhook channel.

configuration_url
string required

URL users can visit to manage the webhook.

url
string required

Webhook URL that Slack posts events to.

is_enterprise_install
boolean

Indicates whether the installation occurred on an enterprise grid.

refresh_token
string

Refresh token for regenerating the bot access token.

scope
string

Space-delimited OAuth scopes granted to the bot token.

team
object required
Show child attributes
name
string

Workspace name where the app was installed.

id
string required

Workspace ID where the app was installed.

token_type
string

Type of bot token returned by Slack.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot/installations' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"id":"A12345678-T123","access_token":"xoxb-123456789012-1234567890123-12345678901234567890abcdef123456","scope":"identify,commands,bot","team_name":"Team Installing Your App","team_id":"T12345678","enterprise_id":"E12345678","enterprise_name":"Enterprise Grid, Inc.","bot_user_id":"U12345678","app_id":"A12345678","authed_user":{"id":"U12345678","scope":"identify,commands"},"incoming_webhook":{"channel":"C12345678","channel_id":"C12345678","configuration_url":"https://teamname.slack.com/services/B12345678","url":"https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"},"team":{"name":"Team Installing Your App","id":"T123"}}'
Response
{
  "id": "A12345678-T123",
  "access_token": "xoxb-123456789012-1234567890123-12345678901234567890abcdef123456",
  "scope": "identify,commands,bot",
  "team_name": "Team Installing Your App",
  "team_id": "T12345678",
  "enterprise_id": "E12345678",
  "enterprise_name": "Enterprise Grid, Inc.",
  "bot_user_id": "U12345678",
  "app_id": "A12345678",
  "authed_user": {
    "id": "U12345678",
    "scope": "identify,commands"
  },
  "incoming_webhook": {
    "channel": "C12345678",
    "channel_id": "C12345678",
    "configuration_url": "https://teamname.slack.com/services/B12345678",
    "url": "https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"
  },
  "team": {
    "name": "Team Installing Your App",
    "id": "T123"
  }
}

Start a MagicBell SlackBot installation

POST/integrations/magicbell_slackbot/installations/start
User JWT

Initiates the installation flow for a MagicBell SlackBot integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

Request body

app_id
string required

Slack app ID that the installation flow should use.

auth_url
string

Optional override for the authorization URL returned to the client.

extra_scopes
array

Additional OAuth scopes to request during installation.

Show child attributes
(array item)
string
redirect_url
string

Custom redirect URL to use after OAuth completes.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot/installations/start' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"app_id":"12345678901","auth_url":"https://example.com/auth","redirect_url":"https://example.com/redirect","extra_scopes":["scope1","scope2"]}'
Response
{
    "app_id": "app-id",
    "auth_url": "https://slack.com/oauth/v2/authorize?client_id=app-id&scope=channels:read,chat:write",
    "scopes": [
      "channels:read",
      "chat:write"
    ]
  }

Finish a MagicBell SlackBot installation

POST/integrations/magicbell_slackbot/installations/finish
User JWT

Completes the installation flow for the MagicBell SlackBot integration. This endpoint is typically called after the user has completed any required authorization steps with MagicBell SlackBot.

Request body

app_id
string required

The app ID of the Slack app that was originally configured at the project-level.

code
string required

The code that was returned from the OAuth flow, and found in the query string of the redirect URL.

redirect_url
string
Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot/installations/finish' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"app_id":"12345678901","code":"string","redirect_url":"string"}'
Response
{
  "id": "A12345678-T123",
  "access_token": "xoxb-123456789012-1234567890123-12345678901234567890abcdef123456",
  "scope": "identify,commands,bot",
  "team_name": "Team Installing Your App",
  "team_id": "T12345678",
  "enterprise_id": "E12345678",
  "enterprise_name": "Enterprise Grid, Inc.",
  "bot_user_id": "U12345678",
  "app_id": "A12345678",
  "authed_user": {
    "id": "U12345678",
    "scope": "identify,commands"
  },
  "incoming_webhook": {
    "channel": "C12345678",
    "channel_id": "C12345678",
    "configuration_url": "https://teamname.slack.com/services/B12345678",
    "url": "https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"
  },
  "team": {
    "name": "Team Installing Your App",
    "id": "T123"
  }
}

Save a MagicBell SlackBot integration

PUT/integrations/magicbell_slackbot
Project JWT

Updates or creates the MagicBell SlackBot integration for the project.

Request body

enabled
boolean required
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"enabled":true}'
Response
{
    "enabled": true
  }

Delete a MagicBell SlackBot integration

DELETE/integrations/magicbell_slackbot
Project JWT

Deletes the MagicBell SlackBot integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all MagicBell SlackBot integrations

GET/integrations/magicbell_slackbot
Project JWT

Retrieves the current MagicBell SlackBot integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
    "enabled": true
  }
  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Mailgun

Connect Mailgun so you can deliver notifications using your existing domains, routes, and analytics.
ENDPOINTS
   PUT /integrations/mailgun
DELETE /integrations/mailgun
   GET /integrations/mailgun

The Mailgun object

Attributes

data
array
Show child attributes
(array item)
links
The Mailgun object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "from": {
          "name": "Example",
          "email": "hello@example.com"
        },
        "api_key": "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
        "region": "us",
        "domain": "example.com"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a Mailgun integration

PUT/integrations/mailgun
Project JWT

Updates or creates the Mailgun integration for the project.

Request body

api_key
string required
min length: 1
domain
string required
min length: 1
from
object
Show child attributes
email
string required

The email address to send from

format: email
name
nullable string

The name to send from

region
string required
Possible enum values:
us
eu
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/mailgun' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"from":{"name":"Example","email":"hello@example.com"},"api_key":"key-3ax6xnjp29jd6fds4gc373sgvjxteol0","region":"us","domain":"example.com"}'
Response
{
  "from": {
    "name": "Example",
    "email": "hello@example.com"
  },
  "api_key": "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
  "region": "us",
  "domain": "example.com"
}

Delete a Mailgun integration

DELETE/integrations/mailgun
Project JWT

Deletes the Mailgun integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/mailgun' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Mailgun integrations

GET/integrations/mailgun
Project JWT

Retrieves the current Mailgun integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/mailgun' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "from": {
    "name": "Example",
    "email": "hello@example.com"
  },
  "api_key": "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
  "region": "us",
  "domain": "example.com"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Ping Email

Synthetic email integration that helps you validate deliverability SLAs by periodically sending canary messages.
ENDPOINTS
   PUT /integrations/ping_email
DELETE /integrations/ping_email
   GET /integrations/ping_email

The Ping Email object

Attributes

data
array
Show child attributes
(array item)
links
The Ping Email object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "url": "https://example.com/webhook"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a Ping Email integration

PUT/integrations/ping_email
Project JWT

Updates or creates the Ping Email integration for the project.

Request body

url
string required

URL to ping

format: uri
min length: 1
max length: 100
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/ping_email' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"url":"https://example.com/webhook"}'
Response
{
  "url": "https://example.com/webhook"
}

Delete a Ping Email integration

DELETE/integrations/ping_email
Project JWT

Deletes the Ping Email integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/ping_email' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Ping Email integrations

GET/integrations/ping_email
Project JWT

Retrieves the current Ping Email integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/ping_email' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "url": "https://example.com/webhook"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

SendGrid

Configure SendGrid credentials so MagicBell can fan out transactional emails with your templates and domain.
ENDPOINTS
   PUT /integrations/sendgrid
DELETE /integrations/sendgrid
   GET /integrations/sendgrid

The SendGrid object

Attributes

data
array
Show child attributes
(array item)
links
The SendGrid object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "api_key": "SG.1234567890",
        "from": {
          "email": "company@example.com",
          "name": "Company Name"
        },
        "reply_to": {
          "email": "reply-to@example.com",
          "name": "Reply to Company"
        }
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a SendGrid integration

PUT/integrations/sendgrid
Project JWT

Updates or creates the SendGrid integration for the project.

Request body

api_key
string required

The API key for Sendgrid

from
object
Show child attributes
name
nullable string

The name to send from

email
string required

The email address to send from

format: email
reply_to
object
Show child attributes
email
string required

The email address to reply to

format: email
name
nullable string

The name to reply to

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/sendgrid' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"api_key":"SG.1234567890","from":{"email":"company@example.com","name":"Company Name"},"reply_to":{"email":"reply-to@example.com","name":"Reply to Company"}}'
Response
{
  "api_key": "SG.1234567890",
  "from": {
    "email": "company@example.com",
    "name": "Company Name"
  },
  "reply_to": {
    "email": "reply-to@example.com",
    "name": "Reply to Company"
  }
}

Delete a SendGrid integration

DELETE/integrations/sendgrid
Project JWT

Deletes the SendGrid integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/sendgrid' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all SendGrid integrations

GET/integrations/sendgrid
Project JWT

Retrieves the current SendGrid integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/sendgrid' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "api_key": "SG.1234567890",
  "from": {
    "email": "company@example.com",
    "name": "Company Name"
  },
  "reply_to": {
    "email": "reply-to@example.com",
    "name": "Reply to Company"
  }
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Amazon SES

Integrate Amazon SES to reuse verified identities, bounce handling, and CloudWatch metrics.
ENDPOINTS
   PUT /integrations/ses
DELETE /integrations/ses
   GET /integrations/ses

The Amazon SES object

Attributes

data
array
Show child attributes
(array item)
links
The Amazon SES object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "key_id": "MY_FAKE_AWS_ACCESS_KEY_ID",
        "secret_key": "MY_FAKE_AWS_SECRET_KEY",
        "region": "eu-west-1",
        "from": {
          "name": "Company Name",
          "email": "company@example.com"
        }
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save an Amazon SES integration

PUT/integrations/ses
Project JWT

Updates or creates the Amazon SES integration for the project.

Request body

from
object
Show child attributes
email
string required

The email address to send from

format: email
name
nullable string

The name to send from

key_id
string required

AWS Access Key ID

min length: 1
region
string required

AWS Region

min length: 1
secret_key
string required

AWS Secret Key

min length: 1
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/ses' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"key_id":"MY_FAKE_AWS_ACCESS_KEY_ID","secret_key":"MY_FAKE_AWS_SECRET_KEY","region":"eu-west-1","from":{"name":"Company Name","email":"company@example.com"}}'
Response
{
  "key_id": "MY_FAKE_AWS_ACCESS_KEY_ID",
  "secret_key": "MY_FAKE_AWS_SECRET_KEY",
  "region": "eu-west-1",
  "from": {
    "name": "Company Name",
    "email": "company@example.com"
  }
}

Delete an Amazon SES integration

DELETE/integrations/ses
Project JWT

Deletes the Amazon SES integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/ses' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Amazon SES integrations

GET/integrations/ses
Project JWT

Retrieves the current Amazon SES integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/ses' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "key_id": "MY_FAKE_AWS_ACCESS_KEY_ID",
  "secret_key": "MY_FAKE_AWS_SECRET_KEY",
  "region": "eu-west-1",
  "from": {
    "name": "Company Name",
    "email": "company@example.com"
  }
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Slack

Configure Slack so broadcasts can post rich updates into channels or DMs. The flow covers OAuth installation, workspace selection, and webhook delivery setup.
ENDPOINTS
   PUT /integrations/slack/installations
  POST /integrations/slack/installations/start
  POST /integrations/slack/installations/finish
   PUT /integrations/slack
DELETE /integrations/slack
   GET /integrations/slack

The Slack object

Attributes

data
array
Show child attributes
(array item)
links
The Slack object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "app_id": "12345678901",
        "client_id": "1.0",
        "client_secret": "12345678901234567890123456789012",
        "signing_secret": "12345678901234567890123456789012"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a Slack installation

PUT/integrations/slack/installations
User JWT

Creates a new installation of a Slack integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

Request body

access_token
string required

Bot token returned from the Slack OAuth exchange.

app_id
string required

Slack app identifier for the installed app.

authed_user
object required
Show child attributes
token_type
string

Token type value provided by Slack.

expires_in
integer

Seconds until the user token expires.

scope
string

Space-delimited OAuth scopes granted to the user token.

access_token
string

User token returned from the OAuth exchange.

refresh_token
string

Refresh token for the authed user.

id
string required

Slack user ID for the installer.

bot_user_id
string

Slack user ID of the installed bot.

enterprise
object
Show child attributes
name
string required

Enterprise grid name.

id
string required

Enterprise grid identifier.

expires_in
integer

Seconds until the bot access token expires.

id
string

Unique identifier MagicBell assigns to the Slack installation.

pattern: ^[A-Z0-9]+-.*$
incoming_webhook
object
Show child attributes
channel
string required

Human readable name for the webhook channel.

configuration_url
string required

URL users can visit to manage the webhook.

url
string required

Webhook URL that Slack posts events to.

is_enterprise_install
boolean

Indicates whether the installation occurred on an enterprise grid.

refresh_token
string

Refresh token for regenerating the bot access token.

scope
string

Space-delimited OAuth scopes granted to the bot token.

team
object required
Show child attributes
name
string

Workspace name where the app was installed.

id
string required

Workspace ID where the app was installed.

token_type
string

Type of bot token returned by Slack.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/slack/installations' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"id":"A12345678-T123","access_token":"xoxb-123456789012-1234567890123-12345678901234567890abcdef123456","scope":"identify,commands,bot","team_name":"Team Installing Your App","team_id":"T12345678","enterprise_id":"E12345678","enterprise_name":"Enterprise Grid, Inc.","bot_user_id":"U12345678","app_id":"A12345678","authed_user":{"id":"U12345678","scope":"identify,commands"},"incoming_webhook":{"channel":"C12345678","channel_id":"C12345678","configuration_url":"https://teamname.slack.com/services/B12345678","url":"https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"},"team":{"name":"Team Installing Your App","id":"T123"}}'
Response
{
  "id": "A12345678-T123",
  "access_token": "xoxb-123456789012-1234567890123-12345678901234567890abcdef123456",
  "scope": "identify,commands,bot",
  "team_name": "Team Installing Your App",
  "team_id": "T12345678",
  "enterprise_id": "E12345678",
  "enterprise_name": "Enterprise Grid, Inc.",
  "bot_user_id": "U12345678",
  "app_id": "A12345678",
  "authed_user": {
    "id": "U12345678",
    "scope": "identify,commands"
  },
  "incoming_webhook": {
    "channel": "C12345678",
    "channel_id": "C12345678",
    "configuration_url": "https://teamname.slack.com/services/B12345678",
    "url": "https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"
  },
  "team": {
    "name": "Team Installing Your App",
    "id": "T123"
  }
}

Start a Slack installation

POST/integrations/slack/installations/start
User JWT

Initiates the installation flow for a Slack integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

Request body

app_id
string required

Slack app ID that the installation flow should use.

auth_url
string

Optional override for the authorization URL returned to the client.

extra_scopes
array

Additional OAuth scopes to request during installation.

Show child attributes
(array item)
string
redirect_url
string

Custom redirect URL to use after OAuth completes.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/integrations/slack/installations/start' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"app_id":"12345678901","auth_url":"https://example.com/auth","redirect_url":"https://example.com/redirect","extra_scopes":["scope1","scope2"]}'
Response
{
    "app_id": "app-id",
    "auth_url": "https://slack.com/oauth/v2/authorize?client_id=app-id&scope=channels:read,chat:write",
    "scopes": [
      "channels:read",
      "chat:write"
    ]
  }

Finish a Slack installation

POST/integrations/slack/installations/finish
User JWT

Completes the installation flow for the Slack integration. This endpoint is typically called after the user has completed any required authorization steps with Slack.

Request body

app_id
string required

The app ID of the Slack app that was originally configured at the project-level.

code
string required

The code that was returned from the OAuth flow, and found in the query string of the redirect URL.

redirect_url
string
Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/integrations/slack/installations/finish' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"app_id":"12345678901","code":"string","redirect_url":"string"}'
Response
{
  "id": "A12345678-T123",
  "access_token": "xoxb-123456789012-1234567890123-12345678901234567890abcdef123456",
  "scope": "identify,commands,bot",
  "team_name": "Team Installing Your App",
  "team_id": "T12345678",
  "enterprise_id": "E12345678",
  "enterprise_name": "Enterprise Grid, Inc.",
  "bot_user_id": "U12345678",
  "app_id": "A12345678",
  "authed_user": {
    "id": "U12345678",
    "scope": "identify,commands"
  },
  "incoming_webhook": {
    "channel": "C12345678",
    "channel_id": "C12345678",
    "configuration_url": "https://teamname.slack.com/services/B12345678",
    "url": "https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"
  },
  "team": {
    "name": "Team Installing Your App",
    "id": "T123"
  }
}

Save a Slack integration

PUT/integrations/slack
Project JWT

Updates or creates the Slack integration for the project.

Request body

app_id
string required

The Slack app ID that can be found in the app's settings page of the Slack API dashboard.

pattern: ^[0-9A-Z]+$
client_id
string required

The Slack client ID that can be found in the app's settings page of the Slack API dashboard.

pattern: ^[0-9]+\.[0-9]+$
client_secret
string required

The Slack client secret that can be found in the app's settings page of the Slack API dashboard.

min length: 32
max length: 32
signing_secret
string required

The Slack signing secret that can be found in the app's settings page of the Slack API dashboard.

min length: 32
max length: 32
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/slack' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"app_id":"12345678901","client_id":"1.0","client_secret":"12345678901234567890123456789012","signing_secret":"12345678901234567890123456789012"}'
Response
{
  "app_id": "12345678901",
  "client_id": "1.0",
  "client_secret": "12345678901234567890123456789012",
  "signing_secret": "12345678901234567890123456789012"
}

Delete a Slack integration

DELETE/integrations/slack
Project JWT

Deletes the Slack integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/slack' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Slack integrations

GET/integrations/slack
Project JWT

Retrieves the current Slack integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/slack' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "app_id": "12345678901",
  "client_id": "1.0",
  "client_secret": "12345678901234567890123456789012",
  "signing_secret": "12345678901234567890123456789012"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

SMTP

Bring any SMTP server for outbound email, ideal for on-prem or region-specific compliance.
ENDPOINTS
   PUT /integrations/smtp
DELETE /integrations/smtp
   GET /integrations/smtp

The SMTP object

Attributes

data
array
Show child attributes
(array item)
links
The SMTP object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "host": "smtp.gmail.com",
        "port": 587,
        "username": "user@example.com",
        "password": "your-app-password",
        "from": {
          "email": "notifications@example.com",
          "name": "Example Notifications"
        },
        "reply_to": {
          "email": "support@example.com",
          "name": "Example Support"
        },
        "security": "starttls"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a SMTP integration

PUT/integrations/smtp
Project JWT

Updates or creates the SMTP integration for the project.

Request body

from
object required

Default sender email address

Show child attributes
email
string required

Sender email address

format: email
name
string

Sender name

host
string required

SMTP server hostname

password
string required

SMTP authentication password

port
integer required

SMTP server port

min: 1
max: 65535
reply_to
object

Reply-to email address

Show child attributes
name
string

Reply-to name

email
string required

Reply-to email address

format: email
security
string

SMTP security/encryption method

Possible enum values:
none
ssl
starttls
username
string required

SMTP authentication username

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/smtp' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"host":"smtp.gmail.com","port":587,"username":"user@example.com","password":"your-app-password","from":{"email":"notifications@example.com","name":"Example Notifications"},"reply_to":{"email":"support@example.com","name":"Example Support"},"security":"starttls"}'
Response
{
  "host": "smtp.gmail.com",
  "port": 587,
  "username": "user@example.com",
  "password": "your-app-password",
  "from": {
    "email": "notifications@example.com",
    "name": "Example Notifications"
  },
  "reply_to": {
    "email": "support@example.com",
    "name": "Example Support"
  },
  "security": "starttls"
}

Delete a SMTP integration

DELETE/integrations/smtp
Project JWT

Deletes the SMTP integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/smtp' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all SMTP integrations

GET/integrations/smtp
Project JWT

Retrieves the current SMTP integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/smtp' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "host": "smtp.gmail.com",
  "port": 587,
  "username": "user@example.com",
  "password": "your-app-password",
  "from": {
    "email": "notifications@example.com",
    "name": "Example Notifications"
  },
  "reply_to": {
    "email": "support@example.com",
    "name": "Example Support"
  },
  "security": "starttls"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Twilio

Wire Twilio to deliver SMS, WhatsApp, or voice notifications as part of your delivery planner.
ENDPOINTS
   PUT /integrations/twilio
DELETE /integrations/twilio
   GET /integrations/twilio

The Twilio object

Attributes

data
array
Show child attributes
(array item)
links
The Twilio object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "account_sid": "ACXXXXXXXX",
        "api_key": "SKXXXXXXXX",
        "api_secret": "your_api_secret",
        "from": "+15017122661"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a Twilio integration

PUT/integrations/twilio
Project JWT

Updates or creates the Twilio integration for the project.

Request body

account_sid
string required

The SID for your Twilio account

min length: 1
max length: 100
api_key
string required

A US1 API key for Twilio- - https://www.twilio.com/docs/iam/api-keys

min length: 1
max length: 100
api_secret
string required

The API Secret for Twilio

min length: 1
max length: 100
from
string required

The phone number to send from, in E.164 format

min length: 1
max length: 100
pattern: ^\+[0-9]{1,14}$
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/twilio' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"account_sid":"ACXXXXXXXX","api_key":"SKXXXXXXXX","api_secret":"your_api_secret","from":"+15017122661"}'
Response
{
  "account_sid": "ACXXXXXXXX",
  "api_key": "SKXXXXXXXX",
  "api_secret": "your_api_secret",
  "from": "+15017122661"
}

Delete a Twilio integration

DELETE/integrations/twilio
Project JWT

Deletes the Twilio integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/twilio' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Twilio integrations

GET/integrations/twilio
Project JWT

Retrieves the current Twilio integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/twilio' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "account_sid": "ACXXXXXXXX",
  "api_key": "SKXXXXXXXX",
  "api_secret": "your_api_secret",
  "from": "+15017122661"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Web Push

Connect browser push providers so you can reach users on the open web. Handles VAPID keys, service-worker registration, and token lifecycles.
ENDPOINTS
   PUT /integrations/web_push/installations
  POST /integrations/web_push/installations/start
   PUT /integrations/web_push
DELETE /integrations/web_push
   GET /integrations/web_push

The Web Push object

Attributes

data
array
Show child attributes
(array item)
links
The Web Push object
{
  "data": [
    {
      "name": "<provider-name>",
      "id": "123",
      "config": {
        "public_key": "BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw",
        "private_key": "y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"
      }
    }
  ],
  "links": {
    "first": "https://api.magicbell.com/v1/example",
    "next": "https://api.magicbell.com/v1/example?page_next=abc",
    "prev": null
  }
}

Save a Web Push installation

PUT/integrations/web_push/installations
User JWT

Creates a new installation of a Web Push integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.

Request body

endpoint
string required

The push subscription URL obtained from PushSubscription.endpoint after calling registration.pushManager.subscribe(). This is the unique URL for this device that push messages will be sent to.

format: uri
keys
object required

The encryption keys from the PushSubscription.getKey() method, needed to encrypt push messages for this subscription.

Show child attributes
p256dh
string required

The P-256 ECDH public key obtained from PushSubscription.getKey('p256dh'). Used to encrypt push messages for this subscription.

auth
string required

The authentication secret obtained from PushSubscription.getKey('auth'). Used to encrypt push messages for this subscription.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/web_push/installations' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"endpoint":"https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN","keys":{"p256dh":"BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0","auth":"GoIO2ulhtQuyBM64lZuFuw"}}'
Response
{
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "keys": {
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0",
    "auth": "GoIO2ulhtQuyBM64lZuFuw"
  }
}

Start a Web Push installation

POST/integrations/web_push/installations/start
User JWT

Initiates the installation flow for a Web Push integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/integrations/web_push/installations/start' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "public_key": "BHaJd...gRHDk",
  "auth_token": "eyGhb...GA2Bw"
}

Save a Web Push integration

PUT/integrations/web_push
Project JWT

Updates or creates the Web Push integration for the project.

Request body

private_key
string required

VAPID private key - from the pair you generated.

min length: 8
max length: 128
public_key
string required

VAPID public key - generate one at https://magicbell.com/tools/vapid-keys.

min length: 8
max length: 128
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/integrations/web_push' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"public_key":"BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw","private_key":"y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"}'
Response
{
  "public_key": "BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw",
  "private_key": "y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"
}

Delete a Web Push integration

DELETE/integrations/web_push
Project JWT

Deletes the Web Push integration configuration from the project. This will disable the integration's functionality within the project.

Query parameters

id
string

the unique identifier of the integration to be deleted

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/integrations/web_push' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all Web Push integrations

GET/integrations/web_push
Project JWT

Retrieves the current Web Push integration configurations for a specific integration type in the project. Returns configuration details and status information.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/integrations/web_push' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "name": "<provider-name>",
    "id": "123",
    "config": {
  "public_key": "BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw",
  "private_key": "y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"
}

  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Notifications

Notifications are the per-recipient records created from broadcasts. These endpoints let a user list, fetch, and manage the notifications that drive their inbox experience.

Related guides: Notification Primitive
ENDPOINTS
  POST /notifications/archive
  POST /notifications/read
   GET /notifications/{notification_id}
  POST /notifications/{notification_id}/archive
  POST /notifications/{notification_id}/unarchive
  POST /notifications/{notification_id}/read
  POST /notifications/{notification_id}/unread
   GET /notifications

The Notifications object

Attributes

action_url
nullable string

The link associated with the notification.

max length: 2048
archived_at
nullable string

The timestamp when the notification was archived.

format: date-time
category
nullable string

The category grouping for the notification.

max length: 100
content
nullable string

The body content of the notification.

max length: 10485760
created_at
string required

The timestamp when the notification was created.

format: date-time
custom_attributes
nullable object

The custom data stored with the notification.

discarded_at
nullable string

The timestamp when the notification was discarded.

format: date-time
id
string required

The unique identifier for the notification.

format: uuid
read_at
nullable string

The timestamp when the notification was marked as read.

format: date-time
seen_at
nullable string

The timestamp when the notification was seen.

format: date-time
sent_at
nullable string

The timestamp when the notification was sent.

format: date-time
title
string required

The title that is displayed to recipients.

min length: 1
max length: 255
topic
nullable string

The topic for additional classification.

max length: 100
updated_at
string required

The timestamp when the notification was last updated.

format: date-time
user_id
string required

The user that should receive the notification.

format: uuid
The Notifications object
{
  "id": "4b6efd21-f0f6-4051-8922-cc8c90a3dc5d",
  "title": "Example Notification",
  "action_url": null,
  "seen_at": null,
  "read_at": null,
  "project_id": 7,
  "user_id": "d4121424-097e-40b0-9cc8-357060d004b2",
  "created_at": "2024-09-11T11:14:42.165Z",
  "updated_at": "2024-09-11T11:14:42.165Z",
  "custom_attributes": {
    "key": "value",
    "obj_key": {
      "one": "two"
    }
  },
  "metadata": {},
  "category_id": null,
  "notification_broadcast_id": "6a8b1e23-f54b-4c65-95b2-78f288d7f247",
  "in_app": true,
  "discarded_at": null,
  "overrides": {},
  "aasm_state": "unseen",
  "archived_at": null,
  "topic_id": null
}

Archive all notifications

POST/notifications/archive
User JWT

Archive all notifications.

Query parameters

category
nullable string

filter notifications by their category

topic
nullable string

filter notifications by their topic

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/notifications/archive' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Mark all notifications read

POST/notifications/read
User JWT

Marks all notifications as read.

Query parameters

category
nullable string

filter notifications by their category

topic
nullable string

filter notifications by their topic

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/notifications/read' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Fetch a notification

GET/notifications/{notification_id}
User JWT

Gets a notification by ID.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/notifications/{notification_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "id": "4b6efd21-f0f6-4051-8922-cc8c90a3dc5d",
  "title": "Example Notification",
  "action_url": null,
  "seen_at": null,
  "read_at": null,
  "project_id": 7,
  "user_id": "d4121424-097e-40b0-9cc8-357060d004b2",
  "created_at": "2024-09-11T11:14:42.165Z",
  "updated_at": "2024-09-11T11:14:42.165Z",
  "custom_attributes": { "key": "value", "obj_key": { "one": "two" } },
  "metadata": {},
  "category_id": null,
  "notification_broadcast_id": "6a8b1e23-f54b-4c65-95b2-78f288d7f247",
  "in_app": true,
  "discarded_at": null,
  "overrides": {},
  "aasm_state": "unseen",
  "archived_at": null,
  "topic_id": null
}

Archive a notification

POST/notifications/{notification_id}/archive
User JWT

Archive a notification.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/notifications/{notification_id}/archive' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Unarchive a notification

POST/notifications/{notification_id}/unarchive
User JWT

Unarchives a notification.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/notifications/{notification_id}/unarchive' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Mark a notification read

POST/notifications/{notification_id}/read
User JWT

Marks a notification as read.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/notifications/{notification_id}/read' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Mark a notification unread

POST/notifications/{notification_id}/unread
User JWT

Marks a notification as unread.

Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/notifications/{notification_id}/unread' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

List all notifications

GET/notifications
User JWT

Lists all notifications for a user.

Query parameters

category
nullable string

filter notifications by their category

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

status
nullable string

filter notifications by their read state, one of 'unread' | 'read' | 'archived'

topic
nullable string

filter notifications by their topic

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/notifications' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "id": "4b6efd21-f0f6-4051-8922-cc8c90a3dc5d",
  "title": "Example Notification",
  "action_url": null,
  "seen_at": null,
  "read_at": null,
  "project_id": 7,
  "user_id": "d4121424-097e-40b0-9cc8-357060d004b2",
  "created_at": "2024-09-11T11:14:42.165Z",
  "updated_at": "2024-09-11T11:14:42.165Z",
  "custom_attributes": { "key": "value", "obj_key": { "one": "two" } },
  "metadata": {},
  "category_id": null,
  "notification_broadcast_id": "6a8b1e23-f54b-4c65-95b2-78f288d7f247",
  "in_app": true,
  "discarded_at": null,
  "overrides": {},
  "aasm_state": "unseen",
  "archived_at": null,
  "topic_id": null
}
],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Users

Users are the recipients of every notification. These endpoints let you list users, upsert profiles, and remove users while keeping identifiers aligned with your product database.

Related guides: User Primitive
ENDPOINTS
   PUT /users
DELETE /users/{user_id}
   GET /users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
DELETE /users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
   GET /users/{user_id}/channels/mobile_push/apns/tokens
   GET /users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
DELETE /users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
   GET /users/{user_id}/channels/mobile_push/expo/tokens
   GET /users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
DELETE /users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
   GET /users/{user_id}/channels/mobile_push/fcm/tokens
   GET /users/{user_id}/channels/in_app/inbox/tokens/{token_id}
DELETE /users/{user_id}/channels/in_app/inbox/tokens/{token_id}
   GET /users/{user_id}/channels/in_app/inbox/tokens
   GET /users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
DELETE /users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
   GET /users/{user_id}/channels/slack/magicbell_slackbot/tokens
   GET /users/{user_id}/channels/slack/tokens/{token_id}
DELETE /users/{user_id}/channels/slack/tokens/{token_id}
   GET /users/{user_id}/channels/slack/tokens
   GET /users/{user_id}/channels/teams/tokens/{token_id}
DELETE /users/{user_id}/channels/teams/tokens/{token_id}
   GET /users/{user_id}/channels/teams/tokens
   GET /users/{user_id}/channels/web_push/tokens/{token_id}
DELETE /users/{user_id}/channels/web_push/tokens/{token_id}
   GET /users/{user_id}/channels/web_push/tokens
   GET /users

The Users object

Attributes

app_id
string

The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.

pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
created_at
string required

The timestamp when the token was created.

format: date-time
device_token
string required

The APNs device token to register with MagicBell.

min length: 64
discarded_at
nullable string

The timestamp when the token was discarded, if applicable.

format: date-time
id
string required

The unique identifier for the token.

installation_id
string

The APNs environment this token belongs to. If omitted we assume it targets production.

Possible enum values:
development
production
updated_at
nullable string

The timestamp when the token metadata last changed.

format: date-time
The Users object
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}

Save a user

PUT/users
Project JWT

Creates or updates a user with the provided details. The user will be associated with the project specified in the request context.

Request body

created_at
nullable string

The timestamp when the user was created.

format: date-time
custom_attributes
nullable object

Arbitrary custom values stored on the user.

email
nullable string

The primary email address of the user.

external_id
nullable string

The user identifier from an external system.

first_name
nullable string

The first name of the user.

id
string

The unique identifier for the user.

format: uuid
last_name
nullable string

The last name of the user.

last_notified_at
nullable string

The timestamp when the user last received a notification.

format: date-time
last_seen_at
nullable string

The timestamp when the user last opened the inbox.

format: date-time
updated_at
nullable string

The timestamp when the user was last updated.

format: date-time
Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/users' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"id":"8a038704-acc1-47f9-81b0-7523886cbeae","external_id":"external-id","email":"dan@example.com","first_name":"Dan","last_name":"Example","custom_attributes":{"key":"value"}}'
Response
{
  "id": "8a038704-acc1-47f9-81b0-7523886cbeae",
  "external_id": "external-id",
  "email": "dan@example.com",
  "first_name": "Dan",
  "last_name": "Example",
  "custom_attributes": {
    "key": "value"
  }
}

Delete a user

DELETE/users/{user_id}
Project JWT

Removes a user and all associated data from the project.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{}

Fetch a user's APNs token

GET/users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
Project JWT

Fetches a specific APNs token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/apns/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an user's APNs token

DELETE/users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
Project JWT

Deletes a specific user's APNs token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/apns/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's APNs tokens

GET/users/{user_id}/channels/mobile_push/apns/tokens
Project JWT

Lists all APNs tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/apns/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's Expo token

GET/users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
Project JWT

Fetches a specific Expo token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/expo/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an user's Expo token

DELETE/users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
Project JWT

Deletes a specific user's Expo token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/expo/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's Expo tokens

GET/users/{user_id}/channels/mobile_push/expo/tokens
Project JWT

Lists all Expo tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/expo/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's FCM token

GET/users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
Project JWT

Fetches a specific FCM token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an user's FCM token

DELETE/users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
Project JWT

Deletes a specific user's FCM token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's FCM tokens

GET/users/{user_id}/channels/mobile_push/fcm/tokens
Project JWT

Lists all FCM tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/fcm/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "installation_id": "development",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's Inbox token

GET/users/{user_id}/channels/in_app/inbox/tokens/{token_id}
Project JWT

Fetches a specific Inbox token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/in_app/inbox/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an user's Inbox token

DELETE/users/{user_id}/channels/in_app/inbox/tokens/{token_id}
Project JWT

Deletes a specific user's Inbox token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/in_app/inbox/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's Inbox tokens

GET/users/{user_id}/channels/in_app/inbox/tokens
Project JWT

Lists all Inbox tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/in_app/inbox/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's MagicBell SlackBot token

GET/users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
Project JWT

Fetches a specific MagicBell SlackBot token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Delete an user's MagicBell SlackBot token

DELETE/users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
Project JWT

Deletes a specific user's MagicBell SlackBot token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's MagicBell SlackBot tokens

GET/users/{user_id}/channels/slack/magicbell_slackbot/tokens
Project JWT

Lists all MagicBell SlackBot tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/magicbell_slackbot/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's Slack token

GET/users/{user_id}/channels/slack/tokens/{token_id}
Project JWT

Fetches a specific Slack token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

Delete an user's Slack token

DELETE/users/{user_id}/channels/slack/tokens/{token_id}
Project JWT

Deletes a specific user's Slack token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's Slack tokens

GET/users/{user_id}/channels/slack/tokens
Project JWT

Lists all Slack tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z",
  "webhook": {
    "url": "https://example.com/webhook"
  }
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's Teams token

GET/users/{user_id}/channels/teams/tokens/{token_id}
Project JWT

Fetches a specific Teams token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/teams/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an user's Teams token

DELETE/users/{user_id}/channels/teams/tokens/{token_id}
Project JWT

Deletes a specific user's Teams token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/teams/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's Teams tokens

GET/users/{user_id}/channels/teams/tokens
Project JWT

Lists all Teams tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/teams/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "id": "123",
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Fetch a user's Web Push token

GET/users/{user_id}/channels/web_push/tokens/{token_id}
Project JWT

Fetches a specific Web Push token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/web_push/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "id": "123",
  "keys": {
    "auth": "GoIO2ulhtQuyBM64lZuFuw",
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
  },
  "updated_at": "2021-01-01T00:00:00Z"
}

Delete an user's Web Push token

DELETE/users/{user_id}/channels/web_push/tokens/{token_id}
Project JWT

Deletes a specific user's Web Push token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.

Request
curl --request DELETE \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/web_push/tokens/{token_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "123",
    "discarded_at": "2021-01-01T00:00:00Z"
  }

List an user's Web Push tokens

GET/users/{user_id}/channels/web_push/tokens
Project JWT

Lists all Web Push tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users/{user_id}/channels/web_push/tokens' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "created_at": "2021-01-01T00:00:00Z",
  "discarded_at": "2021-01-01T00:00:00Z",
  "endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
  "id": "123",
  "keys": {
    "auth": "GoIO2ulhtQuyBM64lZuFuw",
    "p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
  },
  "updated_at": "2021-01-01T00:00:00Z"
}],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

List all users

GET/users
Project JWT

Lists all users in the project.

Query parameters

ending_before
nullable string

a cursor for use in pagination, points to the first ID in next page

limit
integer

defines the maximum number of items to return per page (default: 50)

query
nullable string

filter users by their email address or external ID

starting_after
nullable string

a cursor for use in pagination, points to the last ID in previous page

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/users' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
  "id": "8a038704-acc1-47f9-81b0-7523886cbeae",
  "external_id": "external-id",
  "email": "dan@example.com",
  "first_name": "Dan",
  "last_name": "Example",
  "custom_attributes": {
    "key": "value"
  }
}
],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

Workflows

Workflows let you orchestrate multi-step reactions to events, fan out to broadcasts, enrich data, or call external services. These routes manage definitions and runs so you can iterate on automation safely.
ENDPOINTS
   PUT /workflows
   GET /workflows/*
  POST /workflows/runs
   GET /workflows/runs/{run_id}
   GET /workflows/{workflow_key}/runs
   GET /workflows

The Workflows object

Attributes

disabled
boolean

When true, prevents the workflow from being triggered.

key
string required

Unique identifier for this workflow definition.

min length: 3
pattern: ^[A-Za-z0-9\_\.\-\:]+$
steps
array required

Ordered list describing each action that will run inside the workflow.

Show child attributes
(array item)
object
Show child attributes
if
nullable string

JMESPath condition that must evaluate truthy for the step to run.

input
nullable object

Optional payload passed to the command when it executes.

command
string required

Command to execute (e.g., broadcast, pause, wait, abort)

pattern: ^[a-z_]+$
The Workflows object
{
  "steps": [
    {
      "command": "broadcast",
      "input": {
        "channel": "in_app"
      }
    },
    {
      "command": "broadcast",
      "if": "{{data.paying}} == true",
      "input": {
        "channel": "email"
      }
    }
  ],
  "key": "project"
}

Save workflow definition

PUT/workflows
Project JWT

Creates or updates a workflow definition for the project

Request body

disabled
boolean

When true, prevents the workflow from being triggered.

key
string required

Unique identifier for this workflow definition.

min length: 3
pattern: ^[A-Za-z0-9\_\.\-\:]+$
steps
array required

Ordered list describing each action that will run inside the workflow.

Show child attributes
(array item)
object
Show child attributes
command
string required

Command to execute (e.g., broadcast, pause, wait, abort)

pattern: ^[a-z_]+$
if
nullable string

JMESPath condition that must evaluate truthy for the step to run.

input
nullable object

Optional payload passed to the command when it executes.

Request
curl --request PUT \
  --url 'https://api.magicbell.com/v2/workflows' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"steps":[{"command":"broadcast","input":{"channel":"in_app"}},{"command":"broadcast","if":"{{data.paying}} == true","input":{"channel":"email"}}],"key":"project"}'
Response
{
  "steps": [
    {
      "command": "broadcast",
      "input": {
        "channel": "in_app"
      }
    },
    {
      "command": "broadcast",
      "if": "{{data.paying}} == true",
      "input": {
        "channel": "email"
      }
    }
  ],
  "key": "project"
}

Fetch workflow definition

GET/workflows/*
Project JWT

Retrieves a workflow definition by key

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/workflows/*' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
  "steps": [
    {
      "command": "broadcast",
      "input": {
        "channel": "in_app"
      }
    },
    {
      "command": "broadcast",
      "if": "{{data.paying}} == true",
      "input": {
        "channel": "email"
      }
    }
  ],
  "key": "project"
}

Execute workflow

POST/workflows/runs
Project JWT

Executes a workflow with the provided input parameters

Request body

input
nullable object

Optional JSON payload that will be passed as the workflow input context.

key
string required

The unique workflow key to execute (e.g. integration.stripe.charge.succeeded).

pattern: ^[A-Za-z0-9\_\.\-\:]+$
Request
curl --request POST \
  --url 'https://api.magicbell.com/v2/workflows/runs' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN" \
  --data '{"key":"magicbell:signup","input":{"user":{"id":"123","name":"John Doe"}}}'
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Get workflow run status

GET/workflows/runs/{run_id}
Project JWT

Retrieves the status and details of a workflow run

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/workflows/runs/{run_id}' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "workflow_key": "integration.stripe.charge.succeeded",
    "status": {
      "state": 2,
      "next_step": 1,
      "started_at": "2024-01-01T00:00:00Z"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "input": {
      "description": "",
      "payload": {
        "action": "in_progress"
      },
      "type": "workflow_job"
    }
  }

List workflow runs

GET/workflows/{workflow_key}/runs
Project JWT

Retrieves all runs for a specific workflow

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/workflows/{workflow_key}/runs' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "data":[{
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "workflow_key": "integration.stripe.charge.succeeded",
    "status": {
      "state": 2,
      "next_step": 1,
      "started_at": "2024-01-01T00:00:00Z"
    },
    "created_at": "2024-01-01T00:00:00Z"
  }],
    "links": {
      "first":"https://api.magicbell.com/v1/example",
      "next":"https://api.magicbell.com/v1/example?page_next=abc",
      "prev":null
    }
  }

List workflow definitions

GET/workflows
Project JWT

Retrieves all workflow definitions for the project

Request
curl --request GET \
  --url 'https://api.magicbell.com/v2/workflows' \
  --header 'content-type: application/json' \
  --header "authorization: Bearer $TOKEN"
Response
{
    "items": [
      {
        "key": "integration.stripe.charge.succeeded",
        "disabled": false,
        "steps": [
          {
            "command": "broadcast",
            "if": "event.amount > 1000",
            "input": {
              "category": "billing",
              "template": "payment_received"
            }
          }
        ]
      }
    ]
  }