{"id":5868,"date":"2023-09-21T13:01:02","date_gmt":"2023-09-21T11:01:02","guid":{"rendered":"https:\/\/www.inboxroad.com\/?page_id=5868"},"modified":"2025-10-06T14:26:29","modified_gmt":"2025-10-06T12:26:29","slug":"webhook-handling-email-events","status":"publish","type":"page","link":"https:\/\/www.inboxroad.com\/de\/documentation\/webhook-handling-email-events\/","title":{"rendered":"Webhook: Handling Email Events"},"content":{"rendered":"\r\n<h2>Introduction<\/h2>\r\n<p class=\"wp-block-paragraph\">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.<\/p>\r\n<h2>1. Overview of Email Events<\/h2>\r\n<p>Inboxroad facilitates the tracking of:<\/p>\r\n<ul>\r\n<li>Bounces (&#8222;b&#8220;) &amp; (&#8222;rb&#8220;): Emails that are not delivered, differentiated as HARD and SOFT based on the underlying reason.<\/li>\r\n<li>Delivered (&#8222;d&#8220;): Emails that reach the recipient&#8217;s inbox successfully.<\/li>\r\n<li>Complaints (&#8222;f&#8220;): Emails reported as spam or considered unwanted.<\/li>\r\n<\/ul>\r\n<h2>2. Setting up the Webhook for Email Events<\/h2>\r\n<ul>\r\n<li>Setup an endpoint on your end to receive webhook events.\u00a0<\/li>\r\n<li>Login to Inboxroad, go to <a href=\"https:\/\/app.inboxroad.com\/settings\/webhooks\" target=\"_blank\" rel=\"noopener\">settings\/ webhooks<\/a> and fill in the necessary data.<\/li>\r\n<\/ul>\r\n<h2>3. Email Event Payload Structure and Sample<\/h2>\r\n<p>Upon the occurrence of an email event, Inboxroad sends an HTTP POST request with detailed payload information. Here&#8217;s an overview:<\/p>\r\n<ul>\r\n<li>type: Represents the event type (\u201cb\u201d for bounced, \u201crb\u201d for remote bounced, &#8222;d&#8220; for delivered, &#8222;f&#8220; for complaints).<\/li>\r\n<li>timeLogged: Timestamp marking when the event was logged.<\/li>\r\n<li>orig: Sender&#8217;s email address.<\/li>\r\n<li>rcpt: Recipient&#8217;s email address.<\/li>\r\n<li>dsnAction: Delivery status notification action.<\/li>\r\n<li>dsnStatus: Delivery status notification&#8217;s status.<\/li>\r\n<li>dsnDiag: Diagnostic information from the SMTP.<\/li>\r\n<li>bounceCat: The category of the bounce.<\/li>\r\n<li>rcvSmtpUser: The SMTP user who received the email.<\/li>\r\n<li>header_Message-Id: A unique identifier for the email.<\/li>\r\n<li>vmta: The Virtual Mail Transfer Agent used.<\/li>\r\n<\/ul>\r\n<p>&nbsp;<\/p>\r\n<p>The payload should be in the following format:<\/p>\r\n\r\n\r\n\r\n<pre class=\"wp-block-code\" title=\"payload\"><code class=\"language-json\" lang=\"json\">\r\njson\r\n\r\n{\r\n    \"type\": \"d\",\r\n    \"timeLogged\": \"1695222842\",\r\n    \"orig\": \"adress@rp.domain.com\",\r\n    \"rcpt\": \"example@domain.net\",\r\n    \"dsnAction\": \"relayed\",\r\n    \"dsnStatus\": \"2.0.0 (success)\",\r\n    \"dsnDiag\": \"smtp;250 2.0.0 OK\",\r\n    \"bounceCat\": \"other\",\r\n    \"rcvSmtpUser\": \"user\",\r\n    \"header_Message-Id\": \"&lt;80894b937274b975f9e3ab05f0a009636d2016d9@rp.domain.com&gt;\",\r\n    \"vmta\": \"a000\"\r\n}<\/code><\/pre>\r\n\r\n\r\n\r\n<h2>4. Bounce Classification with BOUNCE_MAPPER<\/h2>\r\n<p>Inboxroad provides a granular bounce classification system to enable precise actions based on the bounce&#8217;s nature. This is categorized using the bounceCat field in the payload, as:<\/p>\r\n\r\n<pre class=\"wp-block-code\" title=\"\"><code class=\"language-json\" lang=\"json\">\r\npython\r\n\r\nBOUNCE_MAPPER = {\r\n    'message-expired': 'EXPIRED',\r\n    'bad-mailbox': 'HARD',\r\n    'bad-domain': 'HARD',\r\n    'quota-issues': 'SOFT',\r\n    'inactive-mailbox': 'SOFT',\r\n    'no-answer-from-host': 'SOFT',\r\n    'relaying-issues': 'SOFT',\r\n    'routing-errors': 'SOFT'\r\n}\r\n<\/code><\/pre>\r\n<p>Leverage this mapper to ascertain the nature of each bounce (e.g., HARD, SOFT, EXPIRED).<\/p>\r\n<h2>5. Handling Email Events<\/h2>\r\n<p>For Bounces (\u201cb\u201d) &amp; (\u201crb)\u201d: Use the BOUNCE_MAPPER to classify and act. For example:<\/p>\r\n<ul>\r\n<li>HARD bounces typically highlight persistent issues. These should not be targetted in your next campaign(s).<\/li>\r\n<li>SOFT bounces might be transient, necessitating careful observation before action. Monitor the soft bounces and exclude them from your list after 5 occurrences.<\/li>\r\n<\/ul>\r\n<p>For Delivered (&#8222;d&#8220;): Analyze, log, and respond as suitable for your application.<\/p>\r\n<p>For Complaints (&#8222;f&#8220;): Don\u2019t target these anymore since they\u2019ve complained on one of your campaigns.<small><\/small><\/p>\r\n\r\n\r\n\r\n<h2 class=\"wp-block-heading\">Contact us if you need help<\/h2>\r\n\r\n\r\n\r\n<p class=\"wp-block-paragraph\">Please reach out to <a href=\"https:\/\/www.inboxroad.com\/contact\/\" data-type=\"link\" data-id=\"https:\/\/www.inboxroad.com\/contact\/\">our support team<\/a> if you need help.<\/p>\r\n","protected":false},"excerpt":{"rendered":"<p>Introduction Inboxroad webhooks offer real-time notifications, ensuring swift responses to email events like deliveries,&#8230;<\/p>\n","protected":false},"author":4,"featured_media":4993,"parent":9,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"page-documentation.php","meta":{"_acf_changed":false,"om_disable_all_campaigns":false,"inline_featured_image":false,"_monsterinsights_skip_tracking":false,"footnotes":""},"class_list":["post-5868","page","type-page","status-publish","has-post-thumbnail","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/pages\/5868","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/comments?post=5868"}],"version-history":[{"count":1,"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/pages\/5868\/revisions"}],"predecessor-version":[{"id":8564,"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/pages\/5868\/revisions\/8564"}],"up":[{"embeddable":true,"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/pages\/9"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/media\/4993"}],"wp:attachment":[{"href":"https:\/\/www.inboxroad.com\/de\/wp-json\/wp\/v2\/media?parent=5868"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}