/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

ParameterTypeDescription
_idStringUnique ID
userIdStringYour user id
createdAtDateDate it was created
modifiedAtDateDate it was last modified
nameStringArbitrary name that shows up in the UI. Not used outside of the Mixmax UI.
triggerObjectThe 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.
filterStringJSON serialized string representation of a Sift filter. Details below. Omit for no filter.
isPausedBooleanTrue if the rule is paused (not running on incoming events)
actionsArrayOnly 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.

KeyTypeRequired?Description
eventNameStringyesThe internal name of the event that triggers this rule

type=recurring

This type of rule triggers on a recurring time.

KeyTypeRequired?Description
rruleStringyesThe 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:

OperatorSupport data typesDescriptionExample value
$timeOfDayDate or TimestampMatches 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 }
$dayOfWeekDate or TimestampMatches 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] }
$withinTimeRangeDate or String or TimestampMatches 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

FieldDescriptionExample value
$anyRecipientAlias 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"}
Language
Authorization
Header