Email auto-forwarding rules

Create email forwarding rules for inbound emails to reroute messages.

MailSlurp inboxes support email auto-forwarding using inbox forwarding rules. You can attach inbox forwarders to any inbox and configure rules that will forward inbound email to other email addresses based on matching fields within the email such as body, subject or sender.

Forwarder alternatives

  • Auto repliers: allow automatic replies for matching emails.
  • Inbox aliases: mask email address behind two-way inbox to hide original email address.

How does inbox forwarding work?

Inbox forwarders are entities that can be attached to an inbox. There are one-way forwarders that match emails against a rulesets to determine whether the inbound message should be forwarded to a recipient associated with the forwarder. For two-way inbox proxies see the alias guide.

forwarder

Inbox forwarders can have multiple rulesets. Rules use pattern matching applied to fields within an email. So for the above example a forwarder is matched on the email subject using the asterisk in Hi* as wildcard. This means inbound emails with Hi there as a subject will be forwarded by the forwarder.

Setup

Inbox forwarding is configured for each inbox using the UI or the InboxForwarderControllerApi. Each inbox forwarder takes a field, match and forwardToRecipient option.

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,
];

For instance a rule using the SENDER field will match incoming email address senders against the match option in the inbox forwarder. Emails that match this rule will be forwarded to the recipients listed in the rules forwardToRecipient option.

To configure rules in the MailSlurp dashboard navigate to the inbox forwarding page and create a new inbox forwarder for an inbox of your choice:

email routing

Basic example

Let's create some inboxes with MailSlurp's javascript client and attach inbox forwarding rules.

const mailslurp = new MailSlurp({ apiKey: process.env.apiKey });
// create two inboxes for testing
const inbox1 = await mailslurp.inboxController.createInboxWithDefaults();
const inbox2 = await mailslurp.inboxController.createInboxWithDefaults();
const inbox3 = await mailslurp.inboxController.createInboxWithDefaults();

// add auto forwarding rule to inbox 2
await mailslurp.inboxForwarderController.createNewInboxForwarder({
  // attach rule to inbox 2
  inboxId: inbox2.id,
  createInboxForwarderOptions: {
    // filter emails that match the sender from inbox 1 and send to inbox 3
    field: CreateInboxForwarderOptionsFieldEnum.SENDER,
    match: inbox1.emailAddress,
    forwardToRecipients: [inbox3.emailAddress],
  },
});

// send email from inbox1 to inbox2
await mailslurp.sendEmail(inbox1.id!!, {
  to: [inbox2.emailAddress!!],
  subject: 'Hello',
});

// see that inbox2 gets the original email
const receivedEmail = await mailslurp.waitForLatestEmail(
  inbox2.id,
  60000,
  true
);
expect(receivedEmail.subject).toContain('Hello');

// see that inbox3 gets a forwarded email
const forwardedEmail = await mailslurp.waitForLatestEmail(
  inbox3.id,
  60000,
  true
);
expect(forwardedEmail.subject).toContain('Hello');

// check the sent messages for inbox2 to find the forwarded message
const sentFromInbox2 = await mailslurp.sentController.getSentEmails({
  inboxId: inbox2.id,
});
expect(sentFromInbox2.totalElements).toEqual(1);
const forwardedMessage = sentFromInbox2.content[0];
expect(forwardedMessage.to).toEqual([inbox3.emailAddress]);
expect(forwardedMessage.from).toEqual(inbox2.emailAddress);

Wildcard matching

Basic wildcard pattern matching is available:

const mailslurp = new MailSlurp({ apiKey: process.env.apiKey });
// create two inboxes for testing
const inbox1 = await mailslurp.inboxController.createInboxWithDefaults();
const inbox2 = await mailslurp.inboxController.createInboxWithDefaults();
const inbox3 = await mailslurp.inboxController.createInboxWithDefaults();

const inbox1Domain = inbox1.emailAddress.split('@')[1];

// add auto forwarding rule to inbox 2
await mailslurp.inboxForwarderController.createNewInboxForwarder({
  // attach rule to inbox 2
  inboxId: inbox2.id,
  createInboxForwarderOptions: {
    // filter emails that match the sender from inbox 1 and send to inbox 3
    field: CreateInboxForwarderOptionsFieldEnum.SENDER,
    // notice the use of the wildcard when matching
    // this will match any address with the same domain as inbox 1
    match: `*@${inbox1Domain}`,
    forwardToRecipients: [inbox3.emailAddress],
  },
});

// send email from inbox1 to inbox2
await mailslurp.sendEmail(inbox1.id!!, {
  to: [inbox2.emailAddress!!],
  subject: 'Hello wildcard',
});

// see that inbox2 gets the original email
const receivedEmail = await mailslurp.waitForLatestEmail(
  inbox2.id,
  60000,
  true
);
expect(receivedEmail.subject).toContain('Hello wildcard');

// see that inbox3 gets a forwarded email
const forwardedEmail = await mailslurp.waitForLatestEmail(
  inbox3.id,
  60000,
  true
);
expect(forwardedEmail.subject).toContain('Hello wildcard');

// check the sent messages for inbox2 to find the forwarded message
const sentFromInbox2 = await mailslurp.sentController.getSentEmails({
  inboxId: inbox2.id,
});
expect(sentFromInbox2.totalElements).toEqual(1);
const forwardedMessage = sentFromInbox2.content[0];
expect(forwardedMessage.to).toEqual([inbox3.emailAddress]);
expect(forwardedMessage.from).toEqual(inbox2.emailAddress);

Forwarding with complex sender name

Forwarding also works with RFC 5322 email addresses that contain a sender name:

const mailslurp = new MailSlurp({ apiKey: process.env.apiKey });
// create three test inboxes
const inbox1 = await mailslurp.createInboxWithOptions({ name: 'John Doe' });
expect(inbox1.name).toContain('John Doe');
const inbox2 = await mailslurp.inboxController.createInboxWithDefaults();
const inbox3 = await mailslurp.inboxController.createInboxWithDefaults();

// create forwarding rules
// add auto forwarding rule to inbox 2
await mailslurp.inboxForwarderController.createNewInboxForwarder({
  // attach rule to inbox 2
  inboxId: inbox2.id,
  createInboxForwarderOptions: {
    // filter emails that match the sender from inbox 1 and send to inbox 3
    field: CreateInboxForwarderOptionsFieldEnum.SENDER,
    match: inbox1.emailAddress,
    forwardToRecipients: [inbox3.emailAddress],
  },
});
// send an email that includes name in sender (RFC 5322)
await mailslurp.sendEmail(inbox1.id!!, {
  to: [inbox2.emailAddress!!],
  subject: 'Hello with name',
  useInboxName: true,
});

// see that inbox2 gets the original email
const receivedEmail = await mailslurp.waitForLatestEmail(
  inbox2.id,
  60000,
  true
);
expect(receivedEmail.subject).toContain('Hello with name');
expect(receivedEmail.sender.name).toContain(`John Doe`);
expect(receivedEmail.sender.emailAddress).toContain(inbox1.emailAddress);

// get the sent email and check that the sender contains the email name
const sentMessages = await mailslurp.sentController.getSentEmails({
  inboxId: inbox1.id,
});
const sentMessage = await mailslurp.sentController.getSentEmail({
  id: sentMessages.content[0].id!!,
});
expect(sentMessage.from).toEqual(`John Doe <${inbox1.emailAddress}>`);

// see that inbox3 gets a forwarded email
const forwardedEmail = await mailslurp.waitForLatestEmail(
  inbox3.id,
  60000,
  true
);
expect(forwardedEmail.subject).toContain('Hello with name');

More options

For other use cases consider using email webhooks to process incoming emails and route them using your own server logic.