Event Notifications

Our platform provides webhook support, allowing clients to receive real-time event notifications for email engagements such as Delivered, Opened, Clicked, Unsubscribe, and Spam events. This feature enables seamless tracking and response handling based on user interactions for emails sent through our Trigger APIs.

Webhook for Event Notifications of Trigger-Based APIs

This service is available for emails sent via the Trigger APIs, specifically Fire Trigger v2, Dynamic Template Trigger v2, and Attachment Trigger v2. Please ensure you are using Version 2 of these APIs to receive a unique messageID in the API response.

cmercury will send POST requests to your designated webhook URL, including the messageID that matches the one provided in the Trigger API response. This feature enables you to map each event notification directly back to its corresponding API request in your application, providing seamless tracking and data consistency.

Webhook URL Setup for Event Notifications

Clients can configure webhook URLs to receive event notifications directly from our app. We offer two options for webhook URL configuration:

Account-Wide Webhook URL

Set a common webhook URL for your entire client account. This URL will receive notifications for all engagement events generated by any Trigger API request within the account. This is a straightforward setup, ideal for clients wanting a single notification endpoint for all interactions.

Trigger ID-Specific Webhook URL

For more granular control, clients can set up webhook URLs based on individual Trigger IDs. Each Trigger ID serves a distinct purpose within the Trigger API and can be tied to a unique webhook URL. Notifications for events related only to that specific Trigger ID will be sent to its designated webhook URL. This setup is ideal for clients needing separate event streams, such as development vs. production environments or segmented campaigns.

Setting Up Webhook URLs

To add webhook URLs:

• Contact your account manager or in [email protected] to register a new webhook URL.
• Specify whether the webhook should be Account-Wide or Trigger ID-Specific.
• For Trigger ID-Specific URLs, provide the desired Trigger ID for each URL.
• Clients who use Zapier integration will be auto-configured to receive account-wide events on Zapier platform.

Example Webhook URL Configuration

Trigger ID	Webhook URL	Purpose
Account-Wide	https://www.yourdomain.com/account_webhook	Receives all account-wide events
1457	https://www.yourdomain.com/specific_webhook_1457	Only receives events for Trigger ID 1457
1414	https://www.yourdomain.com/specific_webhook_1414	Only receives events for Trigger ID 1414

In this configuration:

• The Account-Wide Webhook URL receives all events across the account except for the trigger ID specified in trigger specific webhook.
• Each Trigger ID-Specific Webhook URL receives notifications solely for its assigned Trigger ID.

Sample Event Notifications

Samples of event notification that will be send to the webhook is given below.

DELIVERED

An email gets delivered to the recipient

JSON

{  
    "messageId": "20241018014218812sdasfsaq9BdfgdPi",  
    "event": "DELIVERED",  
    "timestamp": "2024-10-18T04:50:27+00:00",  
    "email": "[email protected]",  
    "message": "relayed",  
    "version": "1.0"  
}

BOUNCE

Process the bounce event and remove the email address from all future campaigns to protect your domain's reputation and to avoid account lockout.

Hard Bounce A permanent failure in email delivery when the email address is wrong or similar situations. More.

JSON

{  
  "messageId": "20241018014218812sdasfsaq9BdfgdPi",  
  "event": "BOUNCE",  
  "timestamp": "2024-09-27T10:10:59+00:00",  
  "email": "[email protected]",  
  "message": "failed",  
  "version": "1.0"  
}

Soft Bounce A temporary failure in email delivery in situations like the recipient's mailbox is full or is temporarily out of reach More. The email addresses do not need to be removed from mailing activities at the first instance of this event. However, keeping a maximum attempt limit on these email addresses and then removing them from the email list is a good practice.

JSON

{  
  "messageId": "20241018014218812sdasfsaq9BdfgdPi",  
  "event": "SOFTBOUNCE",  
  "timestamp": "2024-09-27T10:10:59+00:00",  
  "email": "[email protected]",  
  "message": "SoftBounced",  
  "version": "1.0"  
}

OPEN

An email is opened by the recipient.

JSON

{  
    "messageId": "20241018014218812sdasfsaq9BdfgdPi",  
    "event": "OPEN",  
    "timestamp": "2024-10-18T04:54:43+00:00",  
    "email": "[email protected]",  
    "message": "Opened",  
    "version": "1.0       "  
}

CLICK

The click event will have an additional Key named ClickedLink to identify the link clicked by the user.

JSON

{
"messageId": "20241018014218812sdasfsaq9BdfgdPi",
"event": "CLICK",
"timestamp": "2024-10-18T07:09:26+00:00",
"email": "[email protected]",
"message": "Clicked",
"version": "1.0       ",
"ClickedLink": "https:\/\/www.domain.org\/index.html?q=param"
}

UNSUBSCRIBE

The unsubscribe event might not have the messageID key. Hence process the event using email key and remove the email address from future mail activities for safeguarding your domain's reputation.

JSON

{      
    "event": "UNSUBSCRIBE",  
    "timestamp": "2024-10-18T04:54:43+00:00",  
    "email": "[email protected]",  
    "message": "Unsubscribed",  
    "version": "1.0       "  
}

SPAM

The spam event will not have the messageID key. Hence process the event using email key and remove the email address from future mail activities for safeguarding your domain's reputation.

JSON

{      
    "event": "SPAM",  
    "timestamp": "2024-10-18T04:54:43+00:00",  
    "email": "[email protected]",  
    "message": "SpamReported",  
    "version": "1.0       "  
}

Contact [email protected] for any assistance.