Webhooks in a Mail Agent

What is a Webhook?

Webhooks are user-defined HTTP call backs that are triggered by an event. Webhooks are used to relay the data about email activity (like bounces) and recipient activity (like opens and clicks) to your application. The Webhook URL has to be configured in TransMail by the application developer to receive the event (bounce, click, open) data. TransMail allows you to preview your webhook data within a Mail Agent and test it.  

Types of Webhooks

We can classify webhooks under 3 types:

Bounce Tracking Webhook

You will need bounce information about your transactional emails. There are multiple reasons for your emails to bounce. For example, if your recipient's mailbox is full, your email will bounce temporarily. Such temporary bounces are called as soft bounces. If the bounce is permanent, due to an invalid recipient email address, it is called a hard bounce.

Standard Reported Data for Bounce Webhook

  • event name - the type of event. This will be either hard bounce or soft bounce.
  • email info - This provides the details of the bounced email like:
    • email reference - used to trace the email.
    • subject - Subject of the bounced email.
    • bounce address - the recipient email address and name for which the bounce occurred.
    • to - The email address to which the bounce details are to be sent. You can add any number of "to" addresses here.
    • processed time - timestamp of when the email was sent.
  • event data - this field provides the reason for the bounce, time of bounce, and the diagnostic message.
  • request id - this is the id provided when our send mail API is called.
  • mailagent_key - the unique identifier of the Mail Agent.
  • webhook_request_id - This is the unique id for a specific webhook transaction.

Open Tracking Webhook

Another important information you want to know about your transactional emails is the email open rate. TransMail relays the email-open information to your application via the Open webhook. This event is triggered the first time the recipient opens the email. Even if the recipient opens the email multiple times only the details of the first instance are stored and transmitted by TransMail.

Standard Reported Data for Open tracking webhook

  • Event name - the type of event. The event tracked here is email opens.
  • email info - This provides the details of the bounced email like:
    • email reference - used to trace the email
    • subject - Subject of the bounced email
    • bounce address - the recipient email address and name for which the bounce occurred.
    • to - The email address to which the bounce details are to be sent. You can add any number of "to" addresses here.
    • processed time - timestamp of when the email was sent.
  • event data - this field provides the details of the recipient email client service name and version, time of email open, IP location of the recipient, zip code, country code, city, latitude, country name, IP address, time zone, region, longitude, browser name and version, operating system name and version, time, device and name.
  • request id - this is the id provided when our send mail API is called.
  • mailagent_key - the unique identifier of the Mail Agent.
  • webhook_request_id - This is the unique id for a specific webhook transaction.

Click Tracking Webhook

Sometimes, your transactional emails will have clickable links as a part of its html body. You will want to know, how many of your email recipients actually clicked on these links. TransMail relays unique clicks information across all the tracked links in the email. This information helps you monitor the performance of your transactional emails.

If a recipient clicks on the same tracked link multiple times, only the unique clicks are recorded and relayed by TransMail to the application via the webhook URL.

Standard Reported Data for Click tracking webhook

  • Event name - the type of event. The event tracked here is the unique clicks on the tracked links.
  • email info - This provides the details of the bounced email like:
    • email reference - used to trace the email.
    • subject - Subject of the bounced email.
    • bounce address - the recipient email address and name for which the bounce occurred.
    • to - The email address to which the bounce details are to be sent. You can add any number of "to" addresses here.
    • processed time - timestamp of when the email was sent.
  • event data - this field provides the details of the recipient email client service name and version, time of email open, IP location of the recipient, zip code, country code, city, latitude, country name, ip address, time zone, region, longitude, browser name and version, operating system name and version, time, device and name.
  • request id - this is the id provided when our send mail API is called.
  • mailagent_key - the unique identifier of the Mail Agent.
  • webhook_request_id - This is the unique id for a specific webhook transaction.

Configure your Webhook URL

  1. From the left panel, select Mail Agents and select a Mail Agent for which you want to add webhooks.
  2. Navigate to Webhooks tab.
  3. Click on Configure Webhook.

  1. Add Webhooks box will appear. Here you can add your webhook and test it.
  2. Enter Webhook URLDescription and choose the notifications (from Soft bouncedHard bouncedOpen and Click) for which you want the webhook to relay this data to your application.

  1. Click on Save after the required details are filled.
  2. Webhook is configured successfully.
  3. If you wish to add more webhooks to your TransMail Mail Agent, then click on Add Webhook button on the right-hand side.

  1. You can follow the same steps to add multiple webhooks.

Edit your Webhook URL

  1. From the left panel, select Mail Agents and select a Mail Agent for which you want to add webhooks.
  2. Navigate to Webhooks tab. Here the list of webhooks configured for your Mail Agent will be listed.
  3. Hover over Webhook to view Edit webhook icon.
  4. Click on Edit webhook to open the Add Webhooks box.

  1. You can edit Webhook URLDescription and select/ de-select from these notifications - Soft bouncedHard bouncedOpen and Click.

  1. Click on Save to apply the changes to your Webhook URL.

Test your Webhook URL

  1. From the left panel, select Mail Agents and select a Mail Agento which you want to add webhooks.
  2. Navigate to Webhooks tab. You will see the Webhooks page where you can view the list of webhooks for that Mail Agent.
  3. Locate Webhook URL you want to test and hover your cursor over it.
  4. Click on send test webhook icon indicated by a flight symbol. 

  1. You can check the reception of your webhook data.

Authenticate your Webhook URL

Webhook URL should be made public for TransMail to send data. Due to its public exposure, the URL is under threat. There is a possibility for hackers to manipulate the URL data by posting irrelevant information to the public webhook URL.

In order to protect the webhook URL, TransMail provides an authentication key. Authentication protects your Webhook URL from irrelevant clicks. You can add an Authentication Key as a part of the data sent to the Webhook URL. Your application can then use this Authentication Key to validate the incoming webhook data.

  1. From the left panel, select Mail Agents and select the Mail Agent to which you want to add webhooks.
  2. Navigate to Webhooks tab. You will see the Webhooks page where you can view the list of webhooks for that Mail Agent.
  3. Click on Authentication Key on the top right corner.

  1. Enter Authentication Key and click on Set.
  2. Use Authentication Key to validate the webhook data sent to your application.

Delete your Webhook URL

You can delete a Webhook URL, however, you will have to add it again to re-use it.

  1. From the left panel, select Mail Agents and select the Mail Agent to which you want to add webhooks.
  2. Navigate to Webhooks tab. You will see the Webhooks page where you can view the list of webhooks for that Mail Agent.
  3. Locate the webhook you want to delete and hover your cursor over it.
  4. Click on the delete icon on the right corner.

  1. Click on OK to confirm the webhook deletion.

Note:

Before you get started it is important to know that TransMail is for sending transactional emails like welcome emailers, password resets emails, OTPs. We do not support sending of bulk emails or promotional emails like newsletters or marketing campaign emails. If you ar e looking for a bulk email provider, check out Zoho Campaigns.