Simulate soft and hard bounce email responses

Email bounces and rejections are common in email delivery. They can occur for various reasons, such as invalid email addresses, full mailboxes, or server issues. In this guide, we will explore how to simulate soft and hard bounces using MailSlurp's bounce simulation rules.

If you need the operating model behind those labels before you simulate them, read Soft bounce vs hard bounce.

What are email bounces?

Email bounces occur when an email cannot be delivered to the recipient's mailbox. There are two main types of bounces:

• Soft Bounce: This is a temporary issue, such as a full mailbox or a server that is temporarily unavailable. The email may be delivered later. A soft bounce typically results in a 451 SMTP error code.

• Hard Bounce: This is a permanent issue, such as an invalid email address or a domain that does not exist. A hard bounce typically results in a 550 SMTP error code.

Why simulate bounces?

Simulating bounces is useful for testing email delivery and bounce handling in your application. It allows you to verify that your application can handle bounce scenarios correctly without sending real emails to invalid addresses.

How to simulate bounces with MailSlurp

In MailSlurp, you can simulate bounces by creating a ruleset with a bounce action. This ruleset can be applied to an inbox to simulate soft and hard bounces for incoming emails.

Step 1: Create an SMTP inbox

To simulate bounces, you need to create an SMTP inbox. This type of inbox uses a custom MX server that can return 451 and 550 SMTP error codes for soft and hard bounces, respectively. Using the MailSlurp API or Javascript client, you can create an SMTP inbox like this:

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

Step 2: Create a bounce ruleset

Next we need to attach a rule to the inbox that will cause it to return a bounce response. This can be done by creating a ruleset with 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: '*'
  }
});

Step 3: Test bounce rules

Now that we have an inbox with a ruleset we can test the bounce. To do so we need to get the smtp server details for the inbox like so:

// use access details to connect to SMTP server
const {
  smtpServerHost,
  smtpServerPort,
} = await mailslurp.inboxController.getSmtpAccess({
  inboxId: inbox.id
});

Then we can use an SMTP client (like nodemailer) to send an email to the inbox and observe the bounce response. Here is an example of a hard bounce test using the nodemailer library:

// test the bounce rule using nodemailer smtp client
const transport = nodemailer.createTransport({
  host: smtpServerHost,
  port: smtpServerPort,
  secure: false
});
// try send to the inbox and catch exception
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');

Conclusion

That's it! You have successfully simulated soft and hard bounces using MailSlurp's bounce simulation rules. This allows you to test your application's email handling capabilities without sending real emails to invalid addresses. You can now handle bounce scenarios effectively in your application.

This bounce simulator works with any SMTP client or mail provider. For more information, see the inbox rulesets documentation and the inbox rulesets guide.