API (v2) Reference

Introduction

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

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

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
max length: 2048
category
nullable string
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
content
nullable string
max length: 10485760
created_at
string

The timestamp when the broadcast was created.

format: date-time
custom_attributes
nullable object
id
string

The unique id for this broadcast.

format: uuid
overrides
nullable object
Show child attributes
providers
object
Show child attributes
expo
object
slack
object
teams
object
sendgrid
object
mailgun
object
ses
object
fcm
object
apns
object
web_push
object
twilio
object
channels
object
Show child attributes
email
object
Show child attributes
title
string
min length: 1
max length: 255
content
string
max length: 1048576
action_url
nullable string
max length: 2048
sms
object
Show child attributes
title
string
min length: 1
max length: 255
content
string
max length: 1048576
action_url
nullable string
max length: 2048
in_app
object
Show child attributes
title
string
min length: 1
max length: 255
content
string
max length: 1048576
action_url
nullable string
max length: 2048
mobile_push
object
Show child attributes
action_url
nullable string
max length: 2048
title
string
min length: 1
max length: 255
content
string
max length: 1048576
recipients
nullable array required
min items: 1
max items: 1000
Show child attributes
(array item)
status
object
Show child attributes
status
string required
Possible enum values:
enqueued
processing
processed
summary
object required
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
Show child attributes
(array item)
object
Show child attributes
message
string
title
string required
min length: 1
max length: 255
topic
nullable string
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
Request
magicbell broadcast create \
  --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
magicbell broadcast fetch \
  --broadcast_id '{broadcast_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell broadcast list
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
    }
  }

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

(Optional) The bundle identifier of the application that is registering this token. Use this field to override the default identifier specified in the projects APNs integration.

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

(Optional) The APNs environment the token is registered for. If none is provided we assume the token is used in production.

Possible enum values:
development
production
Request
magicbell channel save_apns_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
magicbell channel fetch_apns_token \
  --token_id '{token_id}'
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
magicbell channel delete_apns_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_apns_tokens
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
min length: 1
Request
magicbell channel save_expo_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
magicbell channel fetch_expo_token \
  --token_id '{token_id}'
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
magicbell channel delete_expo_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_expo_tokens
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
min length: 64
installation_id
string
Possible enum values:
development
production
Request
magicbell channel save_fcm_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
magicbell channel fetch_fcm_token \
  --token_id '{token_id}'
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
magicbell channel delete_fcm_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_fcm_tokens
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 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
token
string required
min length: 64
Request
magicbell channel save_inbox_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
magicbell channel fetch_inbox_token \
  --token_id '{token_id}'
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
magicbell channel delete_inbox_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_inbox_tokens
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
    }
  }

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
installation_id
string required
scope
string
channel_id
string required
webhook
object

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

Show child attributes
url
string required
format: uri
min length: 1
Request
magicbell channel save_slack_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
magicbell channel fetch_slack_token \
  --token_id '{token_id}'
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
magicbell channel delete_slack_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_slack_tokens
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 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
magicbell channel save_teams_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
magicbell channel fetch_teams_token \
  --token_id '{token_id}'
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
magicbell channel delete_teams_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_teams_tokens
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
    }
  }

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
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_\.\-/:]+$
label
nullable string
max length: 255
Request
magicbell channel save_user_preferences \
  --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
magicbell channel fetch_user_preferences
Response
{
    "categories": [
      {
        "key": "category_1",
        "label": "Category 1",
        "channels": [
          {
            "name": "email",
            "label": "Email",
            "enabled": true
          }
        ]
      }
    ]
  }

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
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
magicbell channel save_web_push_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
magicbell channel fetch_web_push_token \
  --token_id '{token_id}'
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
magicbell channel delete_web_push_token \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell channel list_web_push_tokens
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
    }
  }

Fetch an event

GET/events/{event_id}
Project JWT

Fetches a project event by its ID.

Request
magicbell event fetch \
  --event_id '{event_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell event list
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
    }
  }

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
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
min length: 10
max length: 10
payload_version
string
Possible enum values:
1
2
team_id
string required
min length: 10
max length: 10
Request
magicbell integration save_apns \
  --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
Request
magicbell integration delete_apns
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
magicbell integration list_apns
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
    }
  }

Save an Expo integration

PUT/integrations/expo
Project JWT

Updates or creates the Expo integration for the project.

Request body

access_token
string required
min length: 1
Request
magicbell integration save_expo \
  --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
Request
magicbell integration delete_expo
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
magicbell integration list_expo
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
    }
  }

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
auth_uri
string required
client_email
string required
client_id
string required
client_x509_cert_url
string required
private_key
string required
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
project_id
string required
token_uri
string required
type
string required
Possible enum values:
service_account
universe_domain
string required
Request
magicbell integration save_fcm \
  --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
Request
magicbell integration delete_fcm
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
magicbell integration list_fcm
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
    }
  }

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
Show child attributes
emptyInboxUrl
string required
locale
nullable string required
min length: 2
theme
nullable object required
Show child attributes
banner
object
Show child attributes
backgroundOpacity
number
fontSize
string required
backgroundColor
string required
textColor
string required
unseenBadge
object
Show child attributes
backgroundColor
string required
header
object
Show child attributes
fontFamily
string required
fontSize
string required
backgroundColor
string required
textColor
string required
borderRadius
string required
footer
object
Show child attributes
fontSize
string required
backgroundColor
string required
textColor
string required
borderRadius
string required
notification
object
Show child attributes
default
object required
Show child attributes
fontFamily
string required
fontSize
string required
textColor
string required
borderRadius
string required
backgroundColor
string required
hover
object
Show child attributes
backgroundColor
string required
state
object
Show child attributes
color
string required
margin
string required
unseen
object required
Show child attributes
textColor
string required
backgroundColor
string required
hover
object
Show child attributes
backgroundColor
string required
state
object
Show child attributes
color
string required
unread
object required
Show child attributes
state
object
Show child attributes
color
string required
textColor
string required
backgroundColor
string required
hover
object
Show child attributes
backgroundColor
string required
dialog
object
Show child attributes
accentColor
string required
backgroundColor
string required
textColor
string required
icon
object
Show child attributes
borderColor
string required
width
string required
Request
magicbell integration save_inbox_installation \
  --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
magicbell integration start_inbox_installation
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
Show child attributes
emptyInboxUrl
string required
locale
nullable string required
min length: 2
theme
nullable object required
Show child attributes
dialog
object
Show child attributes
backgroundColor
string required
textColor
string required
accentColor
string required
icon
object
Show child attributes
borderColor
string required
width
string required
banner
object
Show child attributes
fontSize
string required
backgroundColor
string required
textColor
string required
backgroundOpacity
number
unseenBadge
object
Show child attributes
backgroundColor
string required
header
object
Show child attributes
borderRadius
string required
fontFamily
string required
fontSize
string required
backgroundColor
string required
textColor
string required
footer
object
Show child attributes
fontSize
string required
backgroundColor
string required
textColor
string required
borderRadius
string required
notification
object
Show child attributes
default
object required
Show child attributes
textColor
string required
borderRadius
string required
backgroundColor
string required
hover
object
Show child attributes
backgroundColor
string required
state
object
Show child attributes
color
string required
margin
string required
fontFamily
string required
fontSize
string required
unseen
object required
Show child attributes
textColor
string required
backgroundColor
string required
hover
object
Show child attributes
backgroundColor
string required
state
object
Show child attributes
color
string required
unread
object required
Show child attributes
state
object
Show child attributes
color
string required
textColor
string required
backgroundColor
string required
hover
object
Show child attributes
backgroundColor
string required
Request
magicbell integration save_inbox \
  --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
Request
magicbell integration delete_inbox
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
magicbell integration list_inbox
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
    }
  }

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
magicbell integration save_mailgun \
  --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
Request
magicbell integration delete_mailgun
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
magicbell integration list_mailgun
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
    }
  }

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
magicbell integration save_ping_email \
  --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
Request
magicbell integration delete_ping_email
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
magicbell integration list_ping_email
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
    }
  }

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
email
string required

The email address to send from

format: email
name
nullable string

The name to send from

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
magicbell integration save_sendgrid \
  --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
Request
magicbell integration delete_sendgrid
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
magicbell integration list_sendgrid
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
    }
  }

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
magicbell integration save_ses \
  --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
Request
magicbell integration delete_ses
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
magicbell integration list_ses
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
    }
  }

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
app_id
string required
authed_user
object required
Show child attributes
access_token
string
refresh_token
string
id
string required
token_type
string
expires_in
integer
scope
string
bot_user_id
string
enterprise
object
Show child attributes
name
string required
id
string required
expires_in
integer
id
string
pattern: ^[A-Z0-9]+-.*$
incoming_webhook
object
Show child attributes
channel
string required
configuration_url
string required
url
string required
is_enterprise_install
boolean
refresh_token
string
scope
string
team
object required
Show child attributes
name
string
id
string required
token_type
string
Request
magicbell integration save_slack_installation \
  --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
auth_url
string
extra_scopes
array
Show child attributes
(array item)
string
redirect_url
string
Request
magicbell integration start_slack_installation \
  --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
magicbell integration finish_slack_installation \
  --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
magicbell integration save_slack \
  --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
Request
magicbell integration delete_slack
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
magicbell integration list_slack
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
    }
  }

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
magicbell integration save_twilio \
  --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
Request
magicbell integration delete_twilio
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
magicbell integration list_twilio
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
    }
  }

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
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
magicbell integration save_web_push_installation \
  --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
magicbell integration start_web_push_installation
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://tools.reactpwa.com/vapid.

min length: 8
max length: 128
Request
magicbell integration save_web_push \
  --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
Request
magicbell integration delete_web_push
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
magicbell integration list_web_push
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
    }
  }

Archive all notifications

POST/notifications/archive
User JWT

Archive all notifications.

Query parameters

category
nullable string
topic
nullable string
Request
magicbell notification archive_all
Response
{}

Mark all notifications read

POST/notifications/read
User JWT

Marks all notifications as read.

Query parameters

category
nullable string
topic
nullable string
Request
magicbell notification mark_all_read
Response
{}

Fetch a notification

GET/notifications/{notification_id}
User JWT

Gets a notification by ID.

Request
magicbell notification fetch \
  --notification_id '{notification_id}'
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
magicbell notification archive \
  --notification_id '{notification_id}'
Response
{}

Unarchive a notification

POST/notifications/{notification_id}/unarchive
User JWT

Unarchives a notification.

Request
magicbell notification unarchive \
  --notification_id '{notification_id}'
Response
{}

Mark a notification read

POST/notifications/{notification_id}/read
User JWT

Marks a notification as read.

Request
magicbell notification mark_read \
  --notification_id '{notification_id}'
Response
{}

Mark a notification unread

POST/notifications/{notification_id}/unread
User JWT

Marks a notification as unread.

Request
magicbell notification mark_unread \
  --notification_id '{notification_id}'
Response
{}

List all notifications

GET/notifications
User JWT

Lists all notifications for a user.

Query parameters

category
nullable string
ending_before
nullable string
limit
integer
starting_after
nullable string
status
nullable string
topic
nullable string
Request
magicbell notification list
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
    }
  }

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
format: date-time
custom_attributes
nullable object
email
nullable string
external_id
nullable string
first_name
nullable string
id
string
format: uuid
last_name
nullable string
last_notified_at
nullable string
format: date-time
last_seen_at
nullable string
format: date-time
updated_at
nullable string
format: date-time
Request
magicbell user save \
  --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
magicbell user delete \
  --user_id '{user_id}'
Response
{}

Fetch an 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
magicbell user fetch_apns_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_apns_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_apns_tokens \
  --user_id '{user_id}'
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 an 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
magicbell user fetch_expo_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_expo_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_expo_tokens \
  --user_id '{user_id}'
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 an 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
magicbell user fetch_fcm_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_fcm_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_fcm_tokens \
  --user_id '{user_id}'
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 an 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
magicbell user fetch_inbox_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_inbox_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_inbox_tokens \
  --user_id '{user_id}'
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 an 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
magicbell user fetch_slack_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_slack_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_slack_tokens \
  --user_id '{user_id}'
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 an 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
magicbell user fetch_teams_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_teams_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_teams_tokens \
  --user_id '{user_id}'
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 an 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
magicbell user fetch_web_push_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
magicbell user delete_web_push_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'
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
limit
integer
starting_after
nullable string
Request
magicbell user list_web_push_tokens \
  --user_id '{user_id}'
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
limit
integer
query
nullable string
starting_after
nullable string
Request
magicbell user list
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
    }
  }

Save workflow definition

PUT/workflows
Project JWT

Creates or updates a workflow definition for the project

Request body

disabled
boolean
key
string required
min length: 3
pattern: ^[A-Za-z0-9\_\.\-\:]+$
steps
array required
Show child attributes
(array item)
object
Show child attributes
command
string required
pattern: ^[A-Za-z0-9\_\:]+$
if
nullable string
input
nullable object
Request
magicbell workflow save \
  --data '{"steps":[{"command":"broadcast:send","input":{"channel":"in_app"}},{"command":"broadcast:send","if":"{{notification.unseen}} == false","input":{"channel":"email"}}],"key":"project"}'
Response
{
  "steps": [
    {
      "command": "broadcast:send",
      "input": {
        "channel": "in_app"
      }
    },
    {
      "command": "broadcast:send",
      "if": "{{notification.unseen}} == false",
      "input": {
        "channel": "email"
      }
    }
  ],
  "key": "project"
}

Fetch workflow definition

GET/workflows/*
Project JWT

Retrieves a workflow definition by key

Request
magicbell workflow fetch
Response
{
  "steps": [
    {
      "command": "broadcast:send",
      "input": {
        "channel": "in_app"
      }
    },
    {
      "command": "broadcast:send",
      "if": "{{notification.unseen}} == false",
      "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
key
string required
pattern: ^[A-Za-z0-9\_\.\-\:]+$
Request
magicbell workflow create_run \
  --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
magicbell workflow fetch_run \
  --run_id '{run_id}'
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"
  }

List workflow runs

GET/workflows/{workflow_key}/runs
Project JWT

Retrieves all runs for a specific workflow

Request
magicbell workflow list_runs \
  --workflow_key '{workflow_key}'
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
    }
  }