/rules (webhooks)

Mixmax rules are a way to intercept events and route them to a webhook or some other place https://app.mixmax.com/dashboard/rules. Also see https://engineering.mixmax.com/blog/introducing-rules for how they can be used.

🚧

We apologize: this API isn't well documented. If you'd like to learn more about the rule format, consider creating a Rule in the Mixmax Rules Dashboard UI and then use this API to retrieve it to understand the format.

Rules intercept a Mixmax event in realtime, evaluate a filter conditions on the event, and performs an action. For example, if you wanted to intercept incoming emails to [email protected] and route them to Slack, you could create the rule:

{
  trigger: { type: "event", eventName: "message:sent" },
  filter:  {"to.email": "[email protected]" },
}

Note that when creating a rule, you should also create a rule action. This specifies what happens after a rule has been triggered (and passes the filter criteria).

Response format

Parameter

Type

Description

_id

String

Unique ID

userId

String

Your user id

createdAt

Date

Date it was created

modifiedAt

Date

Date it was last modified

name

String

Arbitrary name that shows up in the UI. Not used outside of the Mixmax UI.

trigger

Object

The trigger for the rule. An object with required key type that is one of the types in the table listed below. This object may contain other key/value pairs specific to that event.

filter

String

JSON serialized string representation of a Sift filter. Details below. Omit for no filter.

isPaused

Boolean

True if the rule is paused (not running on incoming events)

actions

Array

Only present if you pass expand=actions on the querystring. Contains the rule actions (from GET /rule/:id/actions).

Trigger

A trigger is an object that represents the trigger for the rule. It must have the key type and other key/values that are specified in the tables below.

type=event

This type of rule triggers on a realtime event, such as an email being sent. A comprehensive list of event names is not currently documented.

Key

Type

Required?

Description

eventName

String

yes

The internal name of the event that triggers this rule

type=recurring

This type of rule triggers on a recurring time.

Key

Type

Required?

Description

rrule

String

yes

The rfc2445-compliant RRULE definition to specifies when this rule should be run

Filter (for event-based triggers)

Only applies if using the type=event trigger type.

A filter is a JSON-serialized Sift object. A Sift filter is a domain-specific language (inspired by MongoDB) for a complex expression. The Mixmax rules engine will evaluate your filter against the incoming event. If you omit a filter, then all events will match.

Example

So let's say you have an incoming poll:vote event that looks like this:

{
   name: "Favorite ice cream flavor",
   voteLabel: "vanilla",
   recipientEmail: "[email protected]",
}

and you want to match the first vote. You can create a simple Sift filter:

{
   name: "vanilla"
}

Now let's look at a more complex example. Let's say you want this rule to trigger if either [email protected] votes on vanilla OR [email protected] votes on chocolate. You can use Sifts $or operator like so:

{
   $or: [
      {name: "vanilla", recipientEmail: {$regex: "[email protected]", $options: "i"}},
      {name: "chocolate", recipientEmail: {$regex: "[email protected]", $options: "i"}}
   ]
}

Note that we're matching the email address case-insensitively, since most email servers are case-insensitive.

Restrictions

Since your Sift filter needs to be JSON serializable, you may not use Sift's $where operator. Also, when passing regular expressions you must use the object format (i.e. {$regex: "^prefix", options: "i"} instead of /^prefix/i).

Custom expressions

In addition to the basic expressions implemented by Sift, the Mixmax rules engine also supports the following custom expressions:

Operator

Support data types

Description

Example value

$timeOfDay

Date or Timestamp

Matches a range of times within a day. It's an object with parameters:

  1. timezone: the IANA timezone specifier for the timezone
  2. start: the start hour of the day (00-23)
  3. end: the end hour of the day (00-23), must be after start
{
   timezone: "America/Los_Angeles",   start: 6,
   end: 20
}

$dayOfWeek

Date or Timestamp

Matches one or more days in a week. It's an object with parameters:

  1. timezone: the IANA timezone specifier for the timezone
  2. days: an array of number days to match (0=Sunday, 6=Saturday)
{
   timezone: "America/Los_Angeles",   days: [1,2,3,4,5]
}

$withinTimeRange

Date or String or Timestamp

Matches if the date (or date string) is within the specified time range. Currently supports days and minutes. Negative number means past.

{
   days: -1
}

As a convenience, some event types support custom "fields" that match multiple fields behind the scenes. For example, you can use $anyRecipient as an alias for to, cc, `bcc.

For example, if you wanted to match messages that are sent between 9am and 5pm, you could use:

{
   sent: { 
      $timeOfDay: { timezone: "America/Los_Angeles", start: 4, end: 16 } 
   }
}

Custom fields

Field

Description

Example value

$anyRecipient

Alias for matching to.email or cc.email or bcc.email properties. Only valid for unopened, replied, and message:received event types.

{
$anyRecipient: {$regex: "[email protected].com", $options: "i"}
Language
Authentication
Header
Click Try It! to start a request and see the response here!