Email Event Webhooks

Email event webhooks are a way to receive real-time notifications about email events, such as when an email is delivered, opened, clicked, bounced, or marked as spam. They work by sending an HTTP POST request to a URL you specify whenever a specific event occurs in Xeams. This allows you to monitor your email campaigns and respond to events instantly, rather than constantly checking for updates through traditional APIs like IMAP or POP3.

How Event Webhooks Work?

Configuration

To configure a webhook in Xeams, go to Home > Plugins > Event Webhooks. The following table defines every field on this page:

Friendly Name Any arbitrary value that is used to identify this webhook
Post URL The URL endpoint that is called when an event occurs. Please refer to the section below for more details on creating this endpoint.
Payload Type This can be either JSON, XML, or Form-Data. Further explanation is provided below.

Events

Since Xeams can handle both inbound and outbound emails, trigger events are generated in both directions. For example, many services that only process outbound emails cannot create an event for a replied email because replies to the original email never go through their server. Xeams supports the following events:

  • Failed Delivery - When Xeams is unable to deliver an email. Initially, many emails will sit in the outbound queue until their expiration time has elapsed. This alert is sent after an email expires.
  • Non-Delivery Report (NDR) - Although this is similar to a Failed Delivery, there is a subtle yet essential difference between the two. A failed delivery occurs when Xeams is unable to deliver the message to the receiving server, due to the server being unresponsive or perhaps not accepting the recipient of the email. An NDR occurs when the receiving server accepts the message from Xeams but generates a non-delivery report at a later time.
  • Delivered - Messages that are delivered successfully. Note that a delivered message can still generate an NDR.
  • Replies - Occurs when Xeams encounters a reply to a previously sent message.
  • Auto Replies - These are similar to Replies you see above, but the message is auto-generated, such as an out-of-office reply.
  • Received - This event is triggered when the system receives an email. This can be either an inbound or an outbound email. This is the only event containing the entire email message in the webhook's body.
  • Email Campaign - rest of the events are applicable when using the Email Campaign plugin
    • Viewed - This event is raised when a recipient of the campaign views the message.
    • Clicked - Occurs when the recipient clicks on a hyperlink within the email.
    • Unsubscribed - Occurs when a recipient unsubscribes from your mailing list.


Creating URL Endpoints

A URL endpoint can be created on any web server, provided it can be reached from the machine where Xeams is running. Since most instances of Xeams run within your network, these URLs can be used to access web servers on your LAN, eliminating the need for any firewall configuration.

You can use any web server or programming language to implement this endpoint.

Message Payload

Xeams supports multiple types of payloads:

  1. JSON - Content-type: application/json; charset=utf-8
  2. XML - Content-type: text/xml; charset=utf-8
  3. Web Form Data - Content-Type: application/x-www-form-urlencoded; charset=utf-8

Regardless of the type of payload you choose, the data remains the same. It contains the following fields:

  • body - Textual body
  • cc - CC value in the email header
  • dateReceived - A 64-bit long integer containing a date in EPOCH time in milliseconds.
  • envelopeMailFrom - MAIL FROM value from the SMTP envelope.
  • envelopeRcptTo - RCPT TO value from the SMTP envelope.
  • eventType - This can be one of the following values:
    • AutoReplied
    • Clicked
    • Delivered
    • Failed
    • NDR
    • Received
    • Replied
    • Unsubscribed
    • Viewed
    • TestURL
  • from - The FROM header value in the message
  • headers - Complete set of headers. This value is encoded in BASE64
  • ipAddress - IP Address of the sender
  • mimeBody - Email body, encoded in BASE64 and corresponds to a complete email message in RFC2822 format. This is only included when the eventType is Received
  • msgType - This can be one of the following values:
    • G - Good Message
    • S - Spam Message
    • P - Possible Spam
  • subject - Subject of the email
  • to - The TO value in the email header.

Sample Payload

NDR event in JSON

{
  "cc": "jane.doe@example.com",
  "envelopeRcptTo": "john.doe@example.com",
  "headers": "U3ViamVjdDogVGVzdGluZyAxMjMNCkZyb206IGphbmVAbXljb3JwLmNvbQ0KVG86IGpvaG4uZG9lQGV4YW1wbGUuY29tDQo=",
  "msgType": "G",
  "envelopeMailFrom": "jane@mycorp.com",
  "subject": "Testing 123",
  "ipAddress": "10.11.12.13",
  "eventType": "NDR",
  "mimeBody": "",
  "body": "This is a sample body of the message.",
  "dateReceived": "1752317412578",
  "from": "jane@mycorp.com",
  "to": "john.doe@example.com"
}

Note: The mimeBody is blank in every event but Received.

Received event in JSON

{
  "cc": "jane.doe@example.com",
  "envelopeRcptTo": "john.doe@example.com",
  "headers": "U3ViamVjdDogVGVzdGluZyAxMjMNCkZyb206IGphbmVAbXljb3JwLmNvbQ0KVG86IGpvaG4uZG9lQGV4YW1wbGUuY29tDQo=",
  "msgType": "G",
  "envelopeMailFrom": "jane@mycorp.com",
  "subject": "Testing 123",
  "ipAddress": "10.11.12.13",
  "eventType": "Received",
  "mimeBody": "U3ViamVjdDogVGVzdGluZyAxMjMNCkZyb206IGphbmVAbXljb3JwLmNvbQ0KVG86IGpvaG4uZG9lQGV4YW1wbGUuY29tDQoNClRoaXMgaXMgYSBzYW1wbGUgYm9keSBvZiB0aGUgbWVzc2FnZS4=",
  "body": "This is a sample body of the message.",
  "dateReceived": "1752317412578",
  "from": "jane@mycorp.com",
  "to": "john.doe@example.com"
}

Received event in XML 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<WebEvent>
    <body>This is a sample body of the message.</body>
    <cc>jane.doe@example.com</cc>
    <dateReceived>1752317844630</dateReceived>
    <envelopeMailFrom>jane@mycorp.com</envelopeMailFrom>
    <envelopeRcptTo>john.doe@example.com</envelopeRcptTo>
    <eventType>Received</eventType>
    <from>jane@mycorp.com</from>
    <headers>U3ViamVjdDogVGVzdGluZyAxMjMNCkZyb206IGphbmVAbXljb3JwLmNvbQ0KVG86IGpvaG4uZG9lQGV4YW1wbGUuY29tDQo=</headers>
    <ipAddress>10.11.12.13</ipAddress>
    <mimeBody>U3ViamVjdDogVGVzdGluZyAxMjMNCkZyb206IGphbmVAbXljb3JwLmNvbQ0KVG86IGpvaG4uZG9lQGV4YW1wbGUuY29tDQoNClRoaXMgaXMgYSBzYW1wbGUgYm9keSBvZiB0aGUgbWVzc2FnZS4=</mimeBody>
    <msgType>G</msgType>
    <subject>Testing 123</subject>
    <to>john.doe@example.com</to>
</WebEvent>