Segments

Often notifications need to be sent to a specified group of users. Groups can be static, but more commonly, they are dynamic (e.g., when a user switches payment tiers). Select Segments as recipients when using Compose to send notifications to your users.

How to create segments from the Dashboard

Click the Users icon from the left navigation sidebar and select Create Segment. Use the query builder to compose a new segment. Segments consist of a Field, a Condition, and Criteria. Matches will display below the query builder as you build the segment.

Compose complex segments by creating additional filters — click Add and choose the And or Or operator.

Remember to label and save your segment! Segment labels do not have to be unique.

Fields

The following fields are supported:

• email
• first_name
• last_name
• external_id
• custom_attributes

The following are examples of valid custom attributes:

• company
• company.department (nested properties)
• company.department.role (deeply nested properties)

Conditions

The following conditions are supported:

• contains
• equals
• starts with
• ends with

Criteria

• Criteria accepts strings and integers under 200 characters, and boolean values.
• * is a wild card. It represents any character. For example, s*nk matches "sink", "sank", and "sunk".

How to create segments using the API

MagicBell allows you to create a notification specifying users by either their email address or their ID. Learn more.

However, you can also specify a group of users to notify. To that end, you can provide an SQL-like string to the notification.recipients.matches parameter.

{
  "notification": {
    "title": "We are processing your order",
    "recipients": [
      {
        "matches": "*"
      }
    ]
  }
}

Format

The matches string accepts a wildcard char: *, and these logic operators: =, AND and OR.

With these you form strings that MagicBell can use to search for existing users either by their email address, external ID or a custom attribute.

These are examples of valid strings that you can pass to the create notifications API endpoint:

• Notify all users

  "*"
  

• Notify the user whose email is "[email protected]"

  "email = [email protected]"
  

• Notify all users whose email starts with "dan"

  "email = [email protected]*"
  

• Notify all users whose email's domain is "example.com"

  "email = *@example.com"
  

• Notify all users whose external ID ends with "001"

  "external_id = *001"
  

• Notify all users that belong to the "Example" company

  "custom_attributes.company.name = Example"
  

• Notify all users that belong to the "Example" company or their external ID starts with "AB"

  "custom_attributes.company.name = Example OR external_id = AB*"
  

Setting custom attributes

We encourage you to set custom attributes on your MagicBell users to take full advantage of this feature. You can do it using our users API endpoints.