Overview
Integrate smarter with webhooks. We will send real-time notifications whenever an event occurs in Enginemailer so you can keep your app in sync with us.
Once you create a webhook for an event, and provide a callback URL, Enginemailer will automatically post JSON data containing necessary details every time the event occurs. It is up to you to perform a certain action when it receives a corresponding notification.
Enginemailer provides the option to set up a webhook for specific events and for specific verified sending domains so you have more control!
Event Types
Any change that happens in the system is captured as an event. These are the events generated by Enginemailer:
|
Event |
Description |
|
Delivery |
Email successfully delivered to the destination domain. |
|
Bounce |
Hard bounce e-mail is permanently bounced because the address is invalid. Soft bounce e-mail is recognized by the recipient's mail server but is returned to the sender because the recipient's mailbox is full, the mail server is temporarily unavailable, or the recipient no longer has an e-mail account at that address |
|
Open |
A recipient has opened the HTML message. |
|
Click |
A Recipient clicked on a link within the message. |
|
Unsubscribe |
A recipient unsubscribed from the mailing list. |
|
Spam-Complaint |
A recipient reports unwanted emails to their email provider. |
Handling Webhooks
Enginemailer needs to receive a status code 200 or OK reply from the configured URL to confirm that it has successfully delivered the notification via HTTP POST. Enginemailer treats status codes other than 200 or OK as failed and will not retry.
Configuring Webhooks
To configure your webhooks, go to Domains › {domain.com} › Webhooks.
Enginemailer allows only verified sending domains to setup webhook. You will not see the option in the non-verified domain.
If you have not added a webhook, you can enter the URL based on the event. Click Test URL to check if the URL provided is working. The response status is displayed on the page. If successful, you may proceed to save the URLs. Don’t forget to enable the webhook, otherwise, we will not send to the URL.
When you create your webhook, we recommend that you use HTTPS for your webhook URL. You may also randomly generate a key for your website and add it along with your webhook URL.
Removing Webhooks
To remove a configured webhook, go to Domains › {domain.com} › Webhooks. Remove the URL and leave it blank.
Debugging Webhooks
You may use Beeceptor to test what data you are going to get from us or you may just use any other developer tools available out there. By using Beeceptor, you can generate a URL to act as a webhook and test that URL in our webhook entry. Then, check in Beeceptor for the result.
Event POST Example
|
Event |
JSON Data |
|
Delivery (Transactional Email) |
{
|
|
Delivery (Marketing Email) |
{
|
|
Delivery (Autoresponder Email) |
{
|
|
Bounce (Transactional Email) |
|
|
Bounce (Marketing Email) |
{
|
|
Bounce (Autoresponder Email) |
{
|
|
Open (Transactional Email) |
|
|
Open (Marketing Email) |
{
|
|
Open (Autoresponder Email) |
{
|
|
Click (Transactional Email) |
|
|
Click (Marketing Email) |
{
|
|
Click (Autoresponder Email) |
{
|
|
Unsubscribe (Marketing Email) |
{
|
|
Unsubscribe (Autoresponder Email) |
|
|
Spam (Transactional Email) |
|
|
Spam (Marketing Email) |
|
|
Spam (Autoresponder Email) |
|
Example of C# code to receive the JSON Data
[AllowAnonymous]
[HttpPost]
public ActionResult EMWebHook(string key)
{
if (key != "lalalala")
{
return Content("Webhook key is not correct");
}
var req = Request.InputStream;
req.Seek(0, SeekOrigin.Begin);
string jsonstr = new StreamReader(req).ReadToEnd();
if (jsonstr == "")
return Content("Content is empty");
else
{
var obj = JObject.Parse(jsonstr);
var eventType = (string)obj.SelectToken("event");
var txid = (string)obj.SelectToken("details.txid");
var email = (string)obj.SelectToken("details.email");
if (eventType == "opened")
{
var opendate = (string)obj.SelectToken("details.opendate");
var ip_address = (string)obj.SelectToken("details.ip_address");
var devicecategory = (string)obj.SelectToken("details.devicecategory");
var devicestring = (string)obj.SelectToken("details.devicestring");
var country = (string)obj.SelectToken("details.country");
//process opened event
}
else if (eventType == "clicked")
{
var clickdate = (string)obj.SelectToken("details.clickdate");
var url = (string)obj.SelectToken("details.url");
var ip_address = (string)obj.SelectToken("details.ip_address");
var devicecategory = (string)obj.SelectToken("details.devicecategory");
var devicestring = (string)obj.SelectToken("details.devicestring");
var country = (string)obj.SelectToken("details.country");
//process clicked event
}
else if (eventType == "bounced")
{
var bouncedate = (string)obj.SelectToken("details.bouncedate");
var bouncecode = (string)obj.SelectToken("details.bouncecode");
var bouncereason = (string)obj.SelectToken("details.bouncereason");
//process bounced event
}
else if (eventType == "delivered")
{
var delivereddate = (string)obj.SelectToken("details.deliverydate");
//process delivered event
}
return Content("Content processed");
}
}