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.
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:
timestamp and token values.signature value.Parameters common to all webhook posts:
| Parameter | Type | Description |
|---|---|---|
| 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:
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"
}