Sending Notifications

Learn how to send notifications using our API

MagicBell allows you to send a notification to one user or many - up to 1000 users in a single request - using the create notification API endpoint. The way you send notifications to a user depends on how you identify users in your app. MagicBell accepts emails and external IDs (strings) as unique identifiers for users.

We encourage you to run examples in your terminal as you read this guide. You can install curl by running:

brew install curl

You can explore all available API endpoints here.

Be sure to replace
MAGICBELL_API_KEY
and
MAGICBELL_API_SECRET
with your actual API key and API secret before running the following examples.

Identify users by their email address

If you identify a user by their email address, you need to set the email addresses you want to notify in the payload you send to our API.

For example, to send a notification to Mary and Richard, whose emails are mary@example.com and richard@example.com, respectively, you can do this:

curl https://api.magicbell.com/notifications \
  --request POST \
  --header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
  --header 'X-MAGICBELL-API-SECRET: MAGICBELL_API_SECRET' \
  --data '{
    "notification": {
        "title": "Task assigned to you: Upgrade to Startup plan",
        "content": "Hello, can you upgrade us to the Startup plan. Thank you.",
        "category": "billing",
        "action_url": "https://magicbell.com/pricing",
        "recipients": [
          { "email": "mary@example.com" },
          { "email": "richard@example.com" }
        ]
    }
  }'

Notice that each recipient has the email key set.

Identify users by an ID

But what if you don't identify users by email in your app? MagicBell allows you to use the same ID you have in your app to send MagicBell notifications.

For example, to send a notification to Mary and Richard, whose IDs are "u001" and "u002", respectively, you can do this:

curl https://api.magicbell.com/notifications \
  --request POST \
  --header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
  --header 'X-MAGICBELL-API-SECRET: MAGICBELL_API_SECRET' \
  --data '{
    "notification": {
        "title": "Task assigned to you: Upgrade to Startup plan",
        "content": "Hello, can you upgrade us to the Startup plan. Thank you.",
        "category": "new_message",
        "action_url": "https://magicbell.com/pricing",
        "recipients": [
          { "external_id": "u001" },
          { "external_id": "u002" },
       ]
    }
  }'

Notice that each recipient has the external_id key set.

If you use an integer to identify users, remember to cast it to a string.