GraphQL API Reference

Explore the MagicBell GraphQL API

Authentication

The MagicBell GraphQL API utilizes an HTTP header based authentication using your MagicBell's project's API key and secret. Your MagicBell project's API key and secret are available in the "Settings" section of your MagicBell Admin Dashboard.

While the API key of your project can be distributed freely, do not publish the API secret.

Admin operations

All API requests that perform an admin operation (like fetch all users or create notifications) require:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGIBCELL-API-SECRET header containing your MagicBell project's API secret
curl https://api.magicbell.com/graphql \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]' \
  --data '{ "query": "{ users(first: 2) { totalCount } }" }'

While the API key of your project can be distributed freely, do not publish the API secret.

Other operations

Your users can perform some operations over their notifications (like fetch them). All API requests that perform these operations require:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGICBELL-USER-EXTERNAL-ID header containing the ID of the user performing the request
  • the X-MAGICBELL-USER-HMAC header containing the computed hash for the user
curl https://api.magicbell.com/graphql \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-USER-EXTERNAL-ID: [USER_ID]'
  --header 'X-MAGICBELL-USER-HMAC: [USER_ID_HMAC]'
  --data '{ "query": "{ notifications(first: 2) { totalCount } }" }'

On the other hand, if you identify users in your app by email, set the X-MAGICBELL-USER-EMAIL header instead:

curl https://api.magicbell.com/graphql \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-USER-EMAIL: [USER_EMAIL]'
  --header 'X-MAGICBELL-USER-HMAC: [USER_EMAIL_HMAC]'
  --data '{ "query": "{ notifications(first: 2) { totalCount } }" }'

If you set both the email and the external ID in the HTTP headers when performing a request the external ID will take precedence over the email.

If you're yet to turn to HMAC authentication for your MagicBell project, you don't have to provide the X-MAGICBELL-USER-HMAC header. However, we highly recommend turning on HMAC authentication before releasing MagicBell to your users.

Fetch notifications

Query

List of notifications that belong to a user. Notifications are sorted in descendent order by the sentAt timestamp.

The user is identified by the HTTP authentication headers.

HTTP headers

  • X-MAGICBELL-API-KEYrequired

    API key of your MagicBell project.

    String

  • X-MAGICBELL-USER-EXTERNAL-ID

    ID of the user. Provide the X-MAGICBELL-USER-EMAIL header instead if you identify users by email.

    String

  • X-MAGICBELL-USER-EMAIL

    Email address of the user. Provide the X-MAGICBELL-USER-EXTERNAL-ID header instead if you identify users by ID.

    String

  • X-MAGICBELL-USER-HMAC

    HMAC calculated with the API secret and ID, or email, of the user. Required if the project has HMAC enabled.

    String

GraphQL Arguments

  • after

    Returns the elements that come after the specified cursor.

    String

  • before

    Returns the elements that come before the specified cursor.

    String

  • first

    Returns the first n elements. Defaults to 50. The maximum accepted value is 50.

    Int

  • last

    Returns the last n elements.

    Int

  • read

    Filters based on the read state. If false, only unread notifications will be returned. Defaults to null.

    Boolean

  • seen

    Filters based on the seen state. If false, only unseen notifications will be returned. Defaults to null.

    Boolean

  • archived

    Filters based on the archived state. If false, only unarchived notifications will be returned. Defaults to null.

    Boolean

    • Fetch users

    Query

    List of users that belong to your project.

    The project is determined by the HTTP authentication headers.

    HTTP headers

    • X-MAGICBELL-API-KEYrequired

      API key of your MagicBell project.

      String

    • X-MAGICBELL-API-SECRETrequired

      API secret of your MagicBell project.

      String

    GraphQL Arguments

  • after

    Returns the elements that come after the specified cursor.

    String

  • before

    Returns the elements that come before the specified cursor.

    String

  • first

    Returns the first n elements. Defaults to 50.

    Int

  • last

    Returns the last n elements.

    Int

  • matches

    Filters based on the stored attributes of users. The string is expected to be an SQL-like expression.

    String

    • Fetch categories

    Query

    List of categories that belong to your project.

    The project is determined by the HTTP authentication headers.

    HTTP headers

    • X-MAGICBELL-API-KEYrequired

      API key of your MagicBell project.

      String

    • X-MAGICBELL-API-SECRETrequired

      API secret of your MagicBell project.

      String

    GraphQL Arguments

  • after

    Returns the elements that come after the specified cursor.

    String

  • before

    Returns the elements that come before the specified cursor.

    String

  • first

    Returns the first n elements. Defaults to 50.

    Int

  • last

    Returns the last n elements.

    Int

    • Fetch logs

    Query

    List of logged activity related to notifications you created with the MagicBell API, either using the REST API or the GraphQL API.

    The project is determined by the HTTP authentication headers.

    HTTP headers

    • X-MAGICBELL-API-KEYrequired

      API key of your MagicBell project.

      String

    • X-MAGICBELL-API-SECRETrequired

      API secret of your MagicBell project.

      String

    GraphQL Arguments

  • after

    Returns the elements that come after the specified cursor.

    String

  • before

    Returns the elements that come before the specified cursor

    String

  • first

    Returns the first n elements. Defaults to 50. The maximum accepted value is 50.

    Int

  • last

    Returns the last n elements.

    Int

  • user

    filters based on the attributes of the recipient of a notification.

    UserFilter

  • notification

    Filters based on the notification attributes.

    NotificationFilter

  • channels

    Filters based on the channel a notification belongs to.

    [String!]