CLI

This package provides a convenient interface to query the MagicBell API.

Quick Start

To get started, install the package with npm

npm install -g magicbell-cli

Authentication

The MagicBell CLI provides two ways to authenticate: interactive browser-based authentication and manual authentication with API keys. Interactive authentication is recommended for local development, while manual authentication is better suited for CI/CD environments.

Interactive Authentication

Log in and authenticate your MagicBell user account to generate a set of authentication keys. To learn more, see our API Authentication docs.

magicbell login

Your browser should open to complete the authentication process. Please click the generated link if it does not.

Output

Starting web-based authentication flow...
Opening browser for authentication...
Please log in with your MagicBell account.
If the browser doesn't open automatically, please visit:
https://api.magicbell.com/cli/auth/initiate?…

Manual Authentication

Optionally, if you don't want to use a browser, use the --manual flag to authenticate with existing keys. This can be helpful when authenticating the CLI in CI/CD environments. This option requires your email, project's JWT, API Key and Secret Key, which are available in the MagicBell Dashboard.

magicbell login \
  --manual \
  --email $EMAIL \
  --jwt $JWT \
  --api-key $API_KEY \
  --secret-key $SECRET_KEY

Output

Using provided credentials...
✅ Successfully logged in with provided credentials!

Commands

Below you'll find the all supported commands with their arguments. Note that you can also run magicbell --help at any time to get a list of options in your console.

You can pass data for commands that take a request body with a --data flag.

Broadcast

List all broadcasts

api ref: list_broadcasts

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

magicbell broadcast list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Fetch a broadcast

api ref: fetch_broadcast

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

magicbell broadcast fetch \
  --broadcast_id '{broadcast_id}'

Flags

Name	Required
broadcast_id	true

Create a broadcast

api ref: create_broadcast

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

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":{}}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

action_url

nullable string

max length: 2048

Channel

List all Web Push tokens

api ref: list_web_push_tokens

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

magicbell channel list_web_push_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Save a channels config

api ref: save_channels_config

Save the channels configuration for a given key.

magicbell channel save_config \
  --data '{"channels":[{"channel":"in_app"},{"if":"{{notification.unseen}} == false","channel":"email"}],"key":"project"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

channels

array required

Show child attributes

(array item)

object

Show child attributes

channel

string required

Possible enum values:

in_app

slack

web_push

mobile_push

teams

sms

delay

integer

min: 0

nullable string

disabled

boolean

key

string required

min length: 3

pattern: ^[A-Za-z0-9_.\-:/]+$

List all Expo tokens

api ref: list_expo_tokens

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

magicbell channel list_expo_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Save a Web Push token

api ref: save_web_push_token

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.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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.

Save an APNs token

api ref: save_apns_token

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.

magicbell channel save_apns_token \
  --data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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

Fetch channel preferences

api ref: fetch_user_preferences

Fetch a user's channel delivery preferences.

magicbell channel fetch_user_preferences

Fetch a channels config

api ref: fetch_channels_config

Fetches the channels config for a given key.

magicbell channel fetch_config \
  --key '{key}'

Flags

Name	Required
key	true

Delete an APNs token

api ref: delete_apns_token

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.

magicbell channel delete_apns_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Save an Expo token

api ref: save_expo_token

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.

magicbell channel save_expo_token \
  --data '{"device_token":"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

device_token

string required

min length: 1

Delete a Teams token

api ref: delete_teams_token

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.

magicbell channel delete_teams_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Delete an Inbox token

api ref: delete_inbox_token

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.

magicbell channel delete_inbox_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Save a FCM token

api ref: save_fcm_token

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.

magicbell channel save_fcm_token \
  --data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

device_token

string required

min length: 64

installation_id

string

Possible enum values:

development

production

Delete a FCM token

api ref: delete_fcm_token

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.

magicbell channel delete_fcm_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Fetch an Expo token

api ref: fetch_expo_token

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.

magicbell channel fetch_expo_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Fetch an Inbox token

api ref: fetch_inbox_token

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.

magicbell channel fetch_inbox_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

List all APNs tokens

api ref: list_apns_tokens

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

magicbell channel list_apns_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Save a Slack token

api ref: save_slack_token

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.

magicbell channel save_slack_token \
  --data '{"webhook":{"url":"https://example.com/webhook"}}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

oauth

object

Show child attributes

scope

string

channel_id

string required

installation_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

Fetch an APNs token

api ref: fetch_apns_token

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.

magicbell channel fetch_apns_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

List all Teams tokens

api ref: list_teams_tokens

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

magicbell channel list_teams_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Save channel preferences

api ref: save_user_preferences

Save a user's channel preferences.

magicbell channel save_user_preferences \
  --data '{"categories":[{"key":"category_1","label":"Category 1","channels":[{"name":"email","label":"Email","enabled":true}]}]}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

Delete an Expo token

api ref: delete_expo_token

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.

magicbell channel delete_expo_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Save an Inbox token

api ref: save_inbox_token

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.

magicbell channel save_inbox_token \
  --data '{"token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

connection_id

nullable string

token

string required

min length: 64

List all Inbox tokens

api ref: list_inbox_tokens

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

magicbell channel list_inbox_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Fetch a Teams token

api ref: fetch_teams_token

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.

magicbell channel fetch_teams_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Delete a Web Push token

api ref: delete_web_push_token

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.

magicbell channel delete_web_push_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Fetch a Web Push token

api ref: fetch_web_push_token

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.

magicbell channel fetch_web_push_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

List all FCM tokens

api ref: list_fcm_tokens

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

magicbell channel list_fcm_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Fetch a FCM token

api ref: fetch_fcm_token

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.

magicbell channel fetch_fcm_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

List all Slack tokens

api ref: list_slack_tokens

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

magicbell channel list_slack_tokens

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Delete a Slack token

api ref: delete_slack_token

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.

magicbell channel delete_slack_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Fetch a Slack token

api ref: fetch_slack_token

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.

magicbell channel fetch_slack_token \
  --token_id '{token_id}'

Flags

Name	Required
token_id	true

Save a Teams token

api ref: save_teams_token

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.

magicbell channel save_teams_token

Event

List all events

api ref: list_events

Retrieves a paginated list of events for the project.

magicbell event list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

Fetch an event

api ref: fetch_event

Fetches a project event by its ID.

magicbell event fetch \
  --event_id '{event_id}'

Flags

Name	Required
event_id	true

Integration

List all Amazon SES integrations

api ref: list_ses_integrations

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

magicbell integration list_ses

Save a Slack installation

api ref: save_slack_installation

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.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

access_token

string required

app_id

string required

authed_user

object required

Show child attributes

access_token

string

refresh_token

string

string required

token_type

string

expires_in

integer

scope

string

bot_user_id

string

enterprise

object

Show child attributes

name

string required

expires_in

integer

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

string required

token_type

string

Finish a Slack installation

api ref: finish_slack_installation

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

magicbell integration finish_slack_installation \
  --data '{"app_id":"12345678901","code":"string","redirect_url":"string"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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

Save a Web Push integration

api ref: save_web_push_integration

Updates or creates the Web Push integration for the project.

magicbell integration save_web_push \
  --data '{"public_key":"BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw","private_key":"y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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

Delete a FCM integration

api ref: delete_fcm_integration

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

magicbell integration delete_fcm

Flags

Name	Required
id	false

List all Inbox integrations

api ref: list_inbox_integrations

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

magicbell integration list_inbox

Delete a Ping Email integration

api ref: delete_ping_email_integration

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

magicbell integration delete_ping_email

Flags

Name	Required
id	false

Save a Ping Email integration

api ref: save_ping_email_integration

Updates or creates the Ping Email integration for the project.

magicbell integration save_ping_email \
  --data '{"url":"https://example.com/webhook"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

url

string required

URL to ping

format: uri

min length: 1

max length: 100

List all SendGrid integrations

api ref: list_sendgrid_integrations

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

magicbell integration list_sendgrid

Save a Stripe integration

api ref: save_stripe_integration

Updates or creates the Stripe integration for the project.

magicbell integration save_stripe \
  --data '{"webhook_signing_secret":"whsec_e5cf4458caae49ae72d8f275deb9b63bdd41dd5c932c27c9346d428fb9e1d0a0"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

string

The unique identifier for this configuration

format: uuid

webhook_signing_secret

string required

The signing secret to verify incoming requests from Stripe

min length: 1

max length: 100

Save a Twilio integration

api ref: save_twilio_integration

Updates or creates the Twilio integration for the project.

magicbell integration save_twilio \
  --data '{"account_sid":"ACXXXXXXXX","api_key":"SKXXXXXXXX","api_secret":"your_api_secret","from":"+15017122661"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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}$

Delete a Web Push integration

api ref: delete_web_push_integration

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

magicbell integration delete_web_push

Flags

Name	Required
id	false

List all integrations

api ref: list_integrations

Lists all available and configured integrations for the project. Returns a summary of each integration including its type, status, and basic configuration information.

magicbell integration list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false

List all EventSource integrations

api ref: list_eventsource_integrations

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

magicbell integration list_eventsource

Delete a SendGrid integration

api ref: delete_sendgrid_integration

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

magicbell integration delete_sendgrid

Flags

Name	Required
id	false

Delete a Twilio integration

api ref: delete_twilio_integration

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

magicbell integration delete_twilio

Flags

Name	Required
id	false

Save an APNs integration

api ref: save_apns_integration

Updates or creates the APNs integration for the project.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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:

team_id

string required

min length: 10

max length: 10

List all APNs integrations

api ref: list_apns_integrations

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

magicbell integration list_apns

Save an Inbox installation

api ref: save_inbox_installation

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.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

images

nullable object required

Show child attributes

emptyInboxUrl

string required

locale

nullable string required

min length: 2

theme

nullable object required

Show child attributes

icon

object

Show child attributes

borderColor

string required

width

string required

banner

object

Show child attributes

textColor

string required

backgroundOpacity

number

fontSize

string required

backgroundColor

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

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

fontFamily

string required

unseen

object required

Show child attributes

hover

object

Show child attributes

backgroundColor

string required

state

object

Show child attributes

color

string required

textColor

string required

backgroundColor

string required

unread

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

dialog

object

Show child attributes

backgroundColor

string required

textColor

string required

accentColor

string required

List all Mailgun integrations

api ref: list_mailgun_integrations

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

magicbell integration list_mailgun

Save an Amazon SES integration

api ref: save_ses_integration

Updates or creates the Amazon SES integration for the project.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

from

object

Show child attributes

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

Save a Web Push installation

api ref: save_web_push_installation

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.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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.

Save an EventSource integration

api ref: save_eventsource_integration

Updates or creates the EventSource integration for the project.

magicbell integration save_eventsource \
  --data '{"source":"backend"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

source

string required

Delete an Expo integration

api ref: delete_expo_integration

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

magicbell integration delete_expo

Flags

Name	Required
id	false

Save an Expo integration

api ref: save_expo_integration

Updates or creates the Expo integration for the project.

magicbell integration save_expo \
  --data '{"access_token":"expo_access_token"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

access_token

string required

min length: 1

Delete a GitHub integration

api ref: delete_github_integration

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

magicbell integration delete_github

Flags

Name	Required
id	false

Save a GitHub integration

api ref: save_github_integration

Updates or creates the GitHub integration for the project.

magicbell integration save_github \
  --data '{"webhook_signing_secret":"whsec_e5cf4458caae49ae72d8f275deb9b63bdd41dd5c932c27c9346d428fb9e1d0a0"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

webhook_signing_secret

string required

The signing secret to verify incoming requests from Github

min length: 1

max length: 100

Delete a Mailgun integration

api ref: delete_mailgun_integration

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

magicbell integration delete_mailgun

Flags

Name	Required
id	false

Save a Slack integration

api ref: save_slack_integration

Updates or creates the Slack integration for the project.

magicbell integration save_slack \
  --data '{"app_id":"12345678901","client_id":"1.0","client_secret":"12345678901234567890123456789012","signing_secret":"12345678901234567890123456789012"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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

List all Slack integrations

api ref: list_slack_integrations

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

magicbell integration list_slack

Delete an APNs integration

api ref: delete_apns_integration

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

magicbell integration delete_apns

Flags

Name	Required
id	false

Save an Inbox integration

api ref: save_inbox_integration

Updates or creates the Inbox integration for the project.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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

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

backgroundColor

string required

textColor

string required

borderRadius

string required

fontSize

string required

notification

object

Show child attributes

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

textColor

string required

backgroundColor

string required

hover

object

Show child attributes

backgroundColor

string required

state

object

Show child attributes

color

string required

default

object required

Show child attributes

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

fontFamily

string required

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

Start an Inbox installation

api ref: start_inbox_installation

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.

magicbell integration start_inbox_installation

List all Ping Email integrations

api ref: list_ping_email_integrations

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

magicbell integration list_ping_email

Delete an Amazon SES integration

api ref: delete_ses_integration

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

magicbell integration delete_ses

Flags

Name	Required
id	false

Start a Slack installation

api ref: start_slack_installation

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.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

app_id

string required

auth_url

string

extra_scopes

array

Show child attributes

(array item)

string

redirect_url

string

List all Stripe integrations

api ref: list_stripe_integrations

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

magicbell integration list_stripe

List all Web Push integrations

api ref: list_web_push_integrations

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

magicbell integration list_web_push

Delete an EventSource integration

api ref: delete_eventsource_integration

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

magicbell integration delete_eventsource

Flags

Name	Required
id	false

List all GitHub integrations

api ref: list_github_integrations

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

magicbell integration list_github

Save a SendGrid integration

api ref: save_sendgrid_integration

Updates or creates the SendGrid integration for the project.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

api_key

string required

The API key for Sendgrid

from

object

Show child attributes

string required

The email address to send from

format: email

name

nullable string

The name to send from

reply_to

object

Show child attributes

name

nullable string

The name to reply to

string required

The email address to reply to

format: email

Delete a Slack integration

api ref: delete_slack_integration

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

magicbell integration delete_slack

Flags

Name	Required
id	false

Delete a Stripe integration

api ref: delete_stripe_integration

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

magicbell integration delete_stripe

Flags

Name	Required
id	false

List all Twilio integrations

api ref: list_twilio_integrations

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

magicbell integration list_twilio

List all Expo integrations

api ref: list_expo_integrations

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

magicbell integration list_expo

List all FCM integrations

api ref: list_fcm_integrations

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

magicbell integration list_fcm

Delete an Inbox integration

api ref: delete_inbox_integration

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

magicbell integration delete_inbox

Flags

Name	Required
id	false

Start a Web Push installation

api ref: start_web_push_installation

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.

magicbell integration start_web_push_installation

Save a FCM integration

api ref: save_fcm_integration

Updates or creates the FCM integration for the project.

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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

Save a Mailgun integration

api ref: save_mailgun_integration

Updates or creates the Mailgun integration for the project.

magicbell integration save_mailgun \
  --data '{"from":{"name":"Example","email":"hello@example.com"},"api_key":"key-3ax6xnjp29jd6fds4gc373sgvjxteol0","region":"us","domain":"example.com"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

api_key

string required

min length: 1

domain

string required

min length: 1

from

object

Show child attributes

string required

The email address to send from

format: email

name

nullable string

The name to send from

region

string required

Possible enum values:

Notification

List all notifications

api ref: list_notifications

Lists all notifications for a user.

magicbell notification list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false
status	false
category	false
topic	false

Archive all notifications

api ref: archive_all_notifications

Archive all notifications.

magicbell notification archive_all

Flags

Name	Required
category	false
topic	false

Mark all notifications read

api ref: mark_all_notifications_read

Marks all notifications as read.

magicbell notification mark_all_read

Flags

Name	Required
category	false
topic	false

Fetch a notification

api ref: fetch_notification

Gets a notification by ID.

magicbell notification fetch \
  --notification_id '{notification_id}'

Flags

Name	Required
notification_id	true

Archive a notification

api ref: archive_notification

Archive a notification.

magicbell notification archive \
  --notification_id '{notification_id}'

Flags

Name	Required
notification_id	true

Mark a notification read

api ref: mark_notification_read

Marks a notification as read.

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

Flags

Name	Required
notification_id	true

Unarchive a notification

api ref: unarchive_notification

Unarchives a notification.

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

Flags

Name	Required
notification_id	true

Mark a notification unread

api ref: mark_notification_unread

Marks a notification as unread.

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

Flags

Name	Required
notification_id	true

User

List all users

api ref: list_users

Lists all users in the project.

magicbell user list

Flags

Name	Required
limit	false
starting_after	false
ending_before	false
query	false

Delete an user's APNs token

api ref: delete_user_apns_token

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.

magicbell user delete_apns_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Fetch an user's APNs token

api ref: fetch_user_apns_token

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.

magicbell user fetch_apns_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

List an user's Expo tokens

api ref: list_user_expo_tokens

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.

magicbell user list_expo_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

Fetch an user's Expo token

api ref: fetch_user_expo_token

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.

magicbell user fetch_expo_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

List an user's Slack tokens

api ref: list_user_slack_tokens

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.

magicbell user list_slack_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

List an user's Teams tokens

api ref: list_user_teams_tokens

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.

magicbell user list_teams_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

Delete an user's Teams token

api ref: delete_user_teams_token

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.

magicbell user delete_teams_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Save a user

api ref: save_user

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

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

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

created_at

nullable string

format: date-time

custom_attributes

nullable object

nullable string

external_id

nullable string

first_name

nullable string

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

Delete a user

api ref: delete_user

Removes a user and all associated data from the project.

magicbell user delete \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true

List an user's Inbox tokens

api ref: list_user_inbox_tokens

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.

magicbell user list_inbox_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

List an user's FCM tokens

api ref: list_user_fcm_tokens

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.

magicbell user list_fcm_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

Fetch an user's FCM token

api ref: fetch_user_fcm_token

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.

magicbell user fetch_fcm_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Fetch an user's Teams token

api ref: fetch_user_teams_token

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.

magicbell user fetch_teams_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Fetch an user's Inbox token

api ref: fetch_user_inbox_token

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.

magicbell user fetch_inbox_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Delete an user's Expo token

api ref: delete_user_expo_token

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.

magicbell user delete_expo_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Delete an user's FCM token

api ref: delete_user_fcm_token

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.

magicbell user delete_fcm_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Delete an user's Slack token

api ref: delete_user_slack_token

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.

magicbell user delete_slack_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Fetch an user's Web Push token

api ref: fetch_user_web_push_token

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.

magicbell user fetch_web_push_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Delete an user's Inbox token

api ref: delete_user_inbox_token

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.

magicbell user delete_inbox_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

List an user's APNs tokens

api ref: list_user_apns_tokens

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.

magicbell user list_apns_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

Fetch an user's Slack token

api ref: fetch_user_slack_token

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.

magicbell user fetch_slack_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

List an user's Web Push tokens

api ref: list_user_web_push_tokens

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.

magicbell user list_web_push_tokens \
  --user_id '{user_id}'

Flags

Name	Required
user_id	true
limit	false
starting_after	false
ending_before	false

Delete an user's Web Push token

api ref: delete_user_web_push_token

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.

magicbell user delete_web_push_token \
  --user_id '{user_id}' \
  --token_id '{token_id}'

Flags

Name	Required
user_id	true
token_id	true

Workflow

Save workflow definition

api ref: save_workflow

Creates or updates a workflow definition for the project

magicbell workflow save \
  --data '{"steps":[{"command":"broadcast:send","input":{"channel":"in_app"}},{"command":"broadcast:send","if":"{{notification.unseen}} == false","input":{"channel":"email"}}],"key":"project"}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

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\_\:]+$

nullable string

input

nullable object

Fetch workflow definition

api ref: fetch_workflow

Retrieves a workflow definition by key

magicbell workflow fetch

Execute workflow

api ref: create_workflow_run

Executes a workflow with the provided input parameters

magicbell workflow create_run \
  --data '{"key":"magicbell:signup","input":{"user":{"id":"123","name":"John Doe"}}}'

Flags

Name	Required
data	true

Data

This command expects a --data argument. The data argument takes a JSON object matching the following spec:

input

nullable object

key

string required

pattern: ^[A-Za-z0-9\_\.\-\:]+$

Get workflow run status

api ref: fetch_workflow_run

Retrieves the status and details of a workflow run

magicbell workflow fetch_run \
  --run_id '{run_id}'

Flags

Name	Required
run_id	true

List workflow runs

api ref: list_workflow_runs

Retrieves all runs for a specific workflow

magicbell workflow list_runs \
  --workflow_key '{workflow_key}'

Flags

Name	Required
workflow_key	true