MailSlurp has a concept called that allow you to create complex rules and patterns for an inbox to control:

  • what emails are accepted by an inbox
  • what recipients an inbox can send emails to

You can add multiple rules to an inbox using wildcard patterns and standard email address matching. This guide explains different use cases with examples and documentation.

Inbox ruleset lifecycle

Here is a brief overview of how inbox rulesets are evaluated. If an inbox has rulesets they will be evaluated against email addresses within outbound and bound emails to block, filter, or allow the sending or receiving action.

Emails that are blocked during receiving are stored as missed emails and can be accessed in the dashboard or via the API.

Structure of rulesets

Each inbox ruleset has the following properties

PropertyDescriptionExample values
inboxIdID of inbox to attach ruleset to
scopeWhen to evaluate a ruleset,
actionWhat action to take if rule matches, ,
targetThe pattern to match email sender or recipients against. Can be a wildcard pattern using or an email address,

Scope types

ScopeDescription
Inbox rulesets scoped to receiving emails will be evaluated whenever an attached inbox receives an email. Target is matched against the sender from field. Use with or actions.
Rules scoped to sending emails will be evaluated before emails are sent from an attached inbox. Use to strip blocked addresses to prevent sending to target email addresses or use and to block or allow if a target matches any recipient in the send options.

Action types

ActionWorks with ScopeDescription
All scopesIf a ruleset matches a target email address in received or sending email the email will be blocked from being received or sent respectively.
All scopesIf a ruleset matches a target email address in any scope the email will be allowed to be sent or received. If you have several specific actions and a more permissive the allow will take precedence.
Will remove matching email address from an email before sending to ensure that email addresses cannot be sent to those addresses. Differs from in way that still allows an email to be sent it just removes the affected email addresses.

Target syntax

The property of an inbox ruleset is a wildcard pattern or email address that can be used by the ruleset to evaluate inputs to see if the ruleset matches.

Target typeExampleDescription
Wild card matchingUse asterisk wild cards to match for email address patterns. Useful for blocking, allowing, or filtering email address from whole domains
Email matchingDirect email matching (case insensitive) for more precise blocking, allowing, and filter of email addresses

If you need to target multiple email addresses use multiple inbox rulesets or a wildcard pattern.

Action precedence

The action will always override if a ruleset matches for both. So if you add a ruleset to an inbox but also add an using the scope then the inbox will block all inbound emails except those from test@gmail.com. Read further for more information on scope.

actions have a higher precedence than so if two actions match for a ruleset target the will override the .

Creating inbox rulesets

To create a ruleset first create an inbox in the Mailslurp dashboard or using the API. You can then add as many rulesets as you wish to a given inbox using the inbox ID. Let's see different ways to create rulesets and the cover what different scopes and actions do.

Create rules in code

More code examples

To use Inbox Rulesets in code use the REST API or an official SDK client. Here we will configure the MailSlurp Javascript client to create and test inbox rulesets using jest.

Setup

Block sending

Filter remove when sending

In this example we demonstrate the use of action inbox ruleset to ensure that a particular email address cannot have emails sent to it from an inbox.

Block inbox receiving emails