Webhooks for bounces

SMTPeter normally modifies the envelope address of all mails that flow through it to track bounces and other messages that are sent back. All bounce messages are therefore sent back to SMTPeter. You can however set up a 'bounce' Webhook to be notified about these bounces too.

Type of messages

The bounce Webhook is used for literally all messages that are sent back to the envelope address. This includes the regular delivery status notifications, but also out-of-office replies, vacation mails, or error messages from servers that do not respect the official format for bounce messages. All these type of messages are sent back to SMTPeter and with a Webhook you can also receive these messages in real-time.

Bounces vs Delivery Status Notifications

SMTPeter sends out messages using the SMTP protocol. This protocol allows remote servers to either accept a message or to refuse it. Refused mails are written to the failure logfile and are sent to the failure Webhooks (see diagram 1).

Diagram 1

However, even when a message is initially accepted (and thus not considered a failure), it still is possible for the other server to send back a bounce email later on in which we're told that the message is rejected after all. These bounce messages are Delivery Status Notifications and have a special format. SMTPeter recognizes these bounces, and adds these errors to the log file too, and calls your failure Webhook (see diagram 2).

Diagram 2

Besides these standardized Delivery Status Notifications, there are many more messages that are sent back to the envelope address. These are for example out-of-office mails or vacation mails, but also error messages (like "mailbox full" or "email address does not exist") from servers that do not respect the official Delivery Status Notification format. These messages are also picked up by SMTPeter.

Because such messages do not follow the official standard for Delivery Status Notifications, they can not be recognized by SMTPeter and are not written to the error log file or are sent to failure Webhooks. Such incoming bounces are only written to the bounce log file, and are sent to the bounce Webhooks. The bounce Webhook thus receives two sort of messages: official Delivery Status Notifications, and bounces and out-of-office replies that could not be recognized.


The bounce Webhook is sent over HTTP POST and the following variables are submitted:

Variable Description
id Original message ID with which the bounce is associated
type Type of action that triggered the Webhook ('bounce')
timestamp Timestamp for the bounce (in YYYY-MM-DD HH:MM:SS format)
time Unix time for the bounce
recipient Email address to which the original mail was sent
envelope Envelope address to send the bounce to
mime The MIME data that was sent (the message itself)
tags The tags that you associated with the mail

The 'id' and 'recipient' and 'tags' variables allow you to link the incoming bounce to the original outgoing message that was sent.

More information