The Basics
Version | v0 |
Endpoint | https://api.magicbell.com |
Accept | application/json |
Content-Type | application/json |
API Spec
The MagicBell REST API is described in an OpenAPI 3.0 document, and there are a few ways to use it.
Client errors
The MagicBell REST API utilizes HTTP response codes
to indicate the success or failure of an API request. A 2xx
response code
indicates success, and a 4xx
response code means that the API request is
incorrect (like when a required parameter is missing or a resource, like a user,
could not be found). A 5xx
response code indicates an error in MagicBell's
servers. These are rare, and we always act quickly to solve them.
When the API responds with a 4xx
response code, the response body includes an
array that contains all the errors that have happened. For example:
json{
"errors": [
{
"code": "api_secret_not_provided",
"message": "API Secret not provided"
}
]
}
As shown above, some errors also have a code
that briefly describes the error
that has happened. These are the possible error codes:
api_key_not_provided
incorrect_api_key
api_secret_not_provided
api_secret_is_incorrect
forbidden
neither_user_hmac_nor_api_secret_provided
user_email_not_provided
You can handle these errors and take necessary action, like displaying an appropriate error message to the users or reporting the event to your error tracker. For example:
Nodeconst axios = require('axios');
const headers = {
'X-MAGICBELL-API-SECRET': 'MAGICBELL_API_SECRET',
'X-MAGICBELL-API-KEY': 'MAGICBELL_API_KEY',
};
const data = {
broadcast: {
title: "We're processing your order",
},
};
axios.post('https://api.magicbell.com/broadcasts', data, headers).catch((error) => {
const { response } = error;
ErrorTracker.notify(response.data, response.status);
});
Rate limiting
The REST API imposes a limit of 100 requests/minute for most GET/OPTIONS/HEAD
endpoints
and 60 requests/minute for POST/PATCH/PUT/DELETE
endpoints.
You will get an HTTP 429 Too Many Requests response if you send requests fasters than that, often accompanied by a helpful error message explaining the limit you have hit. Unless you are on an Enterprise plan, these limits are subject to change without announcement.
Please note that many of our endpoints support batching or bulk actions, which can reduce the number of requests you make.
For example, POST /notifications
supports multiple recipients in a single request.
Many of our API endpoints support bulk operations, and we recommend using them to reduce the number of requests you make.
Idempotent requests
The API supports idempotent requests to prevent the same operation from being performed twice for some endpoints. If you attempt an operation twice or more, we will process only the first attempt. For example, suppose a request to create a notification does not respond due to a network connection error. In that case, you can retry the request with the same idempotency key and it will create no additional notification.
To perform an idempotent request, you need to add an Idempotency-Key: <key>
header on the request.
An idempotency key is a unique value generated on your side, which the server uses to recognize subsequent retries of the same request.
We suggest using V4 UUID to avoid collisions.
The resulting status code and body of the first request will be cached. Subsequent requests with the same idempotency key will return the same result. The cached results will expire after 24 hours.
curl https://api.magicbell.com/broadcasts \
--request POST \
--header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
--header 'X-MAGICBELL-API-SECRET: MAGICBELL_API_SECRET' \
--header 'IDEMPOTENCY-KEY: YOUR_IDEMPOTENCY_KEY' \
--data '{
"broadcast": {
"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" }
]
}
}'