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.

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.

Related content

Receive email in code and tests

Use MailSlurp email APIs to fetch and process emails in tests or apps.

Email auto-forwarding rules

Create email forwarding rules for inbound emails to reroute messages.

Receive emails and attachments with Webhook Push

Receive emails with http webhooks. Webhooks let you respond to inbound email streams in real time on your server or within an application.

Receiving and reading emails

Read emails and attachments in code and tests. Wait for unread emails using long-polling or webhooks.

Send and receive emails

Use inbound and outbound email in code, mail-clients, or online dashboard. Add attachments, configure webhooks and gain SMTP access.

Ready to dive in?Start building email applications today.