{"_id":"5840b34bc6c9322300273ff9","__v":4,"category":{"_id":"57f53fb368a53b2000e03f0f","version":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-10-05T18:00:19.547Z","from_sync":false,"order":0,"slug":"api","title":"REST API"},"parentDoc":null,"project":"5588b8a2f6c18d0d005bba03","version":{"_id":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","__v":15,"createdAt":"2015-06-23T01:38:42.696Z","releaseDate":"2015-06-23T01:38:42.696Z","categories":["5588b8a3f6c18d0d005bba07","5588e9689cfea70d00371df3","5588f5921163180d00b64704","561598b121e9110d0078025a","5616f1c9d170d00d00189306","5616f5c3a410c90d00c6121e","561803dcf8c9632100ac7592","563667280441020d0000e9eb","5642570d9417b40d00c0fcd3","57bf5f02efe0050e00d50bd5","57f53fb368a53b2000e03f0f","57f55187440418170086325a","582e3afa72fd270f0006926d","5841faa973967b0f004b4a2b","58db348aa32c8419002433bb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"5588b847f6c18d0d005bba01","updates":["592f9f10ee04b6000f6a126a","594d6de7387538002da1761c"],"next":{"pages":[],"description":""},"createdAt":"2016-12-01T23:33:31.475Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[{"code":"curl --header \"X-API-Token: <your token>\" https://api.mixmax.com/v1/rules","language":"curl"}]},"method":"get","results":{"codes":[]},"auth":"required","params":[],"url":"/v1/rules"},"isReference":true,"order":71,"body":"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:::at:::yourcompany.com* and route them to Slack, you could create the rule:\n\n```\n{\n  trigger: { type: \"event\", eventName: \"message:sent\" },\n  filter:  {\"to.email\": \"sales@yourcompany.com\" },\n  action: { type: \"sendToSlack\", webhookUrl: \"https://api.slack.com/...\"}\n}\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response format\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"_id\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"*String*\",\n    \"0-2\": \"Unique ID\",\n    \"1-0\": \"userId\",\n    \"1-1\": \"*String*\",\n    \"1-2\": \"Your user id\",\n    \"2-0\": \"createdAt\",\n    \"2-1\": \"*Date*\",\n    \"2-2\": \"Date it was created\",\n    \"3-0\": \"modifiedAt\",\n    \"3-1\": \"*Date*\",\n    \"3-2\": \"Date it was last modified\",\n    \"4-0\": \"name\",\n    \"4-1\": \"*String*\",\n    \"4-2\": \"Arbitrary name that shows up in the UI. Not used outside of the Mixmax UI.\",\n    \"5-0\": \"trigger\",\n    \"5-1\": \"*Object*\",\n    \"5-2\": \"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.\",\n    \"6-0\": \"filter\",\n    \"6-1\": \"*String*\",\n    \"6-2\": \"JSON serialized string representation of a Sift filter. Details below. Omit for no filter.\",\n    \"7-0\": \"action\",\n    \"7-1\": \"*Object*\",\n    \"7-2\": \"An object with required key `type`. This object may contain other key/value pairs specific to that event.\",\n    \"8-0\": \"isPaused\",\n    \"8-1\": \"*Boolean*\",\n    \"8-2\": \"True if the rule is paused (not running on incoming events)\"\n  },\n  \"cols\": 3,\n  \"rows\": 9\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Trigger\"\n}\n[/block]\nA 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.\n\n**type=event**\n\nThis type of rule triggers on a realtime event, such as an email being sent. A comprehensive list of event names is not currently documented.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Required?\",\n    \"0-0\": \"eventName\",\n    \"0-1\": \"String\",\n    \"0-2\": \"yes\",\n    \"h-3\": \"Description\",\n    \"0-3\": \"The internal name of the event that triggers this rule\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n**type=recurring**\n\nThis type of rule triggers on a recurring time.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Required?\",\n    \"0-0\": \"rrule\",\n    \"0-2\": \"yes\",\n    \"0-1\": \"String\",\n    \"h-3\": \"Description\",\n    \"0-3\": \"The rfc2445-compliant RRULE definition to specifies when this rule should be run\"\n  },\n  \"cols\": 4,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Filter (for event-based triggers)\"\n}\n[/block]\nOnly applies if using the type=event trigger type.\n\nA filter is a JSON-serialized [Sift object](https://www.npmjs.com/package/sift). 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.\n\n## Example\n\nSo let's say you have an incoming poll:vote event that looks like this:\n\n```\n{\n   name: \"Favorite ice cream flavor\",\n   voteLabel: \"vanilla\",\n   recipientEmail: \"bob@mixmax.com\",\n}\n```\n\nand you want to match the first vote. You can create a simple Sift filter:\n\n```\n{\n   name: \"vanilla\"\n}\n```\n\nNow 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:\n\n```\n{\n   $or: [\n      {name: \"vanilla\", recipientEmail: {$regex: \"bob@mixmax.com\", $options: \"i\"}},\n      {name: \"chocolate\", recipientEmail: {$regex: \"charlie@mixmax.com\", $options: \"i\"}}\n   ]\n}\n```\n\nNote that we're matching the email address case-insensitively, since most email servers are case-insensitive.\n\n## Restrictions\n\nSince 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`).\n\n## Custom expressions\n\nIn addition to the basic expressions implemented by [Sift](https://www.npmjs.com/package/sift), the Mixmax rules engine also supports the following custom expressions:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Operator\",\n    \"0-0\": \"`$timeOfDay`\",\n    \"h-1\": \"Support data types\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"Matches a range of times within a day. It's an object with parameters:\\n1) timezone: the IANA timezone specifier for the timezone\\n2) start: the start hour of the day (00-23)\\n3) end: the end hour of the day (00-23), must be after start\",\n    \"1-0\": \"`$dayOfWeek`\",\n    \"h-3\": \"Example value\",\n    \"0-1\": \"*Date* or *Timestamp*\",\n    \"1-1\": \"*Date* or *Timestamp*\",\n    \"1-2\": \"Matches one or more days in a week. It's an object with parameters:\\n1) timezone: the IANA timezone specifier for the timezone\\n2) days: an array of number days to match (0=Sunday, 6=Saturday)\",\n    \"0-3\": \"```\\n{\\n   timezone: \\\"America/Los_Angeles\\\",   start: 6,\\n   end: 20\\n}\\n```\",\n    \"1-3\": \"```\\n{\\n   timezone: \\\"America/Los_Angeles\\\",   days: [1,2,3,4,5]\\n}\\n```\",\n    \"2-0\": \"`$withinTimeRange`\",\n    \"2-1\": \"*Date* or *String* or *Timestamp*\",\n    \"2-3\": \"```\\n{\\n   days: -1\\n}\\n```\",\n    \"2-2\": \"Matches if the date (or date string) is within the specified time range. Currently supports `days` and `minutes`. Negative number means past.\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\nAs 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.\n\nFor example, if you wanted to match messages that are sent between 9am and 5pm, you could use:\n\n```\n{\n   sent: { \n      $timeOfDay: { timezone: \"America/Los_Angeles\", start: 4, end: 16 } \n   }\n}\n```\n\n## Custom fields\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Example value\",\n    \"h-3\": \"\",\n    \"0-0\": \"`$anyRecipient`\",\n    \"0-1\": \"Alias for matching `to.email` or `cc.email` or `bcc.email` properties. Only valid for `unopened`, `replied`, and `message:received` event types.\",\n    \"0-2\": \"```\\n{\\n$anyRecipient: {$regex: \\\"hello@mixmax.com\\\", $options: \\\"i\\\"}\\n```\",\n    \"0-3\": \"\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Actions\"\n}\n[/block]\nThe action is the action taken on the event if it passes your filter.","excerpt":"Mixmax rules are a way to intercept events and route them to a webhook or some other place https://app.mixmax.com/dashboard/settings/rules. Also see https://mixmax.com/blog/introducing-rules for how they can be used.","slug":"rules","type":"endpoint","title":"/rules"}

get/rules

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

Definition

{{ api_url }}{{ page_api_url }}

Examples


Documentation

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" }, action: { type: "sendToSlack", webhookUrl: "https://api.slack.com/..."} } ``` [block:api-header] { "type": "basic", "title": "Response format" } [/block] [block:parameters] { "data": { "0-0": "_id", "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-1": "*String*", "0-2": "Unique ID", "1-0": "userId", "1-1": "*String*", "1-2": "Your user id", "2-0": "createdAt", "2-1": "*Date*", "2-2": "Date it was created", "3-0": "modifiedAt", "3-1": "*Date*", "3-2": "Date it was last modified", "4-0": "name", "4-1": "*String*", "4-2": "Arbitrary name that shows up in the UI. Not used outside of the Mixmax UI.", "5-0": "trigger", "5-1": "*Object*", "5-2": "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.", "6-0": "filter", "6-1": "*String*", "6-2": "JSON serialized string representation of a Sift filter. Details below. Omit for no filter.", "7-0": "action", "7-1": "*Object*", "7-2": "An object with required key `type`. This object may contain other key/value pairs specific to that event.", "8-0": "isPaused", "8-1": "*Boolean*", "8-2": "True if the rule is paused (not running on incoming events)" }, "cols": 3, "rows": 9 } [/block] [block:api-header] { "title": "Trigger" } [/block] 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. [block:parameters] { "data": { "h-0": "Key", "h-1": "Type", "h-2": "Required?", "0-0": "eventName", "0-1": "String", "0-2": "yes", "h-3": "Description", "0-3": "The internal name of the event that triggers this rule" }, "cols": 4, "rows": 1 } [/block] **type=recurring** This type of rule triggers on a recurring time. [block:parameters] { "data": { "h-0": "Key", "h-1": "Type", "h-2": "Required?", "0-0": "rrule", "0-2": "yes", "0-1": "String", "h-3": "Description", "0-3": "The rfc2445-compliant RRULE definition to specifies when this rule should be run" }, "cols": 4, "rows": 1 } [/block] [block:api-header] { "type": "basic", "title": "Filter (for event-based triggers)" } [/block] Only applies if using the type=event trigger type. A filter is a JSON-serialized [Sift object](https://www.npmjs.com/package/sift). 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](https://www.npmjs.com/package/sift), the Mixmax rules engine also supports the following custom expressions: [block:parameters] { "data": { "h-0": "Operator", "0-0": "`$timeOfDay`", "h-1": "Support data types", "h-2": "Description", "0-2": "Matches a range of times within a day. It's an object with parameters:\n1) timezone: the IANA timezone specifier for the timezone\n2) start: the start hour of the day (00-23)\n3) end: the end hour of the day (00-23), must be after start", "1-0": "`$dayOfWeek`", "h-3": "Example value", "0-1": "*Date* or *Timestamp*", "1-1": "*Date* or *Timestamp*", "1-2": "Matches one or more days in a week. It's an object with parameters:\n1) timezone: the IANA timezone specifier for the timezone\n2) days: an array of number days to match (0=Sunday, 6=Saturday)", "0-3": "```\n{\n timezone: \"America/Los_Angeles\", start: 6,\n end: 20\n}\n```", "1-3": "```\n{\n timezone: \"America/Los_Angeles\", days: [1,2,3,4,5]\n}\n```", "2-0": "`$withinTimeRange`", "2-1": "*Date* or *String* or *Timestamp*", "2-3": "```\n{\n days: -1\n}\n```", "2-2": "Matches if the date (or date string) is within the specified time range. Currently supports `days` and `minutes`. Negative number means past." }, "cols": 4, "rows": 3 } [/block] 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 [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "h-2": "Example value", "h-3": "", "0-0": "`$anyRecipient`", "0-1": "Alias for matching `to.email` or `cc.email` or `bcc.email` properties. Only valid for `unopened`, `replied`, and `message:received` event types.", "0-2": "```\n{\n$anyRecipient: {$regex: \"hello@mixmax.com\", $options: \"i\"}\n```", "0-3": "" }, "cols": 3, "rows": 1 } [/block] [block:api-header] { "type": "basic", "title": "Actions" } [/block] The action is the action taken on the event if it passes your filter.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}