Event Webhooks: Data Attributes

Event Webhook posts may have a variety of different data fields.

The data fields that may be included currently included are:

• Type 
• DateTime 
• ServerID
• SubaccountID
• IPPoolID
• SecretKey 
• Address 
• FromAddress 
• Subject 
• MessageSize 
• DeferralCode 
• Response 
• LocalIp 
• Reason 
• BounceStatus 
• DiagnosticCode 
• FailureCode  
• FailureType 
• RemoteMta 
• TrackingType 
• UserAgent 
• ClientIp 
• Url 
• Tag 
• FblType 
• From 
• To 
• Length 
• MailingId 
• MessageId 
• Data 
  • Meta 
  • Tags 

Data Field Availability

^{^ These data fields may not always be present for all events in this category.}

^{* SocketLabs Simple (V1) customers should rely on the ServerID field for identifying the SocketLabs resources associated with a message. SocketLabs Complex (V2) customers should rely on SubaccountID and IPPoolID. However, events for V1 and V2 customers may contain both data fields.}

^{** The Data JSON object (Meta and Tags) will only be present when submitted with messages for delivery. By default not all asynchronous (Failure/Tracking/Complaint events) are not enriched with metadata. Contact your SocketLabs Account Manager to have full event enrichment enabled. Data enrichment for asynchronous events only occurs for messages were processed by SocketLabs within the last 16 days. Webhook events that go through an enrichment process may be delayed in processing while the additional data fields are retrieved.}

Data Field Definitions

Type -> STRING

An identifier for the type of webhook event being processed. Current responses include:  

"Queued", "Deferred", "Delivered", "Failed", "Tracking", or "Complaint" 

DateTime -> STRING

This is a timestamp for the event in ISO 8601 format.

ServerID -> INT

The identification number of the server for which the event is associated. While ServerID is valuable for SocketLabs Simple (V1) customers, this field may be present for Complex (V2) customers.

SubaccountID -> INT

The identification number of the subaccount for which the event is associated. While Subaccount is primarily used by SocketLabs Complex (V2) customers, this field may be present for Simple (V1) customers.

IPPoolID -> INT

The identification number of the IPPool that processed a message. While IPPoolID is primarily used by SocketLabs Complex (V2) customers, this field may be present for Simple (V1) customers.

Address -> STRING

The recipient address of the message. Not to be confused with the “To” data field in complaint events. 

FromAddress -> STRING

The From address of the message. Not to be confused with the “To” data field in complaint events.

Subject -> STRING

The Subject line of the message.  

MailingID -> STRING

An optional identifier that can be added to messages that will persist across all aspects of reporting data. The MailingID is meant to be used to categorize batches or groups of messages. SocketLabs will provide aggregated reporting data across this field. Use of excessive volumes of identifiers (such as a unique ID per message) may cause degraded performance of reporting interfaces. See our knowledge article for more information: Message Tagging with MessageID and MailingID

MessageID -> STRING

An optional identifier that can be added to messages that will persist across all aspects of reporting data. The MessageID is designed to be unique for each message. SocketLabs does not provide aggregated reporting statistics on this field. See our knowledge article for more information: Message Tagging with MessageID and MailingID

MessageSize -> INT

The size of the message including all headers, attachments, and message body. Represented in bytes (b). 

Deferral Code -> INT

This is a BETA field intended to help make deferrals easier to understand to humans and less technical users. Due to this field's BETA status, the results in the deferral code may be inconsistent representations of the root cause of deferral. At this time Deferral Codes and Failure Codes use the same schema, so you can reference the failure codes for a definition of each deferral code.  

Response -> STRING

This is the response from the receiving mail server when the message is accepted and queued for delivery to the recipient. Receiving mail systems often provide additional information and data in the response when accepting a message. For example, while some mail servers issue nothing but “250 OK” as the response, other give each message a unique identifier upon acceptance. An example response with an identifier is:  

250 2.0.0 Ok: queued as 099AF107754327X5AX342 

This ID is useful when diagnosing potential sending issues. You can use the unique identifier your message was given as a query in the logs of the receiving mail server, allowing you to track the message and identify an issue. 

LocalIP -> STRING

This is the IP address that is responsible for the delivery or attempted delivery of a message. This IP address may use a format that is internal to the SocketLabs network, but can be translated easily to the public facing IP address. There will always be a direct alignment between the last two octets of the internal and public IP address. The SocketLabs IP range uses the first two octets of 142.0, so if the IP address provided is 10.50 176.1, than the public facing address that performed delivery will be 142.0.176.1 

Reason -> STRING

This is the reason a message failed. It is usually the response from the receiving mail server when the message is rejected for delivery to the recipient. Receiving mail systems all establish their own logic around these error responses and as such there is an extremely wide variety and inconsistency with this dataset. SocketLabs will use this data along with other aspects of a given failure event to try and assign a Failure Type and Failure Code to help better understand and standardize the reason a message was not delivered.  

This field can also be an error that SocketLabs encountered internally in the delivery process. We will often, but not always, include SMTP response codes related to the failure. Such as adding “453 4.4.0” when logging that we were not able to connect to the receiving mail server. 

"453 4.4.0 Could not connect after trying all mx records. type=mx Message expired after being in queue for 4.00 days." 

For asynchronous bounce messages this field will contain either the parsed DiagnosticCode, or if a DiagnosticCode cannot be identified it will be the first 500 characters of the body of the bounce message. 

The reason field may also have some additional data appended at the end by SocketLabs to highlight important aspects of the failure. This includes when in the SMTP transaction the failure response was issued, or how long the message was in queue prior to failure. For example, this error indicates that the message was in our queues for an extended period prior to being considered a delivery failure: 

"453 4.4.0 Could not connect after trying all mx records. type=mx   Message expired after being in queue for 4.00 days." 

Knowing that a message was rejected in response to the SMTP RCPT TO command increases the likelihood that the recipient is non-existent: 

 "550 5.1.0 The account that you tried to reach does not exist In response to the RCPT TO command.” 

BounceStatus -> STRING

This field is present only in well-formed asynchronous bounce events. This means the message in question will also have a Delivered event already. It is parsed from the body of the asynchronous bounce message. We surface this field because it can be one of the most reliable means from interpreting a cause for failure. Additionally, when a message is returned asynchronously and the response is not bound by the format requirements of the SMTP protocol, this data may be difficult to properly identify.  

DiagnosticCode -> STRING

This field is present only in well-formed asynchronous bounce events. This is the full reason parsed from the bounce message as to the cause of the failure. It will often present similar in nature to a traditional synchronous SMTP error response code. 

FailureType -> STRING

Current responses include: "Permanent", "Temporary", "Suppressed" 

When a message fails to be successfully delivered SocketLabs will categorize the failure into one of three potential types: 

• Temporary failure: The message failed to be delivered and the error does NOT indicate that the recipient address is permanently invalid. SocketLabs will NOT add the recipient address to a suppression list to prevent future delivery attempts. 
• Permanent failure: The message failed to be delivered and SocketLabs believes the error indicates the address will NOT be able to accept future messages. Assuming the Suppression List feature is enabled, the recipient address will be added to prevent future delivery attempts. 
• Suppressed: The message was destined to an address that was previously suppressed, and delivery was not attempted at all. 

FailureCode -> INT

The Failure Code is a 4 digit ID that we provide as a more human friendly interpretation explaining why a message failed to be delivered. These 4 values are based solely upon an analysis of the timing and response provided by the recipient mail server which is available as the Reason and DiagnosticCode data. For a complete list of FailureCodes, see Message Delivery Failure Codes

RemoteMTA -> STRING

This is the MX record for which we were connected when a message was accepted, or failed delivery. This is helpful in identifying the system that received the message for domains that have multiple MX records.  

TrackingType -> INT

Current responses include: 0, 1, 2 

This is how open, click, and unsubscribe events are delineated within the tracking events category: 

• 0: Click 
• 1: Open 
• 2: Unsubscribe

UserAgent -> STRING

The UserAgent that is associated with the Open, Click, Unsubscribe, or Complaint.  

For complaints, the User-Agent identifies the system generating the report as defined in Section 8.8 of RFC5965 https://datatracker.ietf.org/doc/html/rfc5965#section-8.8

ClientIP -> STRING

The IP address that originated the request to SocketLabs for Open, Click, and Unsubscribe events. This may be the user or a proxy agent of the mailbox provider or mail client.  

URL -> STRING

The original link in the body of the message that was clicked. This is the destination of the user after being redirected by the tracking system.  

Tag -> STRING

An optional identifier that can be added to the HTML of a message to provide additional data about a link. This is particularly useful when the exact same link is present multiple times in a message as it allows you to differentiate between which of the links were clicked. To establish a URL tag add the following to the HTML of the URL: 

hstracking =”tag” 

For example, in the HTML of a message if you wanted to link to your homepage in both the header and footer, you could use the following tags to identify which URL the user clicked. 

<a href=”https://example.com” hstracking =”Header”>Example.com</a> 

<a href=”https://example.com” hstracking =”Footer”>Example.com</a> 

Valid characters for a tag include 0-9, A-Z, a-z, and hyphen. Tags can be up to 64 characters in length. 

Not to be confused with metatags in Data.

FBLType -> STRING

Current response is only: “abuse” 

This is the value provided in the “Feedback-Type” section of a feedback loop as defined in Section 6 of RFC 5965 - https://datatracker.ietf.org/doc/html/rfc5965#section-6. If other feedback loop types become standardized, the data returned in this field may expand.

FROM -> STRING

The From email address that submitted the feedback loop message to SocketLabs.

TO -> STRING

This is the receiving address that accepted the complaint message. For most customers this will always be “fbl@email-od.com”   

Length -> INT

The character count of the feedback loop message body. 

Data -> JSON

This is an optional JSON data blob that is established upon the submission of a message to SocketLabs. Metadata and Metatags allow for senders to persist additional data along with a given message.