Webhook: Handling Email Events


Inboxroad webhooks offer real-time notifications, ensuring swift responses to email events like deliveries, bounces, or complaints. These webhooks provide valuable insights into email deliverability, enabling refined email campaign strategies. Automated list management via webhooks helps maintain clean email lists, reducing costs and enhancing user engagement. Real-time data from webhooks also aligns with email best practices, keeping up sender reputation.

1. Overview of Email Events

Inboxroad facilitates the tracking of:

  • Bounces (“b”) & (“rb”): Emails that are not delivered, differentiated as HARD and SOFT based on the underlying reason.
  • Delivered (“d”): Emails that reach the recipient’s inbox successfully.
  • Complaints (“f”): Emails reported as spam or considered unwanted.

2. Setting up the Webhook for Email Events

  • Setup an endpoint on your end to receive webhook events.
  • Reach out to contact@inboxroad.com, mention your endpoint and we’ll handle the rest.

3. Email Event Payload Structure and Sample

Upon the occurrence of an email event, Inboxroad sends an HTTP POST request with detailed payload information. Here’s an overview:

  • type: Represents the event type (“b” for bounced, “rb” for remote bounced, “d” for delivered, “f” for complaints).
  • timeLogged: Timestamp marking when the event was logged.
  • orig: Sender’s email address.
  • rcpt: Recipient’s email address.
  • dsnAction: Delivery status notification action.
  • dsnStatus: Delivery status notification’s status.
  • dsnDiag: Diagnostic information from the SMTP.
  • bounceCat: The category of the bounce.
  • rcvSmtpUser: The SMTP user who received the email.
  • header_Message-Id: A unique identifier for the email.
  • vmta: The Virtual Mail Transfer Agent used.


The payload should be in the following format:


    "type": "d",
    "timeLogged": "1695222842",
    "orig": "adress@rp.domain.com",
    "rcpt": "example@domain.net",
    "dsnAction": "relayed",
    "dsnStatus": "2.0.0 (success)",
    "dsnDiag": "smtp;250 2.0.0 OK",
    "bounceCat": "other",
    "rcvSmtpUser": "user",
    "header_Message-Id": "<80894b937274b975f9e3ab05f0a009636d2016d9@rp.domain.com>",
    "vmta": "a000"

4. Bounce Classification with BOUNCE_MAPPER

Inboxroad provides a granular bounce classification system to enable precise actions based on the bounce’s nature. This is categorized using the bounceCat field in the payload, as:


    'message-expired': 'EXPIRED',
    'bad-mailbox': 'HARD',
    'bad-domain': 'HARD',
    'quota-issues': 'SOFT',
    'inactive-mailbox': 'SOFT',
    'no-answer-from-host': 'SOFT',
    'relaying-issues': 'SOFT',
    'routing-errors': 'SOFT'

Leverage this mapper to ascertain the nature of each bounce (e.g., HARD, SOFT, EXPIRED).

5. Handling Email Events

For Bounces (“b”) & (“rb)”: Use the BOUNCE_MAPPER to classify and act. For example:

  • HARD bounces typically highlight persistent issues. These should not be targetted in your next campaign(s).
  • SOFT bounces might be transient, necessitating careful observation before action. Monitor the soft bounces and exclude them from your list after 5 occurrences.

For Delivered (“d”): Analyze, log, and respond as suitable for your application.

For Complaints (“f”): Don’t target these anymore since they’ve complained on one of your campaigns.

Contact us if you need help

Please reach out to our support team if you need help.