🚧
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 sales@yourcompany.com and route them to Slack, you could create the rule:

{
  trigger: { type: "event", eventName: "message:sent" },
  filter:  {"to.email": "sales@yourcompany.com" },
}

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: "bob@mixmax.com",
}

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 bob@mixmax.com votes on vanilla OR charlie@mixmax.com votes on chocolate. You can use Sifts $or operator like so:

{
   $or: [
      {name: "vanilla", recipientEmail: {$regex: "bob@mixmax.com", $options: "i"}},
      {name: "chocolate", recipientEmail: {$regex: "charlie@mixmax.com", $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:

timezone: the IANA timezone specifier for the timezone
start: the start hour of the day (00-23)
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:

timezone: the IANA timezone specifier for the timezone
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: "hello@mixmax.com", $options: "i"}`