Each individually configured webhook endpoint can be customized with regards to which Events are received.
SocketLabs offers the following Event Webhooks:
- Queued Events (Accepted)
- Deferral Events (Delayed)
- Sent Events (Delivered)
- Failed Events (Bounced)
- Complaint Events (Feedback Loops)
- Tracking Events (Opens, Clicks, and Unsubscribes)
Descriptions and Examples
Queued Events
A message has been accepted (queued) by SocketLabs for processing. The outcome of the message has not yet been determined. These events are generated by the MTAs (Mail Transfer Agent) that perform direct-to-MX final message delivery and may not occur instantly upon the completion of an SMTP relay submission or Injection API call.
{
"Type": "Queued",
"DateTime": "2023-06-12T10:04:56.3694682Z",
"SubaccountId": 12345,
"ServerId": 12345,
"SecretKey": "ABC123",
"Address": "example@example.com",
"FromAddress": "example@example.gov",
"Subject": "Welcome to Socketlabs - Verify Your Email Address",
"MessageSize": 22775,
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Deferral Events
A message has been delayed in delivery as the result of a transient error in the delivery process. The rejection indicates a temporary issue, and the message will be held in queue and retried for delivery later. A Failed Event Webhook is NOT generated yet because the outcome of the message has yet to be determined. Messages may also remain in queue without a Deferral Event being generated for a variety of reasons such as SocketLabs optimizing delivery rates in response to a large influx of messages.
{
"Type": "Deferred",
"DateTime": "2023-06-12T13:34:56.6194215Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@example.com",
"SecretKey": "ABC123",
"DeferralCode": 4999,
"Reason": "450 4.3.2 Service currently unavailable",
"ServerId": 12345,
"FromAddress": "example@example.gov",
"SubaccountId": 0,
"IpPoolId": 12345,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Sent Events
A message has been accepted for delivery by the receiving servers for the recipient. SocketLabs has received a 250 response after the completed transmission of the message.
{
"Type": "Delivered",
"DateTime": "2023-06-09T13:55:53.7627979Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@example.com",
"SecretKey": "ABC123",
"RemoteMta": "mxa-0054b702.gslb.pphosted.com",
"ServerId": 12345,
"Response": "250 2.0.0 3r2a75y69g-1 Message accepted for delivery\r\n",
"LocalIp": "142.0.0.0",
"FromAddress": "example@example.com",
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Failed Events
When a message is suppressed (not attempted for delivery), rejected by the receiving mail system, expires from the message delivery queue, or is asynchronously bounced, then a Failed event will be generated and posted to your endpoint.
{
"Type": "Failed",
"DateTime": "2023-06-12T13:34:56.6194215Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@gmail.com",
"SecretKey": "ABC123",
"FailureCode": 2001,
"Reason": "550-5.1.1 The email account that you tried to reach does not exist. Please try{CRLF}550-5.1.1 double-checking the recipient's email address for typos or{CRLF}550-5.1.1 unnecessary spaces. Learn more at{CRLF}550 5.1.1 https://support.google.com/mail/?p=NoSuchUser l2-20020a9d4c02000000b006b27ab0bd0bsi4007169otf.237 - gsmtp In response to the RCPT TO command.",
"RemoteMta": "gmail-smtp-in.l.google.com",
"ServerId": 12345,
"FailureType": "Permanent",
"FromAddress": "example@example.gov",
"BounceStatus": "",
"DiagnosticCode": "",
"SubaccountId": 0,
"IpPoolId": 12345,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Suppressed Failed Event
{
"Type": "Failed",
"DateTime": "2023-06-11T20:52:06.1706801Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@example.com",
"SecretKey": "ABC123",
"FailureCode": 9999,
"Reason": "",
"RemoteMta": "",
"ServerId": 12345,
"FailureType": "Suppressed",
"FromAddress": "example@example.com",
"BounceStatus": "",
"DiagnosticCode": "",
"SubaccountId": 0,
"IpPoolId": 12345,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Synchronous Mailbox Full Failure Event
{
"Type": "Failed",
"DateTime": "2023-06-10T07:20:13.9013211Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@gmail.com",
"SecretKey": "ABC123",
"FailureCode": 3001,
"Reason": "452-4.2.2 The email account that you tried to reach is over quota.
Please direct the recipient to http://{x}123 - gsmtp In response to the RCPT TO
command.",
"RemoteMta": "gmail-smtp-in.l.google.com",
"FailureType": "Temporary",
"FromAddress": "example@gmail.com",
"SubaccountId": 12345,
"IpPoolId": 12345,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Asynchronous Invalid Address Bounce Event
{
"Type": "Failed",
"DateTime": "2023-06-11T11:11:29.6919005Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@example.com",
"SecretKey": "ABC123",
"BounceStatus": "5.1.10",
"DiagnosticCode": "550 5.1.10 RESOLVER.ADR.RecipientNotFound; Recipient
example@example.com not found by SMTP address lookup",
"FailureCode": "2001",
"FailureType": "1",
"Reason": "550 5.1.10 RESOLVER.ADR.RecipientNotFound; Recipient test@example.com
not found by SMTP address lookup",
"ServerId": 12345,
"FromAddress": "example@socketlabs.com",
"RemoteMta": "",
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Asynchronous Spam Policy Bounce Event
{
"Type": "Failed",
"DateTime": "2023-06-09T18:54:08.953011Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@example.com",
"SecretKey": "ABC123",
"BounceStatus": "5.7.1",
"DiagnosticCode": "550 5.7.1 TRANSPORT.RULES.RejectMessage; the message was rejected
by organization policy",
"FailureCode": "1004",
"FailureType": "0",
"Reason": "550 5.7.1 TRANSPORT.RULES.RejectMessage; the message was rejected by
organization policy",
"ServerId": 12345,
"FromAddress": "",
"RemoteMta": "",
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Asynchronous Out of Office Bounce Event
{
"Type": "Failed",
"DateTime": "2023-06-10T20:08:40.7452689Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@example.org",
"SecretKey": "ABC123",
"BounceStatus": "",
"DiagnosticCode": "",
"FailureCode": "5001",
"FailureType": "0",
"Reason": "Thank you for your email. I am currently out of the office and
will return\r\non Monday. I will be checking email periodically.\r\n\r\nHave
a great weekend.\r\n\r\n\r\n\r\n-- \r\n\r\n\r\n*Thanks,*\r\n\r\n\r\n*Example*\r\n\r\
n*Service Manager*\r\n\r\n*Office of Technology*\r\n\r\n*Example School District*\r\
n\r\n*555-555-5555*\r\n\r\n-- \r\nDISCLAIMER: The Example School District does not
discriminate \r\non the basis of race, color, religion, age, gender, disability, nati
onal \r\norigin, military status, genetic information, or any other basis prohibited
\r\nby law. ",
"ServerId": 12345,
"FromAddress": "example@example.com",
"RemoteMta": "",
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Complaint Events
Complaints, or Feedback Loops (FBLs) are asynchronous messages from a mailbox provider returning data about a message. This is usually based on actions of a user such as clicking spam or junk in the mail client. Mailbox providers offer this resource to help reduce unwanted mail from being sent to their users. Not all mailbox providers support feedback loops, and some have strict acceptance criteria to enroll in their offerings. For more information about FBLs please see our knowledge base article here: Feedback
{
"Type": "Complaint",
"DateTime": "2023-06-10T23:56:23.7189637Z",
"MailingId": "SL5233439-5474023",
"MessageId": "129957964",
"Address": "example@comcast.net",
"SecretKey": "ABC123",
"FblType": "abuse",
"UserAgent": "ReturnPathFBL/2.0",
"From": "feedbackloop@comcastfbl.senderscore.net",
"To": "fbl@email-od.com",
"Length": "35117",
"ServerId": 12345
}
Tracking Events: Open
{
"Type": "Tracking",
"DateTime": "2023-06-10T13:07:19.9551935Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@gmail.com",
"SecretKey": "ABC123",
"TrackingType": 1,
"Url": null,
"ServerId": 12345,
"ClientIp": "66.1.2.3",
"UserAgent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
"Tag": “”,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Tracking Event: Click
{
"Type": "Tracking",
"DateTime": "2023-06-09T13:06:29.8791169Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@gmail.com",
"SecretKey": "ABC123",
"TrackingType": 0,
"Url": "https://example.com/links/url?idx=ABC&l=english&rk=39C4ED6",
"ServerId": 12345,
"ClientIp": "192.168.212.27",
"UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36",
"Tag": "Header-Logo",
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Tracking Event: Unsubscribe
{
"Type": "Tracking",
"DateTime": "2023-06-12T05:02:53.074689Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@gmail.com",
"SecretKey": "ABC123",
"TrackingType": 2,
"Url": null,
"ServerId": 12345,
"SubaccountId": 12345,
"ClientIp": "10.10.93.233",
"UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36",
"Tag": null,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
Tracking Event: Mail-To List-Unsubscribe
{
"Type": "Tracking",
"DateTime": "2023-06-12T13:53:52.4780484Z",
"MailingId": "SL5233439-5474023",
"MessageId": "1209957964",
"Address": "example@gmail.com",
"SecretKey": "ABC123",
"TrackingType": 2,
"Url": null,
"ServerId": 12345,
"SubaccountId": 12345,
"ClientIp": "142.0.179.30",
"UserAgent": "Mozilla/5.0 (compatible; SocketLabs Hurricane Server +http://www.socketlabs.com)",
"Tag": null,
"Data": {
"Meta": [
{
"Key": "SnowflakeUserID",
"Value": "5227581"
},
{
"Key": "DynamicImagesUsed",
"Value": "Hero-BL741"
},
{
"Key": "UserRegion",
"Value": "US-West"
},
{
"Key": "PhysicalLocation",
"Value": "San Diego, CA"
}
],
"Tags": [
"Transactional",
"Order Confirmation"
]
}
}
For a description of the data fields see Event Webhooks: Data Attributes