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]", $options: "i"} |