docs api reference API (v2) Reference Introduction Base URL: https://api.magicbell.com/v2
For authentication, rate limits, and errors, please refer to the API documentation .
Broadcasts Broadcasts let you fan out an announcement to every relevant user or topic. Use these APIs to create announcements, inspect their status, and audit how they generated notifications and deliveries across your project.
Related guides:
Broadcast Primitive POST /broadcasts
GET /broadcasts/{broadcast_id}
GET /broadcastsThe Broadcasts object Attributes action_url
nullable string
The URL recipients will be directed to when interacting with the broadcast.
The label used to group broadcasts.
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
The body content delivered with the broadcast.
The timestamp when the broadcast was created.
custom_attributes
nullable object
Arbitrary custom data associated with the broadcast.
The unique id for this broadcast.
Channel- or provider-specific values that override the defaults.
Overrides that are scoped to individual delivery channels.
Overrides for email notifications.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
Overrides for SMS notifications.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
Overrides for in-app notifications.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
Overrides for mobile push notifications.
action_url
nullable string
The link associated with the channel-specific notification.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
Overrides that are scoped to specific providers for a channel.
Provider-specific overrides for Mailgun.
Provider-specific overrides for AWS SES.
Provider-specific overrides for Sendgrid.
Provider-specific overrides for Firebase Cloud Messaging.
Provider-specific overrides for Expo push notifications.
Provider-specific overrides for Apple Push Notification service.
Provider-specific overrides for Slack.
Provider-specific overrides for the web push provider.
Provider-specific overrides for Microsoft Teams.
Provider-specific overrides for Twilio.
recipients
nullable array required
A collection of users or filters that determine who receives the broadcast.
min items: 1
max items: 1000
The recipient specification for the broadcast.
The runtime state of the broadcast execution.
The overall processing status of the broadcast.
Possible enum values:
enqueued
processing
processed
The summary counts for total recipients and failures.
The number of recipients that the broadcast was sent to.
The number of failures while processing the broadcast.
errors
nullable array required
A list of errors encountered while processing the broadcast.
The details about the processing error.
The subject or headline that will be shown to recipients.
min length: 1
max length: 255
The topic that further classifies the broadcast.
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
{
"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": "[email protected] ",
"first_name": "Person",
"last_name": "Doe",
"custom_attributes": {
"plan": "enterprise",
"pricing_version": "v10",
"preferred_pronoun": "They"
},
"phone_numbers": [
"+1 5005550001"
]
}
],
"overrides": {}
}
Create a broadcast Creates a new broadcast. When a broadcast is created, it generates individual notifications for relevant users within the project.
Request body action_url
nullable string
The URL recipients will be directed to when interacting with the broadcast.
The label used to group broadcasts.
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
The body content delivered with the broadcast.
The timestamp when the broadcast was created.
custom_attributes
nullable object
Arbitrary custom data associated with the broadcast.
The unique id for this broadcast.
Channel- or provider-specific values that override the defaults.
Overrides that are scoped to specific providers for a channel.
Provider-specific overrides for Sendgrid.
Provider-specific overrides for Twilio.
Provider-specific overrides for Mailgun.
Provider-specific overrides for Expo push notifications.
Provider-specific overrides for Apple Push Notification service.
Provider-specific overrides for Slack.
Provider-specific overrides for Microsoft Teams.
Provider-specific overrides for AWS SES.
Provider-specific overrides for Firebase Cloud Messaging.
Provider-specific overrides for the web push provider.
Overrides that are scoped to individual delivery channels.
Overrides for in-app notifications.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
Overrides for mobile push notifications.
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
The channel-specific title.
min length: 1
max length: 255
Overrides for email notifications.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
Overrides for SMS notifications.
The channel-specific title.
min length: 1
max length: 255
The channel-specific content.
action_url
nullable string
The link associated with the channel-specific notification.
recipients
nullable array required
A collection of users or filters that determine who receives the broadcast.
min items: 1
max items: 1000
The recipient specification for the broadcast.
The runtime state of the broadcast execution.
The overall processing status of the broadcast.
Possible enum values:
enqueued
processing
processed
The summary counts for total recipients and failures.
The number of recipients that the broadcast was sent to.
The number of failures while processing the broadcast.
errors
nullable array required
A list of errors encountered while processing the broadcast.
The details about the processing error.
The subject or headline that will be shown to recipients.
min length: 1
max length: 255
The topic that further classifies the broadcast.
max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/broadcasts' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"id":"d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b","title":"Hello, World!","content":"I come from broadcast","action_url":"https://example.com","category":"example","topic":"example","custom_attributes":{},"recipients":[{"external_id":"83d987a-83fd034","email":"[email protected] ","first_name":"Person","last_name":"Doe","custom_attributes":{"plan":"enterprise","pricing_version":"v10","preferred_pronoun":"They"},"phone_numbers":["+1 5005550001"]}],"overrides":{}}'
{
"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": "[email protected] ",
"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}
Retrieves detailed information about a specific broadcast by its ID. Includes the broadcast's configuration and current status.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/broadcasts/{broadcast_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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": "[email protected] ",
"first_name": "Person",
"last_name": "Doe",
"custom_attributes": {
"plan": "enterprise",
"pricing_version": "v10",
"preferred_pronoun": "They"
},
"phone_numbers": ["+1 5005550001"]
}
],
"overrides": {}
}
List all broadcasts Retrieves a paginated list of broadcasts for the project. Returns basic information about each broadcast including its creation time and status.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/broadcasts' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"id": "d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b",
"title": "Hello, World!",
"content": "I come from broadcast",
"action_url": "https://example.com",
"category": "example",
"topic": "example",
"custom_attributes": {},
"recipients": [
{
"external_id": "83d987a-83fd034",
"email": "[email protected] ",
"first_name": "Person",
"last_name": "Doe",
"custom_attributes": {
"plan": "enterprise",
"pricing_version": "v10",
"preferred_pronoun": "They"
},
"phone_numbers": ["+1 5005550001"]
}
],
"overrides": {}
}
],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Channels Channels represent the mediums such as Email, Push, SMS, Slack, through which deliveries happen. These routes configure how each channel behaves inside a project, ensuring every notification honors user preferences and branding.
Related guides:
Channel Primitive Mobile Push APIs dedicated to the Mobile Push channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
PUT /channels/mobile_push/apns/tokens
GET /channels/mobile_push/apns/tokens/{token_id}
DELETE /channels/mobile_push/apns/tokens/{token_id}
GET /channels/mobile_push/apns/tokens
PUT /channels/mobile_push/expo/tokens
GET /channels/mobile_push/expo/tokens/{token_id}
DELETE /channels/mobile_push/expo/tokens/{token_id}
GET /channels/mobile_push/expo/tokens
PUT /channels/mobile_push/fcm/tokens
GET /channels/mobile_push/fcm/tokens/{token_id}
DELETE /channels/mobile_push/fcm/tokens/{token_id}
GET /channels/mobile_push/fcm/tokensThe Mobile Push object Attributes The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.
pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
created_at
string required
The timestamp when the token was created.
device_token
string required
The APNs device token to register with MagicBell.
discarded_at
nullable string
The timestamp when the token was discarded, if applicable.
The unique identifier for the token.
The APNs environment this token belongs to. If omitted we assume it targets production.
updated_at
nullable string
The timestamp when the token metadata last changed.
{
"created_at": "2021-01-01T00:00:00Z",
"device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"installation_id": "development",
"updated_at": "2021-01-01T00:00:00Z"
}Save an APNs token PUT /channels/mobile_push/apns/tokens
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 The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.
pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
device_token
string required
The APNs device token to register with MagicBell.
The APNs environment this token belongs to. If omitted we assume it targets production.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'
{
"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}
Fetches details of a specific APNs token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's APNs tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all APNs tokens GET /channels/mobile_push/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/mobile_push/apns/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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
Saves the Expo token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
Request body device_token
string required
The Expo push token returned by the Expo client.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"device_token":"ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"}'
{
"device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
}
Fetch an Expo token GET /channels/mobile_push/expo/tokens/{token_id}
Fetches details of a specific Expo token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's Expo tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all Expo tokens GET /channels/mobile_push/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/mobile_push/expo/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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
Saves the FCM token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
Request body device_token
string required
The Firebase Cloud Messaging device registration token to associate with the user.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"device_token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt","installation_id":"development"}'
{
"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}
Fetches details of a specific FCM token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's FCM tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all FCM tokens GET /channels/mobile_push/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/mobile_push/fcm/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"installation_id": "development",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}In App APIs dedicated to the In App channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
PUT /channels/in_app/inbox/tokens
GET /channels/in_app/inbox/tokens/{token_id}
DELETE /channels/in_app/inbox/tokens/{token_id}
GET /channels/in_app/inbox/tokensThe In App object Attributes connection_id
nullable string
Realtime connection ID to restrict delivery to a specific Ably connection.
created_at
string required
The timestamp when the token was created.
discarded_at
nullable string
The timestamp when the token was discarded, if applicable.
The unique identifier for the token.
The in-app inbox token generated for this user.
updated_at
nullable string
The timestamp when the token metadata last changed.
{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"updated_at": "2021-01-01T00:00:00Z"
}Save an Inbox token PUT /channels/in_app/inbox/tokens
Saves the Inbox token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
Request body connection_id
nullable string
Realtime connection ID to restrict delivery to a specific Ably connection.
The in-app inbox token generated for this user.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"token":"eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt"}'
{
"token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt"
}
Fetch an Inbox token GET /channels/in_app/inbox/tokens/{token_id}
Fetches details of a specific Inbox token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's Inbox tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all Inbox tokens GET /channels/in_app/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/in_app/inbox/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Slack APIs dedicated to the Slack channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
PUT /channels/slack/magicbell_slackbot/tokens
GET /channels/slack/magicbell_slackbot/tokens/{token_id}
DELETE /channels/slack/magicbell_slackbot/tokens/{token_id}
GET /channels/slack/magicbell_slackbot/tokens
PUT /channels/slack/tokens
GET /channels/slack/tokens/{token_id}
DELETE /channels/slack/tokens/{token_id}
GET /channels/slack/tokensThe Slack object Attributes created_at
string required
The timestamp when the token was created.
discarded_at
nullable string
The timestamp when the token was discarded, if applicable.
The unique identifier for the token.
channel_id
string required
The ID of the Slack channel this installation is associated with
installation_id
string required
A unique identifier for this Slack workspace installation
The OAuth scope granted during installation
updated_at
nullable string
The timestamp when the token metadata last changed.
Obtained directly from the incoming_webhook object in the installation response from the Slack API.
The URL for the incoming webhook from Slack
{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}Save a MagicBell SlackBot token PUT /channels/slack/magicbell_slackbot/tokens
Saves the MagicBell SlackBot token for the authenticated user. This token serves as a credential for accessing channel-specific functionality. Each token is unique to the user and channel combination, allowing for direct communication with the user via the channel.
Request body The OAuth scope granted during installation
channel_id
string required
The ID of the Slack channel this installation is associated with
installation_id
string required
A unique identifier for this Slack workspace installation
Obtained directly from the incoming_webhook object in the installation response from the Slack API.
The URL for the incoming webhook from Slack
Request
curl magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"webhook":{"url":"https://example.com/webhook"}}'
{
"webhook": {
"url": "https://example.com/webhook"
}
}
Fetch a MagicBell SlackBot token GET /channels/slack/magicbell_slackbot/tokens/{token_id}
Fetches details of a specific MagicBell SlackBot token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}Delete a MagicBell SlackBot token DELETE /channels/slack/magicbell_slackbot/tokens/{token_id}
Deletes one of the authenticated user's MagicBell SlackBot tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all MagicBell SlackBot tokens GET /channels/slack/magicbell_slackbot/tokens
Lists all MagicBell SlackBot tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/slack/magicbell_slackbot/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Save a Slack token PUT /channels/slack/tokens
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 The OAuth scope granted during installation
channel_id
string required
The ID of the Slack channel this installation is associated with
installation_id
string required
A unique identifier for this Slack workspace installation
Obtained directly from the incoming_webhook object in the installation response from the Slack API.
The URL for the incoming webhook from Slack
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/slack/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"webhook":{"url":"https://example.com/webhook"}}'
{
"webhook": {
"url": "https://example.com/webhook"
}
}
Fetch a Slack token GET /channels/slack/tokens/{token_id}
Fetches details of a specific Slack token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/slack/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's Slack tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/slack/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all Slack tokens GET /channels/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/slack/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Teams APIs dedicated to the Teams channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
PUT /channels/teams/tokens
GET /channels/teams/tokens/{token_id}
DELETE /channels/teams/tokens/{token_id}
GET /channels/teams/tokensThe Teams object Attributes created_at
string required
The timestamp when the token was created.
discarded_at
nullable string
The timestamp when the token was discarded, if applicable.
The unique identifier for the token.
updated_at
nullable string
The timestamp when the token metadata last changed.
{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z"
}Save a Teams token PUT /channels/teams/tokens
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
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/teams/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Fetch a Teams token GET /channels/teams/tokens/{token_id}
Fetches details of a specific Teams token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/teams/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's Teams tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/teams/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all Teams tokens GET /channels/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/teams/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}User Preferences
PUT /channels/user_preferences
GET /channels/user_preferencesThe User Preferences object Attributes max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
The User Preferences object
{
"categories": [
{
"key": "category_1",
"label": "Category 1",
"channels": [
{
"name": "email",
"label": "Email",
"enabled": true
}
]
}
]
}Save channel preferences PUT /channels/user_preferences
Save a user's channel preferences.
Request body max length: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/user_preferences' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"categories":[{"key":"category_1","label":"Category 1","channels":[{"name":"email","label":"Email","enabled":true}]}]}'
Fetch channel preferences GET /channels/user_preferences
Fetch a user's channel delivery preferences.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/user_preferences' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"categories": [
{
"key": "category_1",
"label": "Category 1",
"channels": [
{
"name": "email",
"label": "Email",
"enabled": true
}
]
}
]
}Web Push APIs dedicated to the Web Push channel. Use them to connect devices, rotate credentials, and troubleshoot delivery for this medium.
PUT /channels/web_push/tokens
GET /channels/web_push/tokens/{token_id}
DELETE /channels/web_push/tokens/{token_id}
GET /channels/web_push/tokensThe Web Push object Attributes created_at
string required
The timestamp when the token was created.
discarded_at
nullable string
The timestamp when the token was discarded, if applicable.
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.
The unique identifier for the token.
The encryption keys from the PushSubscription.getKey() method, needed to encrypt push messages for this subscription.
The P-256 ECDH public key obtained from PushSubscription.getKey('p256dh'). Used to encrypt push messages for this subscription.
The authentication secret obtained from PushSubscription.getKey('auth'). Used to encrypt push messages for this subscription.
updated_at
nullable string
The timestamp when the token metadata last changed.
{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
"id": "123",
"keys": {
"auth": "GoIO2ulhtQuyBM64lZuFuw",
"p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
},
"updated_at": "2021-01-01T00:00:00Z"
}Save a Web Push token PUT /channels/web_push/tokens
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 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.
The encryption keys from the PushSubscription.getKey() method, needed to encrypt push messages for this subscription.
The P-256 ECDH public key obtained from PushSubscription.getKey('p256dh'). Used to encrypt push messages for this subscription.
The authentication secret obtained from PushSubscription.getKey('auth'). Used to encrypt push messages for this subscription.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/channels/web_push/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"endpoint":"https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN","keys":{"p256dh":"BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0","auth":"GoIO2ulhtQuyBM64lZuFuw"}}'
{
"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}
Fetches details of a specific Web Push token belonging to the authenticated user. Returns information about the token's status, creation date, and any associated metadata. Users can only access their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/web_push/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes one of the authenticated user's Web Push tokens. This permanently invalidates the specified token, preventing it from being used for future channel access. This action cannot be undone. Users can only revoke their own tokens.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/channels/web_push/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List all Web Push tokens GET /channels/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/channels/web_push/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"endpoint": "https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN",
"id": "123",
"keys": {
"auth": "GoIO2ulhtQuyBM64lZuFuw",
"p256dh": "BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0"
},
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Events Events capture everything that happens across deliveries. Query this stream to audit what occurred, troubleshoot delivery issues, and power observability dashboards.
Related guides:
Delivery Primitive GET /events/{event_id}
GET /eventsThe Events object Attributes The numeric code that categorizes the event.
Additional contextual attributes for the event.
The unique identifier for the event.
The severity level assigned to the event.
A human-readable log message.
The raw payload delivered by the event source.
The time at which the event was recorded.
The type of event that occurred.
{
"id": "123",
"type": "example_type",
"timestamp": "2021-01-01T00:00:00Z"
}Fetch an event Fetches a project event by its ID.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/events/{event_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"type": "example_type",
"timestamp": "2021-01-01T00:00:00Z"
}List all events Retrieves a paginated list of events for the project.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/events' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"id": "123",
"type": "example_type",
"timestamp": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Integrations Integrations connect MagicBell to external providers for delivery, data ingestion, and automation. Use these grouped APIs to configure providers, run installation flows, and receive incoming events.
Related guides:
Integration Primitive APNs Upload APNs credentials to deliver native iOS, iPadOS, and macOS push notifications.
PUT /integrations/apns
DELETE /integrations/apns
GET /integrations/apnsThe APNs object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"app_id": "com.example.myapp",
"certificate": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----",
"key_id": "ABCD1234EF",
"team_id": "ABCD1234EF",
"badge": "unread"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save an APNs integration Updates or creates the APNs integration for the project.
Request body 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]+)*$
Controls whether the app icon badge counts unread or unseen notifications.
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?$
The 10-character Key ID from your Apple Developer account used with the P8 certificate.
min length: 10
max length: 10
Internal payload format version used by MagicBell.
The Apple Developer Team ID that owns the configured key.
min length: 10
max length: 10
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/apns' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"app_id":"com.example.myapp","certificate":"-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----","key_id":"ABCD1234EF","team_id":"ABCD1234EF","badge":"unread"}'
{
"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 Deletes the APNs integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/apns' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all APNs integrations Retrieves the current APNs integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/apns' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"app_id": "com.example.myapp",
"certificate": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgHnr4B2P+by++FGu/th0a44E8chJl5v5Vo4gq0YHw6e6gCgYIKoZIzj0DAQehRANCAARCg1MRibnfyeX5mx6+Rtfzzn7UhJP/oaqL4RzSmDuTsd3BTX33cuQ0gWHe20R2m1bLAkI1wrp+zbWOlAOAD7KX\n-----END PRIVATE KEY-----",
"key_id": "ABCD1234EF",
"team_id": "ABCD1234EF",
"badge": "unread"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Expo Send Expo push notifications to React Native apps with zero extra plumbing.
PUT /integrations/expo
DELETE /integrations/expo
GET /integrations/expoThe Expo object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"access_token": "expo_access_token"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save an Expo integration Updates or creates the Expo integration for the project.
Request body access_token
string required
The Expo access token used to authenticate push notifications.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/expo' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"access_token":"expo_access_token"}'
{
"access_token": "expo_access_token"
}
Delete an Expo integration Deletes the Expo integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/expo' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Expo integrations Retrieves the current Expo integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/expo' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"access_token": "expo_access_token"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}FCM Connect FCM to reach Android devices and browsers that rely on Google's messaging infrastructure.
PUT /integrations/fcm
DELETE /integrations/fcm
GET /integrations/fcmThe FCM object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"type": "service_account",
"project_id": "platform-development",
"private_key_id": "1935e74178f6ef0bbc23fb3538255f8281093bf2",
"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n",
"client_email": "firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com",
"client_id": "117893100789081023083",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com",
"universe_domain": "googleapis.com"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a FCM integration Updates or creates the FCM integration for the project.
Request body auth_provider_x509_cert_url
string required
URL for Google's OAuth provider x509 certificates used to validate tokens.
OAuth authorization endpoint used when exchanging Firebase credentials.
client_email
string required
The client email address from the Firebase service account.
The numeric client identifier for the Firebase service account.
client_x509_cert_url
string required
URL to the public x509 certificate for this service account.
private_key
string required
The PEM encoded service account private key used to sign Firebase credentials.
pattern: ^-+?\s?BEGIN[A-Z ]+-+\n([A-Za-z0-9+/\r\n]+={0,2})\n-+\s?END[A-Z ]+-+\n?$
private_key_id
string required
Identifier of the private key inside the downloaded service account JSON.
project_id
string required
The Firebase project ID associated with this service account.
OAuth token endpoint used to mint access tokens for FCM.
Indicates the kind of Google credential. Service accounts always use the service_account type.
universe_domain
string required
The Google Cloud universe domain hosting the Firebase APIs.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/fcm' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"type":"service_account","project_id":"platform-development","private_key_id":"1935e74178f6ef0bbc23fb3538255f8281093bf2","private_key":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n","client_email":"firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com","client_id":"117893100789081023083","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com","universe_domain":"googleapis.com"}'
{
"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 Deletes the FCM integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/fcm' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all FCM integrations Retrieves the current FCM integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/fcm' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"type": "service_account",
"project_id": "platform-development",
"private_key_id": "1935e74178f6ef0bbc23fb3538255f8281093bf2",
"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7/GBHM4AK4/8c\nZyvJfdzjBzfA48tV9T3N4hBCb4E66jIz+oztH9oSngEfIVO/L1dWjK1OlN0cqJ0f\nQaKq1eycSjmwfTR3HGNjQQyoGQ4BFBdyqT5rRDDZLPI2LoR0dtQXcBtiFpJF2t8e\niDmpl3d/ipuKMtBRzjYPqzP0qv3YkPmw2v5FqKK9EIaHRtOhd2R28F5FE+kF1dvB\nt7fEeVtKcQJcSwDUQ8HEshlWSx6azGd4jxf9jHRXWumXYfTA6NMA7EUTDJVus3vU\ny9MCv2KwZO/dzlQygY0BM9FHPSzZRIiHUx+DH6gYl2uWJatluHz58lj3r5mo/Ssc\nyP3TrqOnAgMBAAECggEAWAnDe0UCt9b8QGyPBK/V1VspgMQOE+UlOzkenUaEUreg\nqFg0TM8ofaSS6OXeR0DgGdALUCyGeyf6YcuG55QFWlKmvuF8QzY/05mA2G7XcKjc\nrF3Xtju61tLmYnqZnMOT46AkquTgPyfYa3+n5aVimRAsdOYESvOUvPTUgcbc2GGK\nC2h2MUCoRKuhzbGx847XJmINRE+xaht4hDMhzhMBVrgGGyQ3sIdbCxpbiQR6QH2H\npITrSnd4hlKRPREWS/D4FUKP/ucXdORP9SUi0R64NRZ3GvT1HvpVZ9fOXwIACdAG\n9fpIQbsmIgxhgZ5ZjuGz/nFi2KQ2Y8rEycQmnHd4QQKBgQD4LVFL93E4qwr7Eruj\nFjyxGYYi2PhVxvrpiSD6ziK3HUjAxat6OcoElJx7WEFWHmi7KRgehqcl40A8Coav\n9DGBwnSM2AYKgzOqMqzjK71TFOQsJdGEYThnhiL2FoQeptgskVS7J9MMBPTnyl7D\nYObINwGbg9auVp66rj5W+dymZwKBgQDB6VdpxJpU9hXBW+8nJESduhzpYiHoe1kN\nyka90dQDOe2b/R7bnF1Ggte6Ll1dMs3xLhN1Mm2XTcX2zmzM15C0E4+1t1LXXzAo\nO2P+riEmCIUc1i0yNMVgEKXiOBBYgKauE3fT88c4dw2JAT0QlifJ0h8kRPNhUaq9\nespjleNQwQKBgHUzwZ7knn2qmSb1M9PTHppseWJfoPexXrGHZyHK064ykDcpos+4\nFuWO4U+G4GQxPDiXMaLI6IsGBUHVnsHdyruC/9O7+S5hw7Zu9CLcdy6TQSZwPcAM\nwbxyJnSdMYvgM1roz2ELb6nPdXE5qwMN8i8/euzcmDgBBDkZLKuamE+lAoGBAKb7\nvd7DAvPvBkUAWi2mub/pqUQA0ZpVvhZ1/f0wWBZ/J/KQQqZzPI+f1Q3rJ1M+kMIE\nH5Vo257TxooGsQKlD2NDBRpCx//XZK0Al9eVM86Av8BZX4pAj0dujqsEBG9yOhbl\nhObsor4pJ2q3ulIyPAk7/L1K8xr3LMUGnIqtZJcBAoGAEQffqGbnaOG8Ue3++bLP\nN6XlAyt5UajAd1CycIHgDvbW0CkWoI70Bg7QNqMYJe6DareH4vRpdB3tw6zNP7qN\n0Bd04L8+zUYN+VqNJ70d7Xn+k2rY7STlgU3vwOzHFwu4wK2A7e+aAZ8AjC+Sr0ZM\nps+wuWO8MN5yQTBZvAEIfQs=\n-----END PRIVATE KEY-----\n",
"client_email": "firebase-adminsdk-qwhtp@platform-development.iam.gserviceaccount.com",
"client_id": "117893100789081023083",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-qwhtp%40magicbell-development.iam.gserviceaccount.com",
"universe_domain": "googleapis.com"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Inbox Manage integrations that sync data into the MagicBell Inbox surfaces, including hosted widgets and embeddable inboxes.
PUT /integrations/inbox/installations
POST /integrations/inbox/installations/start
PUT /integrations/inbox
DELETE /integrations/inbox
GET /integrations/inboxThe Inbox object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"images": {
"emptyInboxUrl": ""
},
"locale": "de",
"theme": {
"banner": {
"backgroundColor": "#F8F5FF",
"fontSize": "14px",
"textColor": "#3A424D"
},
"dialog": {
"accentColor": "#5225C1",
"backgroundColor": "#F5F5F5",
"textColor": "#313131"
},
"footer": {
"backgroundColor": "#FFFFFF",
"borderRadius": "16px",
"fontFamily": "inherit",
"fontSize": "15px",
"textColor": "#5225C1"
},
"header": {
"backgroundColor": "#FFFFFF",
"borderRadius": "16px",
"fontFamily": "inherit",
"fontSize": "15px",
"textColor": "#5225C1"
},
"icon": {
"borderColor": "#EDEDEF",
"width": "24px"
},
"unseenBadge": {
"backgroundColor": "#F80808"
}
}
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save an Inbox installation PUT /integrations/inbox/installations
Creates a new installation of a Inbox integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
Request body images
nullable object required
Image overrides for assets used in the inbox UI.
emptyInboxUrl
string required
URL for the illustration shown when the inbox is empty.
locale
nullable string required
Locale code (ISO language tag) used to localize built-in strings.
theme
nullable object required
Visual customization options for the hosted inbox widget.
Footer styling for the inbox modal.
backgroundColor
string required
Footer background color.
borderRadius
string required
Border radius applied to the footer container.
Font size used in the footer.
Styling overrides for notification list items.
Base styles applied to every notification item.
Default text color for notifications.
borderRadius
string required
Border radius applied to each notification card.
backgroundColor
string required
Background color for notifications in their default state.
Styles applied when a notification is hovered.
backgroundColor
string required
Background color on hover.
Accent colors for notification state indicators.
Color used for the state indicator.
CSS margin applied around each notification card.
fontFamily
string required
Font family for notification text.
Font size for notification text.
Overrides for unseen notifications.
Text color used when a notification is unseen.
backgroundColor
string required
Background color applied to unseen notifications.
Hover styles for unseen notifications.
backgroundColor
string required
Background color on hover for unseen notifications.
State indicator styling for unseen notifications.
Color for the unseen state indicator.
Overrides for unread notifications.
backgroundColor
string required
Background color applied to unread notifications.
Hover styles for unread notifications.
backgroundColor
string required
Background color on hover for unread notifications.
State indicator styling for unread notifications.
Color for the unread state indicator.
Text color used when a notification is unread.
Styling for confirmation and action dialogs.
backgroundColor
string required
Dialog background color.
accentColor
string required
Accent color for dialog buttons and highlights.
Launcher icon styling overrides.
borderColor
string required
CSS color used for the icon border.
Width of the launcher icon (any CSS length).
Top banner styling options.
Font size for banner text.
backgroundColor
string required
Banner background color.
Opacity applied to the banner background.
Badge styling for unseen notification counts.
backgroundColor
string required
Badge background color.
Header styling for the inbox modal.
Font size used in the header.
backgroundColor
string required
Header background color.
borderRadius
string required
Border radius applied to the header container.
fontFamily
string required
CSS font family for the header title.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/inbox/installations' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"images":{"emptyInboxUrl":""},"locale":"de","theme":{"banner":{"backgroundColor":"#F8F5FF","fontSize":"14px","textColor":"#3A424D"},"dialog":{"accentColor":"#5225C1","backgroundColor":"#F5F5F5","textColor":"#313131"},"footer":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"header":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"icon":{"borderColor":"#EDEDEF","width":"24px"},"unseenBadge":{"backgroundColor":"#F80808"}}}'
{
"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
Initiates the installation flow for an Inbox integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/integrations/inbox/installations/start' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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 Updates or creates the Inbox integration for the project.
Request body images
nullable object required
Image overrides for assets used in the inbox UI.
emptyInboxUrl
string required
URL for the illustration shown when the inbox is empty.
locale
nullable string required
Locale code (ISO language tag) used to localize built-in strings.
theme
nullable object required
Visual customization options for the hosted inbox widget.
Styling overrides for notification list items.
Base styles applied to every notification item.
Default text color for notifications.
borderRadius
string required
Border radius applied to each notification card.
backgroundColor
string required
Background color for notifications in their default state.
Styles applied when a notification is hovered.
backgroundColor
string required
Background color on hover.
Accent colors for notification state indicators.
Color used for the state indicator.
CSS margin applied around each notification card.
fontFamily
string required
Font family for notification text.
Font size for notification text.
Overrides for unseen notifications.
Hover styles for unseen notifications.
backgroundColor
string required
Background color on hover for unseen notifications.
State indicator styling for unseen notifications.
Color for the unseen state indicator.
Text color used when a notification is unseen.
backgroundColor
string required
Background color applied to unseen notifications.
Overrides for unread notifications.
Text color used when a notification is unread.
backgroundColor
string required
Background color applied to unread notifications.
Hover styles for unread notifications.
backgroundColor
string required
Background color on hover for unread notifications.
State indicator styling for unread notifications.
Color for the unread state indicator.
Styling for confirmation and action dialogs.
backgroundColor
string required
Dialog background color.
accentColor
string required
Accent color for dialog buttons and highlights.
Launcher icon styling overrides.
borderColor
string required
CSS color used for the icon border.
Width of the launcher icon (any CSS length).
Top banner styling options.
backgroundColor
string required
Banner background color.
Opacity applied to the banner background.
Font size for banner text.
Badge styling for unseen notification counts.
backgroundColor
string required
Badge background color.
Header styling for the inbox modal.
fontFamily
string required
CSS font family for the header title.
Font size used in the header.
backgroundColor
string required
Header background color.
borderRadius
string required
Border radius applied to the header container.
Footer styling for the inbox modal.
Font size used in the footer.
backgroundColor
string required
Footer background color.
borderRadius
string required
Border radius applied to the footer container.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/inbox' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"images":{"emptyInboxUrl":""},"locale":"de","theme":{"banner":{"backgroundColor":"#F8F5FF","fontSize":"14px","textColor":"#3A424D"},"dialog":{"accentColor":"#5225C1","backgroundColor":"#F5F5F5","textColor":"#313131"},"footer":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"header":{"backgroundColor":"#FFFFFF","borderRadius":"16px","fontFamily":"inherit","fontSize":"15px","textColor":"#5225C1"},"icon":{"borderColor":"#EDEDEF","width":"24px"},"unseenBadge":{"backgroundColor":"#F80808"}}}'
{
"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
Deletes the Inbox integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/inbox' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Inbox integrations Retrieves the current Inbox integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/inbox' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"images": { "emptyInboxUrl": "" },
"locale": "de",
"theme": {
"banner": {
"backgroundColor": "#F8F5FF",
"fontSize": "14px",
"textColor": "#3A424D"
},
"dialog": {
"accentColor": "#5225C1",
"backgroundColor": "#F5F5F5",
"textColor": "#313131"
},
"footer": {
"backgroundColor": "#FFFFFF",
"borderRadius": "16px",
"fontFamily": "inherit",
"fontSize": "15px",
"textColor": "#5225C1"
},
"header": {
"backgroundColor": "#FFFFFF",
"borderRadius": "16px",
"fontFamily": "inherit",
"fontSize": "15px",
"textColor": "#5225C1"
},
"icon": { "borderColor": "#EDEDEF", "width": "24px" },
"unseenBadge": { "backgroundColor": "#F80808" }
}
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Magicbell Slackbot Provision the hosted Slackbot that delivers actionable notifications into Slack without you maintaining an app. Ideal when you want a turnkey shared Slack experience.
PUT /integrations/magicbell_slackbot/installations
POST /integrations/magicbell_slackbot/installations/start
POST /integrations/magicbell_slackbot/installations/finish
PUT /integrations/magicbell_slackbot
DELETE /integrations/magicbell_slackbot
GET /integrations/magicbell_slackbotThe Magicbell Slackbot object The Magicbell Slackbot object
{
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"enabled": true
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a MagicBell SlackBot installation PUT /integrations/magicbell_slackbot/installations
Creates a new installation of a MagicBell SlackBot integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
Request body access_token
string required
Bot token returned from the Slack OAuth exchange.
Slack app identifier for the installed app.
authed_user
object required
User token returned from the OAuth exchange.
Refresh token for the authed user.
Slack user ID for the installer.
Token type value provided by Slack.
Seconds until the user token expires.
Space-delimited OAuth scopes granted to the user token.
Slack user ID of the installed bot.
Enterprise grid identifier.
Seconds until the bot access token expires.
Unique identifier MagicBell assigns to the Slack installation.
Human readable name for the webhook channel.
configuration_url
string required
URL users can visit to manage the webhook.
Webhook URL that Slack posts events to.
is_enterprise_install
boolean
Indicates whether the installation occurred on an enterprise grid.
Refresh token for regenerating the bot access token.
Space-delimited OAuth scopes granted to the bot token.
Workspace name where the app was installed.
Workspace ID where the app was installed.
Type of bot token returned by Slack.
Request
curl magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot/installations' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"id":"A12345678-T123","access_token":"xoxb-123456789012-1234567890123-12345678901234567890abcdef123456","scope":"identify,commands,bot","team_name":"Team Installing Your App","team_id":"T12345678","enterprise_id":"E12345678","enterprise_name":"Enterprise Grid, Inc.","bot_user_id":"U12345678","app_id":"A12345678","authed_user":{"id":"U12345678","scope":"identify,commands"},"incoming_webhook":{"channel":"C12345678","channel_id":"C12345678","configuration_url":"https://teamname.slack.com/services/B12345678","url":"https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"},"team":{"name":"Team Installing Your App","id":"T123"}}'
{
"id": "A12345678-T123",
"access_token": "xoxb-123456789012-1234567890123-12345678901234567890abcdef123456",
"scope": "identify,commands,bot",
"team_name": "Team Installing Your App",
"team_id": "T12345678",
"enterprise_id": "E12345678",
"enterprise_name": "Enterprise Grid, Inc.",
"bot_user_id": "U12345678",
"app_id": "A12345678",
"authed_user": {
"id": "U12345678",
"scope": "identify,commands"
},
"incoming_webhook": {
"channel": "C12345678",
"channel_id": "C12345678",
"configuration_url": "https://teamname.slack.com/services/B12345678",
"url": "https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"
},
"team": {
"name": "Team Installing Your App",
"id": "T123"
}
}
Start a MagicBell SlackBot installation POST /integrations/magicbell_slackbot/installations/start
Initiates the installation flow for a MagicBell SlackBot integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.
Request body Slack app ID that the installation flow should use.
Optional override for the authorization URL returned to the client.
Additional OAuth scopes to request during installation.
Custom redirect URL to use after OAuth completes.
Request
curl magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot/installations/start' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"app_id":"12345678901","auth_url":"https://example.com/auth","redirect_url":"https://example.com/redirect","extra_scopes":["scope1","scope2"]}'
{
"app_id": "app-id",
"auth_url": "https://slack.com/oauth/v2/authorize?client_id=app-id&scope=channels:read,chat:write",
"scopes": [
"channels:read",
"chat:write"
]
}Finish a MagicBell SlackBot installation POST /integrations/magicbell_slackbot/installations/finish
Completes the installation flow for the MagicBell SlackBot integration. This endpoint is typically called after the user has completed any required authorization steps with MagicBell SlackBot.
Request body The app ID of the Slack app that was originally configured at the project-level.
The code that was returned from the OAuth flow, and found in the query string of the redirect URL.
Request
curl magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot/installations/finish' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"app_id":"12345678901","code":"string","redirect_url":"string"}'
{
"id": "A12345678-T123",
"access_token": "xoxb-123456789012-1234567890123-12345678901234567890abcdef123456",
"scope": "identify,commands,bot",
"team_name": "Team Installing Your App",
"team_id": "T12345678",
"enterprise_id": "E12345678",
"enterprise_name": "Enterprise Grid, Inc.",
"bot_user_id": "U12345678",
"app_id": "A12345678",
"authed_user": {
"id": "U12345678",
"scope": "identify,commands"
},
"incoming_webhook": {
"channel": "C12345678",
"channel_id": "C12345678",
"configuration_url": "https://teamname.slack.com/services/B12345678",
"url": "https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"
},
"team": {
"name": "Team Installing Your App",
"id": "T123"
}
}
Save a MagicBell SlackBot integration PUT /integrations/magicbell_slackbot
Updates or creates the MagicBell SlackBot integration for the project.
Request
curl magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"enabled":true}'
Delete a MagicBell SlackBot integration DELETE /integrations/magicbell_slackbot
Deletes the MagicBell SlackBot integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all MagicBell SlackBot integrations GET /integrations/magicbell_slackbot
Retrieves the current MagicBell SlackBot integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/magicbell_slackbot' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"enabled": true
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Mailgun Connect Mailgun so you can deliver notifications using your existing domains, routes, and analytics.
PUT /integrations/mailgun
DELETE /integrations/mailgun
GET /integrations/mailgunThe Mailgun object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"from": {
"name": "Example",
"email": "[email protected] "
},
"api_key": "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
"region": "us",
"domain": "example.com"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a Mailgun integration Updates or creates the Mailgun integration for the project.
Request body The email address to send from
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/mailgun' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"from":{"name":"Example","email":"[email protected] "},"api_key":"key-3ax6xnjp29jd6fds4gc373sgvjxteol0","region":"us","domain":"example.com"}'
{
"from": {
"name": "Example",
"email": "[email protected] "
},
"api_key": "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
"region": "us",
"domain": "example.com"
}
Delete a Mailgun integration DELETE /integrations/mailgun
Deletes the Mailgun integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/mailgun' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Mailgun integrations Retrieves the current Mailgun integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/mailgun' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"from": {
"name": "Example",
"email": "[email protected] "
},
"api_key": "key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
"region": "us",
"domain": "example.com"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Ping Email Synthetic email integration that helps you validate deliverability SLAs by periodically sending canary messages.
PUT /integrations/ping_email
DELETE /integrations/ping_email
GET /integrations/ping_emailThe Ping Email object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"url": "https://example.com/webhook"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a Ping Email integration PUT /integrations/ping_email
Updates or creates the Ping Email integration for the project.
Request body URL to ping
format: uri
min length: 1
max length: 100
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/ping_email' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"url":"https://example.com/webhook"}'
{
"url": "https://example.com/webhook"
}
Delete a Ping Email integration DELETE /integrations/ping_email
Deletes the Ping Email integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/ping_email' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Ping Email integrations GET /integrations/ping_email
Retrieves the current Ping Email integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/ping_email' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"url": "https://example.com/webhook"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}SendGrid Configure SendGrid credentials so MagicBell can fan out transactional emails with your templates and domain.
PUT /integrations/sendgrid
DELETE /integrations/sendgrid
GET /integrations/sendgridThe SendGrid object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"api_key": "SG.1234567890",
"from": {
"email": "[email protected] ",
"name": "Company Name"
},
"reply_to": {
"email": "[email protected] ",
"name": "Reply to Company"
}
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a SendGrid integration PUT /integrations/sendgrid
Updates or creates the SendGrid integration for the project.
Request body The email address to send from
The email address to reply to
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/sendgrid' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"api_key":"SG.1234567890","from":{"email":"[email protected] ","name":"Company Name"},"reply_to":{"email":"[email protected] ","name":"Reply to Company"}}'
{
"api_key": "SG.1234567890",
"from": {
"email": "[email protected] ",
"name": "Company Name"
},
"reply_to": {
"email": "[email protected] ",
"name": "Reply to Company"
}
}
Delete a SendGrid integration DELETE /integrations/sendgrid
Deletes the SendGrid integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/sendgrid' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all SendGrid integrations GET /integrations/sendgrid
Retrieves the current SendGrid integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/sendgrid' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"api_key": "SG.1234567890",
"from": {
"email": "[email protected] ",
"name": "Company Name"
},
"reply_to": {
"email": "[email protected] ",
"name": "Reply to Company"
}
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Amazon SES Integrate Amazon SES to reuse verified identities, bounce handling, and CloudWatch metrics.
PUT /integrations/ses
DELETE /integrations/ses
GET /integrations/sesThe Amazon SES object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"key_id": "MY_FAKE_AWS_ACCESS_KEY_ID",
"secret_key": "MY_FAKE_AWS_SECRET_KEY",
"region": "eu-west-1",
"from": {
"name": "Company Name",
"email": "[email protected] "
}
}
}
],
"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 Updates or creates the Amazon SES integration for the project.
Request body The email address to send from
secret_key
string required
AWS Secret Key
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/ses' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"key_id":"MY_FAKE_AWS_ACCESS_KEY_ID","secret_key":"MY_FAKE_AWS_SECRET_KEY","region":"eu-west-1","from":{"name":"Company Name","email":"[email protected] "}}'
{
"key_id": "MY_FAKE_AWS_ACCESS_KEY_ID",
"secret_key": "MY_FAKE_AWS_SECRET_KEY",
"region": "eu-west-1",
"from": {
"name": "Company Name",
"email": "[email protected] "
}
}
Delete an Amazon SES integration Deletes the Amazon SES integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/ses' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Amazon SES integrations Retrieves the current Amazon SES integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/ses' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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": "[email protected] "
}
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Slack Configure Slack so broadcasts can post rich updates into channels or DMs. The flow covers OAuth installation, workspace selection, and webhook delivery setup.
PUT /integrations/slack/installations
POST /integrations/slack/installations/start
POST /integrations/slack/installations/finish
PUT /integrations/slack
DELETE /integrations/slack
GET /integrations/slackThe Slack object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"app_id": "12345678901",
"client_id": "1.0",
"client_secret": "12345678901234567890123456789012",
"signing_secret": "12345678901234567890123456789012"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a Slack installation PUT /integrations/slack/installations
Creates a new installation of a Slack integration for a user. This endpoint is used when an integration needs to be set up with user-specific credentials or configuration.
Request body access_token
string required
Bot token returned from the Slack OAuth exchange.
Slack app identifier for the installed app.
authed_user
object required
Token type value provided by Slack.
Seconds until the user token expires.
Space-delimited OAuth scopes granted to the user token.
User token returned from the OAuth exchange.
Refresh token for the authed user.
Slack user ID for the installer.
Slack user ID of the installed bot.
Enterprise grid identifier.
Seconds until the bot access token expires.
Unique identifier MagicBell assigns to the Slack installation.
configuration_url
string required
URL users can visit to manage the webhook.
Webhook URL that Slack posts events to.
Human readable name for the webhook channel.
is_enterprise_install
boolean
Indicates whether the installation occurred on an enterprise grid.
Refresh token for regenerating the bot access token.
Space-delimited OAuth scopes granted to the bot token.
Workspace name where the app was installed.
Workspace ID where the app was installed.
Type of bot token returned by Slack.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/slack/installations' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"id":"A12345678-T123","access_token":"xoxb-123456789012-1234567890123-12345678901234567890abcdef123456","scope":"identify,commands,bot","team_name":"Team Installing Your App","team_id":"T12345678","enterprise_id":"E12345678","enterprise_name":"Enterprise Grid, Inc.","bot_user_id":"U12345678","app_id":"A12345678","authed_user":{"id":"U12345678","scope":"identify,commands"},"incoming_webhook":{"channel":"C12345678","channel_id":"C12345678","configuration_url":"https://teamname.slack.com/services/B12345678","url":"https://hooks.slack.com/services/T12345678/B12345678/123456789012345678901234"},"team":{"name":"Team Installing Your App","id":"T123"}}'
{
"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
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 Slack app ID that the installation flow should use.
Optional override for the authorization URL returned to the client.
Additional OAuth scopes to request during installation.
Custom redirect URL to use after OAuth completes.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/integrations/slack/installations/start' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"app_id":"12345678901","auth_url":"https://example.com/auth","redirect_url":"https://example.com/redirect","extra_scopes":["scope1","scope2"]}'
{
"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
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 The app ID of the Slack app that was originally configured at the project-level.
The code that was returned from the OAuth flow, and found in the query string of the redirect URL.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/integrations/slack/installations/finish' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"app_id":"12345678901","code":"string","redirect_url":"string"}'
{
"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 Updates or creates the Slack integration for the project.
Request body The Slack app ID that can be found in the app's settings page of the Slack API dashboard.
The Slack client ID that can be found in the app's settings page of the Slack API dashboard.
pattern: ^[0-9]+\.[0-9]+$
client_secret
string required
The Slack client secret that can be found in the app's settings page of the Slack API dashboard.
min length: 32
max length: 32
signing_secret
string required
The Slack signing secret that can be found in the app's settings page of the Slack API dashboard.
min length: 32
max length: 32
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/slack' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"app_id":"12345678901","client_id":"1.0","client_secret":"12345678901234567890123456789012","signing_secret":"12345678901234567890123456789012"}'
{
"app_id": "12345678901",
"client_id": "1.0",
"client_secret": "12345678901234567890123456789012",
"signing_secret": "12345678901234567890123456789012"
}
Delete a Slack integration DELETE /integrations/slack
Deletes the Slack integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/slack' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Slack integrations Retrieves the current Slack integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/slack' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"app_id": "12345678901",
"client_id": "1.0",
"client_secret": "12345678901234567890123456789012",
"signing_secret": "12345678901234567890123456789012"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}SMTP Bring any SMTP server for outbound email, ideal for on-prem or region-specific compliance.
PUT /integrations/smtp
DELETE /integrations/smtp
GET /integrations/smtpThe SMTP object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"host": "smtp.gmail.com",
"port": 587,
"username": "[email protected] ",
"password": "your-app-password",
"from": {
"email": "[email protected] ",
"name": "Example Notifications"
},
"reply_to": {
"email": "[email protected] ",
"name": "Example Support"
},
"security": "starttls"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a SMTP integration Updates or creates the SMTP integration for the project.
Request body Default sender email address
SMTP authentication password
SMTP security/encryption method
SMTP authentication username
Request
curl magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/smtp' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"host":"smtp.gmail.com","port":587,"username":"[email protected] ","password":"your-app-password","from":{"email":"[email protected] ","name":"Example Notifications"},"reply_to":{"email":"[email protected] ","name":"Example Support"},"security":"starttls"}'
{
"host": "smtp.gmail.com",
"port": 587,
"username": "[email protected] ",
"password": "your-app-password",
"from": {
"email": "[email protected] ",
"name": "Example Notifications"
},
"reply_to": {
"email": "[email protected] ",
"name": "Example Support"
},
"security": "starttls"
}
Delete a SMTP integration Deletes the SMTP integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/smtp' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all SMTP integrations Retrieves the current SMTP integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/smtp' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"host": "smtp.gmail.com",
"port": 587,
"username": "[email protected] ",
"password": "your-app-password",
"from": {
"email": "[email protected] ",
"name": "Example Notifications"
},
"reply_to": {
"email": "[email protected] ",
"name": "Example Support"
},
"security": "starttls"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Twilio Wire Twilio to deliver SMS, WhatsApp, or voice notifications as part of your delivery planner.
PUT /integrations/twilio
DELETE /integrations/twilio
GET /integrations/twilioThe Twilio object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"account_sid": "ACXXXXXXXX",
"api_key": "SKXXXXXXXX",
"api_secret": "your_api_secret",
"from": "+15017122661"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a Twilio integration 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
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
The phone number to send from, in E.164 format
min length: 1
max length: 100
pattern: ^\+[0-9]{1,14}$
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/twilio' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"account_sid":"ACXXXXXXXX","api_key":"SKXXXXXXXX","api_secret":"your_api_secret","from":"+15017122661"}'
{
"account_sid": "ACXXXXXXXX",
"api_key": "SKXXXXXXXX",
"api_secret": "your_api_secret",
"from": "+15017122661"
}
Delete a Twilio integration DELETE /integrations/twilio
Deletes the Twilio integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/twilio' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Twilio integrations Retrieves the current Twilio integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/twilio' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"account_sid": "ACXXXXXXXX",
"api_key": "SKXXXXXXXX",
"api_secret": "your_api_secret",
"from": "+15017122661"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Web Push Connect browser push providers so you can reach users on the open web. Handles VAPID keys, service-worker registration, and token lifecycles.
PUT /integrations/web_push/installations
POST /integrations/web_push/installations/start
PUT /integrations/web_push
DELETE /integrations/web_push
GET /integrations/web_pushThe Web Push object {
"data": [
{
"name": "<provider-name>",
"id": "123",
"config": {
"public_key": "BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw",
"private_key": "y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"
}
}
],
"links": {
"first": "https://api.magicbell.com/v1/example",
"next": "https://api.magicbell.com/v1/example?page_next=abc",
"prev": null
}
}Save a Web Push installation PUT /integrations/web_push/installations
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 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.
The encryption keys from the PushSubscription.getKey() method, needed to encrypt push messages for this subscription.
The P-256 ECDH public key obtained from PushSubscription.getKey('p256dh'). Used to encrypt push messages for this subscription.
The authentication secret obtained from PushSubscription.getKey('auth'). Used to encrypt push messages for this subscription.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/web_push/installations' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"endpoint":"https://fcm.googleapis.com/fcm/send/fZhR0fsr0zw:APA91bE4pM-qo1KBJDU_Zp2N9nDP-Jdmwugm-v4KNL_NlJvYCrJeJUzPXmMyAXqAE0m6BFOrkSWT0ArGbUjEEpxQEYZLado8JeW1PZA5CHB8R6C7HT6-MD6Qs8ZaCn8_ffLGGU7WuvtN","keys":{"p256dh":"BICAe4KtLhhPNFvynlqMRxjvpRnr94881QeuTCr8kCwJf-Fssj3FLIlnfFMjj7T1yNg5l6cn14350323_NSGZh0","auth":"GoIO2ulhtQuyBM64lZuFuw"}}'
{
"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
Initiates the installation flow for a Web Push integration. This is the first step in a multi-step installation process where user authorization or external service configuration may be required.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/integrations/web_push/installations/start' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"public_key": "BHaJd...gRHDk",
"auth_token": "eyGhb...GA2Bw"
}
Save a Web Push integration PUT /integrations/web_push
Updates or creates the Web Push integration for the project.
Request body private_key
string required
VAPID private key.
min length: 8
max length: 128
public_key
string required
VAPID public key - read more at https://magicbell.com/tools/vapid-keys.
min length: 8
max length: 128
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/integrations/web_push' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"public_key":"BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw","private_key":"y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"}'
{
"public_key": "BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw",
"private_key": "y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"
}
Delete a Web Push integration DELETE /integrations/web_push
Deletes the Web Push integration configuration from the project. This will disable the integration's functionality within the project.
Query parameters the unique identifier of the integration to be deleted
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/integrations/web_push' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all Web Push integrations GET /integrations/web_push
Retrieves the current Web Push integration configurations for a specific integration type in the project. Returns configuration details and status information.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/integrations/web_push' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"name": "<provider-name>",
"id": "123",
"config": {
"public_key": "BNKZeSrRX_c3QfqzOvv1oshpj1qPbDcUJHKET6Ahs2u9-F4HgllPYxtgaGvGSqfytuALumX5NYZPLD8YmCwBxcw",
"private_key": "y56TIPdEzrQ0Ku_uQbGGkB84mYdF9pJl5IHvmAZ_fVs"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Notifications Notifications are the per-recipient records created from broadcasts. These endpoints let a user list, fetch, and manage the notifications that drive their inbox experience.
Related guides:
Notification Primitive POST /notifications/archive
POST /notifications/read
POST /notifications/seen
GET /notifications/{notification_id}
POST /notifications/{notification_id}/archive
POST /notifications/{notification_id}/unarchive
POST /notifications/{notification_id}/read
POST /notifications/{notification_id}/seen
POST /notifications/{notification_id}/unread
GET /notifications
GET /notifications/unread/countThe Notifications object Attributes action_url
nullable string
The link associated with the notification.
archived_at
nullable string
The timestamp when the notification was archived.
The category grouping for the notification.
The body content of the notification.
created_at
string required
The timestamp when the notification was created.
custom_attributes
nullable object
The custom data stored with the notification.
discarded_at
nullable string
The timestamp when the notification was discarded.
The unique identifier for the notification.
The timestamp when the notification was marked as read.
The timestamp when the notification was seen.
The timestamp when the notification was sent.
The current status of the notification.
The title that is displayed to recipients.
The topic for additional classification.
updated_at
string required
The timestamp when the notification was last updated.
The user that should receive the notification.
{
"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": {},
"status": "unseen",
"archived_at": null,
"topic_id": null
}
Archive all notifications POST /notifications/archive
Archive all notifications.
Query parameters filter notifications by their category
filter notifications by their topic
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/archive' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Mark all notifications read Marks all notifications as read.
Query parameters filter notifications by their category
filter notifications by their topic
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/read' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Mark all notifications seen Marks all unseen notifications as seen.
Query parameters filter notifications by their category
filter notifications by their topic
curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/seen' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Fetch a notification GET /notifications/{notification_id}
Gets a notification by ID.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/notifications/{notification_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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": {},
"status": "unseen",
"archived_at": null,
"topic_id": null
}
Archive a notification POST /notifications/{notification_id}/archive
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/{notification_id}/archive' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Unarchive a notification POST /notifications/{notification_id}/unarchive
Unarchives a notification.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/{notification_id}/unarchive' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Mark a notification read POST /notifications/{notification_id}/read
Marks a notification as read.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/{notification_id}/read' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Mark a notification seen POST /notifications/{notification_id}/seen
Marks a notification as seen.
curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/{notification_id}/seen' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Mark a notification unread POST /notifications/{notification_id}/unread
Marks a notification as unread.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/notifications/{notification_id}/unread' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
List all notifications Lists all notifications for a user.
Query parameters filter notifications by their category
ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
filter notifications by their status, one of 'unseen' | 'unread' | 'read' | 'archived'
filter notifications by their topic
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/notifications' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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": {},
"status": "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
}
}Count unread notifications GET /notifications/unread/count
Returns the count of unread notifications for a user. Supports filtering by category and topic.
Query parameters filter notifications by their category
filter notifications by their topic
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/notifications/unread/count' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Users Users are the recipients of every notification. These endpoints let you list users, upsert profiles, and remove users while keeping identifiers aligned with your product database.
Related guides:
User Primitive PUT /users
DELETE /users/{user_id}
GET /users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
DELETE /users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
GET /users/{user_id}/channels/mobile_push/apns/tokens
GET /users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
DELETE /users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
GET /users/{user_id}/channels/mobile_push/expo/tokens
GET /users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
DELETE /users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
GET /users/{user_id}/channels/mobile_push/fcm/tokens
GET /users/{user_id}/channels/in_app/inbox/tokens/{token_id}
DELETE /users/{user_id}/channels/in_app/inbox/tokens/{token_id}
GET /users/{user_id}/channels/in_app/inbox/tokens
GET /users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
DELETE /users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
GET /users/{user_id}/channels/slack/magicbell_slackbot/tokens
GET /users/{user_id}/channels/slack/tokens/{token_id}
DELETE /users/{user_id}/channels/slack/tokens/{token_id}
GET /users/{user_id}/channels/slack/tokens
GET /users/{user_id}/channels/teams/tokens/{token_id}
DELETE /users/{user_id}/channels/teams/tokens/{token_id}
GET /users/{user_id}/channels/teams/tokens
GET /users/{user_id}/channels/web_push/tokens/{token_id}
DELETE /users/{user_id}/channels/web_push/tokens/{token_id}
GET /users/{user_id}/channels/web_push/tokens
GET /usersThe Users object Attributes The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.
pattern: ^[a-zA-Z0-9]+(.[a-zA-Z0-9]+)*$
created_at
string required
The timestamp when the token was created.
device_token
string required
The APNs device token to register with MagicBell.
discarded_at
nullable string
The timestamp when the token was discarded, if applicable.
The unique identifier for the token.
The APNs environment this token belongs to. If omitted we assume it targets production.
updated_at
nullable string
The timestamp when the token metadata last changed.
{
"created_at": "2021-01-01T00:00:00Z",
"device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"installation_id": "development",
"updated_at": "2021-01-01T00:00:00Z"
}Save a user Creates or updates a user with the provided details. The user will be associated with the project specified in the request context.
Request body created_at
nullable string
The timestamp when the user was created.
custom_attributes
nullable object
Arbitrary custom values stored on the user.
The primary email address of the user.
external_id
nullable string
The user identifier from an external system.
first_name
nullable string
The first name of the user.
The unique identifier for the user.
The last name of the user.
last_notified_at
nullable string
The timestamp when the user last received a notification.
last_seen_at
nullable string
The timestamp when the user last opened the inbox.
updated_at
nullable string
The timestamp when the user was last updated.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/users' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"id":"8a038704-acc1-47f9-81b0-7523886cbeae","external_id":"external-id","email":"[email protected] ","first_name":"Dan","last_name":"Example","custom_attributes":{"key":"value"}}'
{
"id": "8a038704-acc1-47f9-81b0-7523886cbeae",
"external_id": "external-id",
"email": "[email protected] ",
"first_name": "Dan",
"last_name": "Example",
"custom_attributes": {
"key": "value"
}
}
Delete a user Removes a user and all associated data from the project.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
Fetch a user's APNs token GET /users/{user_id}/channels/mobile_push/apns/tokens/{token_id}
Fetches a specific APNs token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/apns/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's APNs token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/apns/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's APNs tokens GET /users/{user_id}/channels/mobile_push/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/apns/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"installation_id": "development",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's Expo token GET /users/{user_id}/channels/mobile_push/expo/tokens/{token_id}
Fetches a specific Expo token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/expo/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's Expo token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/expo/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's Expo tokens GET /users/{user_id}/channels/mobile_push/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/expo/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"device_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's FCM token GET /users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}
Fetches a specific FCM token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's FCM token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/fcm/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's FCM tokens GET /users/{user_id}/channels/mobile_push/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/mobile_push/fcm/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"device_token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"installation_id": "development",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's Inbox token GET /users/{user_id}/channels/in_app/inbox/tokens/{token_id}
Fetches a specific Inbox token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/in_app/inbox/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's Inbox token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/in_app/inbox/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's Inbox tokens GET /users/{user_id}/channels/in_app/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/in_app/inbox/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"token": "eH0fLhuiRj2Np7UQ-opXAm:APA91bGtC-wH4sgW1jWkMKIZf7FYkm_RTQb7Jid7DfSJnCgivGYoRzhLrGxpcIF6yPjmbzAr6CKF-6phZkBasFUUfZmfdgcqfA_ZlZdVk6pSnon3LGzMumCzEJE0zgWoo_RUmVUVJUAt",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's MagicBell SlackBot token GET /users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
Fetches a specific MagicBell SlackBot token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}Delete an user's MagicBell SlackBot token DELETE /users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}
Deletes a specific user's MagicBell SlackBot token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/magicbell_slackbot/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's MagicBell SlackBot tokens GET /users/{user_id}/channels/slack/magicbell_slackbot/tokens
Lists all MagicBell SlackBot tokens associated with a specific user. This endpoint is available to project administrators and returns a paginated list of tokens, including both active and revoked tokens.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/magicbell_slackbot/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's Slack token GET /users/{user_id}/channels/slack/tokens/{token_id}
Fetches a specific Slack token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's Slack token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's Slack tokens GET /users/{user_id}/channels/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/slack/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z",
"webhook": {
"url": "https://example.com/webhook"
}
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's Teams token GET /users/{user_id}/channels/teams/tokens/{token_id}
Fetches a specific Teams token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/teams/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's Teams token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/teams/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's Teams tokens GET /users/{user_id}/channels/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/teams/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"created_at": "2021-01-01T00:00:00Z",
"discarded_at": "2021-01-01T00:00:00Z",
"id": "123",
"updated_at": "2021-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Fetch a user's Web Push token GET /users/{user_id}/channels/web_push/tokens/{token_id}
Fetches a specific Web Push token by its ID for a given user. This endpoint is available to project administrators and requires project-level authentication. Use this to inspect token details including its status, creation date, and associated metadata.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/web_push/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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}
Deletes a specific user's Web Push token. This endpoint is available to project administrators and permanently invalidates the specified token. Once revoked, the token can no longer be used to access channel features. This action cannot be undone.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request DELETE \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/web_push/tokens/{token_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "123",
"discarded_at": "2021-01-01T00:00:00Z"
}List an user's Web Push tokens GET /users/{user_id}/channels/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.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users/{user_id}/channels/web_push/tokens' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"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 Lists all users in the project.
Query parameters ending_before
nullable string
a cursor for use in pagination, points to the first ID in next page
defines the maximum number of items to return per page (default: 50)
filter users by their email address or external ID
starting_after
nullable string
a cursor for use in pagination, points to the last ID in previous page
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/users' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"id": "8a038704-acc1-47f9-81b0-7523886cbeae",
"external_id": "external-id",
"email": "[email protected] ",
"first_name": "Dan",
"last_name": "Example",
"custom_attributes": {
"key": "value"
}
}
],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}Workflows Workflows let you orchestrate multi-step reactions to events, fan out to broadcasts, enrich data, or call external services. These routes manage definitions and runs so you can iterate on automation safely.
PUT /workflows
GET /workflows/*
POST /workflows/runs
GET /workflows/runs/{run_id}
GET /workflows/{workflow_key}/runs
GET /workflowsThe Workflows object Attributes When true, prevents the workflow from being triggered.
Unique identifier for this workflow definition.
min length: 3
pattern: ^[A-Za-z0-9\_\.\-\:]+$
Ordered list describing each action that will run inside the workflow.
Command to execute (e.g., broadcast, pause, wait, abort)
JMESPath condition that must evaluate truthy for the step to run.
Optional payload passed to the command when it executes.
{
"steps": [
{
"command": "broadcast",
"input": {
"channel": "in_app"
}
},
{
"command": "broadcast",
"if": "{{data.paying}} == true",
"input": {
"channel": "email"
}
}
],
"key": "project"
}
Save workflow definition Creates or updates a workflow definition for the project
Request body When true, prevents the workflow from being triggered.
Unique identifier for this workflow definition.
min length: 3
pattern: ^[A-Za-z0-9\_\.\-\:]+$
Ordered list describing each action that will run inside the workflow.
Optional payload passed to the command when it executes.
Command to execute (e.g., broadcast, pause, wait, abort)
JMESPath condition that must evaluate truthy for the step to run.
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request PUT \
--url 'https://api.magicbell.com/v2/workflows' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"steps":[{"command":"broadcast","input":{"channel":"in_app"}},{"command":"broadcast","if":"{{data.paying}} == true","input":{"channel":"email"}}],"key":"project"}'
{
"steps": [
{
"command": "broadcast",
"input": {
"channel": "in_app"
}
},
{
"command": "broadcast",
"if": "{{data.paying}} == true",
"input": {
"channel": "email"
}
}
],
"key": "project"
}
Fetch workflow definition Retrieves a workflow definition by key
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/workflows/*' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"steps": [
{
"command": "broadcast",
"input": {
"channel": "in_app"
}
},
{
"command": "broadcast",
"if": "{{data.paying}} == true",
"input": {
"channel": "email"
}
}
],
"key": "project"
}
Execute workflow Executes a workflow with the provided input parameters
Request body Optional JSON payload that will be passed as the workflow input context.
The unique workflow key to execute (e.g. integration.stripe.charge.succeeded).
pattern: ^[A-Za-z0-9\_\.\-\:]+$
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request POST \
--url 'https://api.magicbell.com/v2/workflows/runs' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN" \
--data '{"key":"magicbell:signup","input":{"user":{"id":"123","name":"John Doe"}}}'
{
"id": "123e4567-e89b-12d3-a456-426614174000"
}
Get workflow run status GET /workflows/runs/{run_id}
Retrieves the status and details of a workflow run
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/workflows/runs/{run_id}' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"workflow_key": "integration.stripe.charge.succeeded",
"status": {
"state": 2,
"next_step": 1,
"started_at": "2024-01-01T00:00:00Z"
},
"created_at": "2024-01-01T00:00:00Z",
"input": {
"description": "",
"payload": {
"action": "in_progress"
},
"type": "workflow_job"
}
}List workflow runs GET /workflows/{workflow_key}/runs
Retrieves all runs for a specific workflow
Request
curl magicbell-cli magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/workflows/{workflow_key}/runs' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"data":[{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"workflow_key": "integration.stripe.charge.succeeded",
"status": {
"state": 2,
"next_step": 1,
"started_at": "2024-01-01T00:00:00Z"
},
"created_at": "2024-01-01T00:00:00Z"
}],
"links": {
"first":"https://api.magicbell.com/v1/example",
"next":"https://api.magicbell.com/v1/example?page_next=abc",
"prev":null
}
}List workflow definitions Retrieves all workflow definitions for the project
Request
curl magicbell-go magicbell-js Copy curl --request GET \
--url 'https://api.magicbell.com/v2/workflows' \
--header 'content-type: application/json' \
--header "authorization: Bearer $TOKEN"
{
"items": [
{
"key": "integration.stripe.charge.succeeded",
"disabled": false,
"steps": [
{
"command": "broadcast",
"if": "event.amount > 1000",
"input": {
"category": "billing",
"template": "payment_received"
}
}
]
}
]
}