REST API (v2)
The current version of the MagicBell REST API is v2.
Base URL
https://api.magicbell.com/v2
Endpoints Reference
You can find the complete list of endpoints in the API (v2) Reference. We also offer several SDKs to help you integrate with the API.
If you haven't migrated yet, the API v1 (deprecated) reference is here.
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:
{
"errors": [
{
"code": "invalid_jwt_format",
"message": "expected authorization header format: Bearer <token>"
}
]
}
Rate Limit
The REST API imposes a limit of 500 req/minute counted per IP address.
On hitting the rate limit, the API returns HTTP 429 Too Many Requests response. The block is removed after 60 seconds.
Please note that several API endpoints support batching or bulk actions, which can reduce the number of requests you make. For example, POST /v2/broadcasts supports multiple recipients in a single request.
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: 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 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.
magicbell broadcasts create \
--data '{
"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": "[email protected]" },
{ "email": "[email protected]" }
]
}'
OpenAPI Description
The API is described in the OpenAPI 3.1 format.