Simulate soft and hard bounce email responses
Create a test email address for bounce simulation, assert SMTP 451 and 550 responses, and verify delivery after removing the bounce rule.

To test email bounce handling, you need a recipient that reliably rejects a message in a way you control. A made-up address is a poor substitute: it may exist, a domain may accept all recipients, or your sending service may keep retrying before it reports failure.
MailSlurp is an email testing platform that provides programmable inboxes. Its SMTP inbox rules let you simulate a temporary rejection or a permanent rejection at the receiving server, then remove the rule to test recovery. You can repeat the test without involving customer addresses.
Choose the response you want to test
A soft bounce describes a temporary delivery problem, while a hard bounce describes a permanent rejection of the message as submitted. MailSlurp's bounce rules produce these responses:
| Receiving rule | SMTP response | Test case |
|---|---|---|
BOUNCE_SOFT |
451 |
A temporary failure that your sender may retry |
BOUNCE_HARD |
550 |
A permanent rejection that requires a different action |
These are specific simulation responses, not the only codes that real mail servers use. The SMTP response classes distinguish temporary 4xx replies from permanent 5xx replies. The bounce-back guide explains how to interpret a later delivery report and its enhanced status code.
Direct SMTP errors and provider bounce events
The example connects directly to the receiving SMTP server, so Nodemailer sees the rejection during sendMail(). If your application submits through an ESP, that service can accept the submission first and report the recipient's failure later through a webhook or delivery-status event. A successful submission response is therefore a different assertion from successful delivery.
Test the direct response first to establish the simulated condition. Then use the same kind of controlled recipient in a separate test through your application's sending provider, and wait for that provider's documented event. Its retry schedule, event names and suppression policy determine what your application observes.
How to simulate bounces with MailSlurp
Use a MailSlurp account with SMTP inbox and ruleset access, a MailSlurp API key, and Node.js. Your environment must also allow an outbound connection to the SMTP host and port returned by the API. Install the client packages in your test project:
npm install mailslurp-client nodemailer
Set MAILSLURP_API_KEY in your shell or test runner's secret settings. Keep the key out of the script. The example uses a synthetic message and creates a separate inbox for each response so the tests do not change an existing inbox's behavior.
Give each test its own receiving rule
The inbox must have type SMTP_INBOX. Attach the rule to that inbox with RECEIVING_EMAILS scope and target *, which matches incoming senders. Create one bounce rule at a time; deleting the soft-bounce rule before a hard-bounce test avoids competing rules.
The script below runs both cases. Each case asserts the SMTP reply code and bounce diagnostic, deletes its rule, sends a fresh message, and waits for that message in the inbox. It also closes the transport and attempts to delete the test resources if an assertion fails.
Run both rejection and recovery checks
Save this as bounce-test.cjs:
const assert = require('node:assert/strict');
const { randomUUID } = require('node:crypto');
const nodemailer = require('nodemailer');
const {
MailSlurp,
CreateInboxDtoInboxTypeEnum,
CreateRulesetOptionsActionEnum,
CreateRulesetOptionsScopeEnum,
} = require('mailslurp-client');
async function testBounce(mailslurp, action, expectedCode, expectedReason) {
const inbox = await mailslurp.createInboxWithOptions({
inboxType: CreateInboxDtoInboxTypeEnum.SMTP_INBOX,
});
let transport;
let rule;
try {
const access = await mailslurp.inboxController.getSmtpAccess({
inboxId: inbox.id,
});
transport = nodemailer.createTransport({
host: access.smtpServerHost,
port: access.smtpServerPort,
secure: false,
connectionTimeout: 10000,
greetingTimeout: 10000,
socketTimeout: 20000,
});
const message = {
from: 'bounce-test@example.com',
to: inbox.emailAddress,
subject: `Bounce test ${randomUUID()}`,
text: 'Synthetic message for a controlled bounce test.',
};
rule = await mailslurp.rulesetController.createNewRuleset({
inboxId: inbox.id,
createRulesetOptions: {
action,
scope: CreateRulesetOptionsScopeEnum.RECEIVING_EMAILS,
target: '*',
},
});
await assert.rejects(
() => transport.sendMail(message),
(error) => {
assert.equal(error.responseCode, expectedCode);
assert.match(error.response, expectedReason);
return true;
},
`Expected SMTP ${expectedCode}`,
);
await mailslurp.rulesetController.deleteRuleset({ id: rule.id });
rule = undefined;
const recovery = {
...message,
subject: `Bounce recovery ${randomUUID()}`,
};
const result = await transport.sendMail(recovery);
assert.deepEqual(result.accepted, [inbox.emailAddress]);
assert.deepEqual(result.rejected, []);
const received = await mailslurp.waitForLatestEmail(inbox.id, 30000, true);
assert.equal(received.subject, recovery.subject);
} finally {
transport?.close();
try {
if (rule) {
await mailslurp.rulesetController.deleteRuleset({ id: rule.id });
}
} finally {
await mailslurp.deleteInbox(inbox.id);
}
}
console.log(`${action}: SMTP ${expectedCode}, then recovery received`);
}
async function main() {
const apiKey = process.env.MAILSLURP_API_KEY;
assert.ok(apiKey, 'Set MAILSLURP_API_KEY');
const mailslurp = new MailSlurp({ apiKey });
await testBounce(mailslurp, CreateRulesetOptionsActionEnum.BOUNCE_SOFT, 451, /soft bounce/i);
await testBounce(mailslurp, CreateRulesetOptionsActionEnum.BOUNCE_HARD, 550, /hard bounce/i);
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
Run it with:
node bounce-test.cjs
A successful run prints one line for BOUNCE_SOFT and one for BOUNCE_HARD, each confirming the expected rejection followed by a received recovery message. The inboxes are deleted when their tests finish. If cleanup fails, inspect the reported error and remove any remaining test inbox or rule before rerunning.
assert.rejects fails if the send unexpectedly succeeds. Its callback checks responseCode and the bounce diagnostic, so a connection error or a rejection with a different explanation fails the test. The recovery check verifies both SMTP acceptance and receipt with the expected subject; acceptance alone would leave the receiving step untested.
Nodemailer's SMTP transport settings control the connection timeouts. If a test times out or reports an authentication error, check the endpoint and network access before interpreting it as a simulated bounce. This example sends to its own receiving inbox; it does not configure an authenticated outbound relay.
Check what your application does with the failure
Once the response test passes, exercise the code that handles the failure in your application. For a temporary error, check that it follows the chosen retry policy and does not mark the recipient as permanently invalid. If an ESP already owns the queued message, avoid adding a second retry queue that sends duplicate copies.
For a permanent rejection, check that the application stops repeating the unchanged send and retains the reason. A real 550 can describe a policy problem as well as an invalid address, so address suppression should use the detailed diagnostic or the provider's classification. Removing the simulation rule proves recovery for the test inbox; it does not establish that a real recipient's underlying problem has been fixed.