Webhooks

Loading the support system

loading...
Support Home > API > Webhooks

 

Event webhooks will notify a URL of your choosing via HTTP POST with information about recipient actions as they occur. You can use this data to track unsubscribes, bounces, opens, and clicks. You can read more about the POSTed data below.

Webhook responses will be handled with one of three patterns:

  • HTTP 200 responses will be considered successful; no retries will occur.
  • HTTP 406 responses will be considered a permanent reject; no retries will occur.
  • All other HTTP responses will be considered a temporary failure and will be retired over a period of 24 hours.


Securing Webhooks

To ensure the authenticity of webhook requests, they are signed, and the signature is posted along with other webhook parameters:

Parameter Type Description
timestamp int Unix timestamp, i.e., a number of seconds passed since Jan. 1, 1970.
token string Random string with a length of 50.
signature string Hexadecimal string generated by HMAC algorithm.

 

To verify the authenticity of the message, you must do the following:

  • Concatenate the timestamp and token values.
  • Encode the resulting string with the HMAC algorithm using your account id as a key and SHA256 digest mode.
  • Compare the resulting hexdigest to the signature value.

Webhook Parameters

Parameters common to all webhook posts:

Parameter Type Description
email string Recipient email address
timestamp int Unix timestamp, i.e. seconds passed since Jan. 1, 1970
eventType string One of 'Open', 'Click', 'Bounce', or 'Optout'
recipientId int The id for the recipient
xCampaign string Any x-rm-Campaign header included 


Parameters common to all Open, Click, and Optout webhook posts:

Parameters labeled with RM are only available to ReachMail campaigns.  EasySMTP campaigns will not supply those values.

 

Parameter Type Description
ipAddress string The IP address originating the event.
userAgent string The UserAgent string of the client that originated the event.
eventId string The id for the event.
listId RM string The id for the list used in the mailing.
malingId RM string The id for the mailing from which the event originates.
listName RM string Name of the list recipient was on.
mailingName RM string Name of the message this event was responding to.
location GeoLocation Geolocation data for the event.
device Device Device data for the event.

 

Optout messages will not have geolocation or device data if they were generated by abuse feedback reports that were received over email channels.

 

Parameters common to GeoLocation models

Parameter Type Description
city string City name
countryCode string Two character country code
region string IP region

 

Parameters common to Device models

Parameter Type Description
clientName string The name of the client derived from the HTTP User-Agent header
clientOs string The name of the client OS derived from the HTTP User-Agent header
clientType string The application type of the client
deviceType string The client device type, e.g. mobile, desktop

 

Parameters common to all Bounce webhook POSTs:

Parameters labeled with RM are only available to ReachMail campaigns.  EasySMTP campaigns will not supply those values.

Parameter Type Description
bounceCode string The evaluated bounce code for the recipient.
reason string An interpreted reason for the bounce
smtpStatus string The original SMTP status returned by the remote server
smtpDiagnostic string The original SMTP diagnostic returned by the remote host
listId RM string The id for the list used in the mailing.
malingId RM string The id for the mailing from which the event originates.
listName RM string Name of the list recipient was on.
mailingName RM string Name of the message this event was responding to.

Interpreted bounce reasons:

  • AutoReply
  • GeneralBounce
  • ChallengeResponse
  • HardBounce
  • MailBlock
  • NonBounce
  • SoftBounce
  • TransientBounce
  • Unsubscribe
  • Complaint

Example Request Bodies

All webhook bodies are sent as JSON.

Example open, click, or opt-out body.

{
    timestamp: 1552927113,
    token: "eec6leeraghooNohk8eu4ohshei5IY2biek6aepeixi7maf5be",
    signature: "74e90deabaea9693ca34ea0c59a5d893c2952b3fab82782fce599f9dfb39e494",
    email: "user@domain.com",
    eventType: "Open",
    recipientId: "a8f3ff76-f915-4c8e-a67f-bf3a2179c6a5",
    xCampaign: "",
    ipAddress: "4.3.2.1",
    userAgent: "Mozilla 5.0",
    eventId: "52e9b845-bb5a-45bb-b8a7-a4946603058b",
    listId: "4f96c5ac-128c-4824-8ffe-8dfa43e3d6eb",
    listName: "My Customers",
    mailingId: "76fb82a5-42a8-4f6d-bf00-d05bac5e9a7d",
    mailingName: "Company Newsletter",
    location: {
       city: "Chicago",
       countryCode: "US",
       region: "IL",
    },
    device: {
        clientName: "Outlook",
        clientOS: "Windows",
        clientType: "Outlook",
        deviceType: "Desktop"
    }
}

Example bounce body.

{
   timestamp: 1552927113,
   token: "eec6leeraghooNohk8eu4ohshei5IY2biek6aepeixi7maf5be",
   signature: "74e90deabaea9693ca34ea0c59a5d893c2952b3fab82782fce599f9dfb39e494",
   email: "user@domain.com",
   eventType: "Open",
   recipientId: "a8f3ff76-f915-4c8e-a67f-bf3a2179c6a5",
   listId: "4f96c5ac-128c-4824-8ffe-8dfa43e3d6eb",
   listName: "My Customers",
   mailingId: "76fb82a5-42a8-4f6d-bf00-d05bac5e9a7d",
   mailingName: "Company Newsletter",
   bounceCode: "HB"
   reason: "HardBounce",
   smtpStatus: "550",
   smtpDiagnostic: "550 invalid user"
}