Inbox automation and routing

MailSlurp is an email API service for configuring mailboxes for campaign automation, testing, and application development. There are several features available for controlling the flow of emails within an inbox.

• Inbox Forwarder
• Proxy Alias
• Inbox Routing Rulesets

Let's compare each feature.

Inbox forwarders

Mailboxes can have inbox forwarders attached to them. Forwarders have pattern matching rules that will forwarded selected inbound emails to a given recipient list.

Forwarding can be configured in code or using the dashboard.

const forwarding: CreateInboxForwarderOptions = {
  field: CreateInboxForwarderOptionsFieldEnum.SUBJECT,
  match: '*@bigcompany.com',
  forwardToRecipients: ['sales@mycompany.com'],
};

Rules can match on different fields within an inbound email address:

const fields = [
  CreateInboxForwarderOptionsFieldEnum.SENDER,
  CreateInboxForwarderOptionsFieldEnum.SUBJECT,
  CreateInboxForwarderOptionsFieldEnum.RECIPIENTS,
  CreateInboxForwarderOptionsFieldEnum.ATTACHMENTS,
];

See the email forwarding automation guide for details.

Proxy aliases

Aliases are a way to mask an email address. You can create an alias for an email you wish to keep hidden. When the alias receives email it forwards it to the masked address and creates a new thread inbox for replies. When you reply the thread forwards the message to the original sender while hiding your masked address. This way email addresses can be kept secret during email communication.

Proxies can be controlled via code or using the dashboard:

/**
 * Example of using an email alias to mask an address and forward emails to hidden address
 */
const fetchApi = require('isomorphic-fetch');
const {
  AliasControllerApi,
  InboxControllerApi,
  Configuration,
  WaitForControllerApi,
} = require('mailslurp-client');

// setup mailslurp config
const config = new Configuration({ apiKey, fetchApi });

// create controllers
const inboxControllerApi = new InboxControllerApi(config);
const aliasControllerApi = new AliasControllerApi(config);
const waitForController = new WaitForControllerApi(config);

// create two different email addresses for testing
const inboxA = await inboxControllerApi.createInbox({ name: 'inboxA' });
const inboxB = await inboxControllerApi.createInbox({ name: 'inboxB' });
const emailAddressA = inboxA.emailAddress!!;
const emailAddressB = inboxB.emailAddress!!;

// create an alias
const alias = await aliasControllerApi.createAlias({
  createAliasOptions: {
    emailAddress: emailAddressA,
    useThreads: true,
  },
});
// emailAddressA has been masked by a new email address that was created by the alias
expect(alias.maskedEmailAddress).toEqual(emailAddressA);
expect(alias.emailAddress).not.toEqual(emailAddressA);

// alias isn't verified until you click the confirmation link sent to the aliased address
expect(alias.isVerified).toEqual(true);

See the email proxy guide to get started.

Routing rulesets

Routing enables admins to block sending or receiving of emails based on pattern matching rules. You can combine rules to control what types of emails can be sent or received by a given email address.

Create rulesets in code looks like this:

test('inbox ruleset block sending and throw', async () => {
  const mailslurp = new MailSlurp({ apiKey: process.env.API_KEY! });
  // create two inboxes for testing
  const inbox1 = await mailslurp.inboxController.createInboxWithDefaults();
  const inbox2 = await mailslurp.inboxController.createInboxWithDefaults();

  // can send with no ruleset
  await mailslurp.inboxController.sendEmailAndConfirm({
    inboxId: inbox2.id!,
    sendEmailOptions: { to: [inbox1.emailAddress!], subject: 'Before block' },
  });
  const [received] = await mailslurp.waitController.waitForMatchingEmails({
    matchOptions: {
      matches: [
        {
          field: MatchOptionFieldEnum.FROM,
          should: MatchOptionShouldEnum.CONTAIN,
          value: inbox2.emailAddress,
        },
      ],
    },
    count: 1,
    inboxId: inbox1.id!,
    timeout: 60000,
  });
  expect(received.subject).toContain('Before block');

  // now create sending block for all domains
  const rulesetSendBlock =
    await mailslurp.inboxRulesetController.createNewInboxRuleset({
      inboxId: inbox1.id,
      createInboxRulesetOptions: {
        action: CreateInboxRulesetOptionsActionEnum.BLOCK,
        scope: CreateInboxRulesetOptionsScopeEnum.SENDING_EMAILS,
        target: '*',
      },
    });

  // sending throws an exception for inbox2 recipient
  try {
    await mailslurp.inboxController.sendEmailAndConfirmRaw({
      inboxId: inbox1.id!,
      sendEmailOptions: {
        to: [inbox2.emailAddress!],
        subject: "Can't email inbox2",
      },
    });
  } catch (e: any) {
    expect(e.status).toEqual(400);
    expect(await e.text()).toContain('Inbox ruleset prevents sending');
  }

  // can test ruleset using the test endpoint to find out why blocked
  const testResult =
    await mailslurp.inboxRulesetController.testInboxRulesetsForInbox({
      inboxId: inbox1.id!,
      inboxRulesetTestOptions: {
        testTarget: inbox2.emailAddress!,
      },
    });
  expect(testResult.matches).toBeTruthy();
  // our sending block rule matches
  expect(Object.keys(testResult.rulesetMatches!)).toContain(
    rulesetSendBlock.id
  );
  expect(testResult.rulesetMatches![rulesetSendBlock.id]!).toEqual(true);

  // add an allow rule for inbox2's email address
  const sendingEmailsAllowRule =
    await mailslurp.inboxRulesetController.createNewInboxRuleset({
      inboxId: inbox1.id,
      createInboxRulesetOptions: {
        action: CreateInboxRulesetOptionsActionEnum.ALLOW,
        scope: CreateInboxRulesetOptionsScopeEnum.SENDING_EMAILS,
        target: inbox2.emailAddress,
      },
    });

  // test that our new rule allows sending
  const testResult2 =
    await mailslurp.inboxRulesetController.testInboxRulesetsForInbox({
      inboxId: inbox1.id!,
      inboxRulesetTestOptions: {
        testTarget: inbox2.emailAddress!,
      },
    });
  expect(testResult2.rulesetMatches![rulesetSendBlock.id]!).toEqual(true);
  expect(testResult2.rulesetMatches![sendingEmailsAllowRule.id]!).toEqual(
    true
  );

  // now can send to inbox 2
  const sendRaw = await mailslurp.inboxController.sendEmailAndConfirmRaw({
    inboxId: inbox1.id!,
    sendEmailOptions: {
      to: [inbox2.emailAddress!],
      subject: 'Hi inbox2',
    },
  });
  expect(sendRaw.raw.ok).toBeTruthy();
});

See the inbox routing guide for more information.