Routing rulesets

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

Quick links:

• Inbox routing rules

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.

Find rulesets in dashboard

You can create and manage inbox rulesets in the MailSlurp dashboard or using API integrations.

1. Use sidebar

2. Click inboxes

3. Click rules

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:

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.

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:

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:

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:

// 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 and the 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.

// 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.

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:

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:

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:

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
• Automatic replies