What is the rules engine?

Rules are a flexible way sophisticated, non-programmers can change sending behavior based on searchable criteria in Mandrill emails. The rules engine lets you take specific actions when events or messages meet criteria you've set.

You can also view example rules to help you get started.

Rule Format

Rules in Mandrill follow traditional if/then and any/all conditional logic. You can think of rules as following the sentence structure:

if any email matches this then do that

For example, "if any email is sent from notifications@example.com then add the 'notifications' tag."

A rule can have multiple criteria and the criteria can contain wildcard pattern matches. Mandrill supports the fnmatch format for wildcard pattern matching. For example, if you want to create a new rule that looks for any emails containing "QA" anywhere in the subject line, your rule condition would look like this:

subject line matches *QA*

But if you want to create a new rule that looks for any emails containing "[QA]" in the subject line (note the brackets), your rule condition would look like this:

subject line matches *\[QA\]*

Rule Triggers

  • a message is sent
  • is delayed
  • is bounced
  • is soft-bounced
  • is opened
  • is clicked
  • a recipient unsubscribes
  • a message is marked as spam
  • is rejected
  • is inbound

Rule Conditions

Each rule can have one or more conditions.

  • recipient's email matches/does not match
  • sender's email matches/does not match
  • subject line matches/does not match
  • tags contains/does not contain
  • template is/is not
  • api key is/is not
  • matched rules contains/does not contain
  • random sample %

Rule actions

Each rule can take one or more actions.

  • do nothing
  • send event to webhook

These conditions are available only for messages that are sent:

  • reject message
  • add google analytics
  • add tag
  • set template
  • set open tracking
  • set click tracking
  • set text generation from HTML
  • set HTML generation from text
  • set CSS inlining
  • set content logging
  • set subaccount
  • set tracking domain
  • set return-path domain

Order of Rules

Rules can both change the content of messages and match on the content of messages, so it's important that they are applied in a consistent order. For example, you might have one rule that matches emails from a specific sender that sets the template to my-template. You may also have another rule that matches emails using my-template and adds the tag my-tag.

Whether or not the email has my-tag depends on whether the rule to add the template is applied before or after the rule that adds the tag. To help control this, Mandrill lets you sort your rules, and they will be applied consistently from the top of the list to the bottom. This can give you a lot of power by creating rules that prepare for other rules further down the list.

Use the handle on the left side of a rule to move its position:


Nested Rules

Nested rules let one rule refer to other rules in their conditions. Use nested rules to avoid repetition if the same conditions are duplicated across multiple rules. For example, here are nested rules that send Gmail password reset emails to a webhook:

Example of nested rules


API keys without descriptions aren't available for rule conditions. Manage API keys on the SMTP & API Info page in your Mandrill account.