# Routing rulesets

Email routing rules for controlling which emails can be sent or received from inboxes.

![](/assets/routing.svg)

## Quick links:
- [Inbox routing rules](https://www.mailslurp.com/guides/inbox-rulesets/)

## About rulesets
Rulesets can be used to define rules about which emails or SMS can be sent or received from an inbox or phone number. Rulesets are applied to inboxes or phone numbers at the account level or specific entity.

<aside data-component="DocsNavigationDisplay" class="docs-navigation-display">
<h3>Find rulesets in dashboard</h3>
<p>You can create and manage inbox rulesets in the MailSlurp dashboard or using API integrations.</p>
<ol class="docs-navigation-steps">
<li><figure class="docs-navigation-step"><img src="/examples-screenshots/ms2-app/navigation/rulesets/0-navbar.jpeg" alt="Find rulesets in dashboard: Use sidebar" loading="lazy" decoding="async" /><figcaption>1. Use sidebar</figcaption></figure></li>
<li><figure class="docs-navigation-step"><img src="/examples-screenshots/ms2-app/navigation/rulesets/1-navbar.jpeg" alt="Find rulesets in dashboard: Click inboxes" loading="lazy" decoding="async" /><figcaption>2. Click inboxes</figcaption></figure></li>
<li><figure class="docs-navigation-step"><img src="/examples-screenshots/ms2-app/navigation/rulesets/2-navbar.jpeg" alt="Find rulesets in dashboard: Click rules" loading="lazy" decoding="async" /><figcaption>3. Click rules</figcaption></figure></li>
</ol>
</aside>

## Creating rulesets
Rulesets can apply to a specific inbox/phone or be account wide. They can also apply to inbound or outbound emails or SMS. You can create rulesets in code like so:

```typescript
const ruleset = await mailslurp.inboxRulesetController.createNewInboxRuleset({
    createInboxRulesetOptions: {
        action: CreateInboxRulesetOptionsActionEnum.BLOCK,
        scope: CreateInboxRulesetOptionsScopeEnum.SENDING_EMAILS,
        target: '*',
    },
    inboxId: undefined,
});
```

In the dashboard you can create rulesets by clicking the `Create ruleset` button on the ruleset page.

![create inbox rules](/examples-screenshots/ms2-app/rulesets/create-ruleset-form.jpeg)

### Testing rules
You can test whether email addresses can send to or receive from an inbox using the ruleset tester. This is useful for debugging rulesets. It can be found on the ruleset index page:

![test inbox rules](/examples-screenshots/ms2-app/rulesets/ruleset-tester.jpeg)

## Rule precedence
Rules apply incrementally and favour `ALLOW` over `BLOCK`. For instance if you have a global `BLOCK` rule for all email addresses and an `ALLOW` for a particular domain, any emails from that domain will be permitted. Here is an example of combined rules and how to test them. First we create two rulesets in code:

```typescript
const inbox = await mailslurp.createInbox();
// block all inbound emails
await mailslurp.inboxRulesetController.createNewInboxRuleset({
    createInboxRulesetOptions: {
        action: CreateInboxRulesetOptionsActionEnum.BLOCK,
        scope: CreateInboxRulesetOptionsScopeEnum.RECEIVING_EMAILS,
        target: '*',
    },
    inboxId: inbox.id
});
// allow from a single domain
await mailslurp.inboxRulesetController.createNewInboxRuleset({
    createInboxRulesetOptions: {
        action: CreateInboxRulesetOptionsActionEnum.ALLOW,
        scope: CreateInboxRulesetOptionsScopeEnum.RECEIVING_EMAILS,
        target: '*@mydomain.com',
    },
    inboxId: inbox.id
});
```

Next we verify that certain domains can send to the inbox:

```typescript
// test receiving from allowed domain
const test1 = await mailslurp.inboxRulesetController.testInboxRulesetReceiving({
    testInboxRulesetReceivingOptions: {
        inboxId: inbox.id,
        fromSender: 'hello@mydomain.com'
    }
})
expect(test1.canReceive).toEqual(true)
// test receiving from any other domain is blocked
const test2 = await mailslurp.inboxRulesetController.testInboxRulesetReceiving({
    testInboxRulesetReceivingOptions: {
        inboxId: inbox.id,
        fromSender: 'hi@other-domain.com'
    }
})
expect(test2.canReceive).toEqual(false)
```

### What happens to blocked emails
Emails that are received but blocked by a rule and saved in the `MissedEmails` section of the app and can also be accessed via [webhooks](/docs/webhooks/) and the [API](/docs/api/).

### Blocking SMS spam
Use rulesets to block inbound SMS spam on your phone numbers. You can do this with two simple rules.

- 1) an account ruleset that `BLOCKS` all `RECEIVING_SMS` from a wild card `*` phone number.
- 2) an account ruleset that `ALLOWS` `RECEIVING_SMS` from specific numbers or patterns you define.

```javascript
// block SMS spam except for known numbers
const blockAll = await rulesetController.createNewRuleset({
  phoneId: undefined, // account wide block
  createRulesetOptions: {
    action: 'BLOCK',
    scope: 'RECEIVING_SMS',
    target: '*'
  }
})
const allowSpecific = await rulesetController.createNewRuleset({
  phoneId: undefined, // account wide permit
  createRulesetOptions: {
    action: 'ALLOW',
    scope: 'RECEIVING_SMS',
    target: '+1234567890' // replace with a known number
  }
})
```

## Simulating bounces
With rulesets you can simulate soft and hard bounces. This is useful for testing email delivery and bounce handling in your application. To do so, you must follow these steps:

- Create an SMTP type inbox
- Create a ruleset with 'BOUNCE_SOFT' or 'BOUNCE_HARD' action and 'RECEIVING_EMAILS' scope

Let's go through some examples.

### Creating a bounce compatible inbox

To simulate bounces you need to use an inbox with the 'SMTP_INBOX' type - this means that the custom MX server will be used at host `mxslurp.click`. The custom server can be configured to give `451` and `550` SMTP errors which will be interpreted as soft and hard bounces respectively.

```javascript
const inbox = await mailslurp.createInboxWithOptions({
  // must use SMTP type inbox for bounce simulation
  inboxType: CreateInboxDtoInboxTypeEnum.SMTP_INBOX
});
```

### Creating a ruleset to bounce emails
Next you will need to create an inbox ruleset that has a bounce action for receiving emails. The ruleset can be created in code like so:

```javascript
const ruleset = await mailslurp.rulesetController.createNewRuleset({
  inboxId: inbox.id,
  createRulesetOptions: {
    action: 'BOUNCE_HARD', // or 'BOUNCE_SOFT'
    scope: 'RECEIVING_EMAILS',
    target: '*'
  }
});
```

### Testing bounce rules
You can test bounces using an SMTP client or by sending emails from another inbox. The ruleset will cause the inbox to return a `451` or `550` SMTP error code depending on the action specified in the ruleset. Here is an example of soft bounce test using the `nodemailer` library:

```javascript
it('can handle soft bounce simulation', async () => {
  const mailslurp = new MailSlurp(config);
  const inbox = await mailslurp.createInboxWithOptions({
    // must use SMTP type inbox for bounce simulation
    inboxType: CreateInboxDtoInboxTypeEnum.SMTP_INBOX
  });
  // create a bounce ruleset for incoming emails
  const ruleset = await mailslurp.rulesetController.createNewRuleset({
    inboxId: inbox.id,
    createRulesetOptions: {
      action: 'BOUNCE_SOFT',
      scope: 'RECEIVING_EMAILS',
      target: '*'
    }
  });
  // test the bounce rule using nodemailer smtp client
  const transport = nodemailer.createTransport({
    host: 'mxslurp.click',
    port: 2525,
    secure: false
  });
  // try send to the inbox
  let err;
  try {
    await transport.sendMail({
      from: 'foo@example.com',
      to: inbox.emailAddress,
      subject: 'Hello full inbox',
      text: 'This should soft bounce'
    });
  } catch (e) {
    err = e;
  }
  // soft bounce error codes
  expect(err?.toString()).toContain('451 4.3.0');
  expect(err?.toString()).toContain('soft bounce');
});
```

And here is a hard bounce example:

```javascript
it('can handle hard bounce simulation', async () => {
  const mailslurp = new MailSlurp(config);
  const inbox = await mailslurp.createInboxWithOptions({
    // must use SMTP type inbox for bounce simulation
    inboxType: CreateInboxDtoInboxTypeEnum.SMTP_INBOX
  });
  // create a bounce ruleset for incoming emails
  const ruleset = await mailslurp.rulesetController.createNewRuleset({
    inboxId: inbox.id,
    createRulesetOptions: {
      action: 'BOUNCE_HARD',
      scope: 'RECEIVING_EMAILS',
      target: '*'
    }
  });
  // test the bounce rule using nodemailer smtp client
  const transport = nodemailer.createTransport({
    host: 'mxslurp.click',
    port: 2525,
    secure: false
  });
  // try send to the inbox
  let err;
  try {
    await transport.sendMail({
      from: 'foo@example.com',
      to: inbox.emailAddress,
      subject: 'Hello blocker',
      text: 'This should bounce'
    });
  } catch (e) {
    err = e;
  }
  // hard bounce error codes
  expect(err?.toString()).toContain('550 5.1.1');
  expect(err?.toString()).toContain('hard bounce');
});
```

## Forwarding and replies
If you wish to match recipients and automatically reply or forward see those features:

- [Forwarding rules](/docs/forwarding/)
- [Automatic replies](/docs/repliers/)