Email Events Overview

Email Events

Each email that is sent via HubSpot generates some number of events, detailing its lifecycle and how the recipient interacts with its content. An event is uniquely identified by its EventId, which is comprised of the following properties:

Property Name Type Description
id string A randomly-generated ID for this event.
created 64-bit integer The timestamp (in milliseconds since epoch) when this event was created.

These properties can be used to lookup a specific event via this endpoint.

Further, all but one event type (UNBOUNCE) have the following properties:

Property Name Type Description
type string (enumeration) The type of event. See below for more information on event types.
recipient string The email address of the recipient of the email message.
portalId 32-bit integer An ID referencing the HubSpot Portal which sent the email message. This will correspond to your portal.
appId 32-bit integer An ID referencing the HubSpot Application which sent the email message.
appName string The name of the HubSpot Application which sent the email message. Note that this is a derived value, and may be modified at any time.
emailCampaignId 64-bit integer An ID referencing the email campaign which the email message is part of. Additional information on the email campaign can be found via this endpoint.

Events can be looked up in bulk using either 'recipient' or both 'appId' and 'campaignId', and optionally any combination of the above properties, via this endpoint.

The following additional properties are also available for all event types (including UNBOUNCE):

Property Name Type Description
hmid string A randomly-generated ID which corresponds to the header 'X-HubSpot-MID' in the email message.
sentBy JSON The EventId which uniquely identifies the email message's SENT event. If not applicable, this property is omitted.
obsoletedBy JSON The EventId which uniquely identifies the follow-on event which makes this current event obsolete. If not applicable, this property is omitted.
causedBy JSON The EventId which uniquely identifies the event which directly caused this event. If not applicable, this property is omitted.

The event reference properties -- 'sentBy', 'obsoletedBy', and 'causedBy' -- are discussed in detail later in this document.

Event Types

There are 12 different event types which can be generated by HubSpot's Email API during the lifecycle of an email message. They are broadly grouped into the categories: Submission, Delivery, User Engagement, and User Status. The event types, the event categories, and their relationships are diagrammed below.

Event Type Description
SENT The message was sent to and received by our delivery provider, which has queued it for further handling.
DROPPED The message was rejected, either by HubSpot or by our delivery provider, and no attempt will be made to deliver the message.
PROCESSED The message has been received by our delivery provider, which has indicated it will attempt to deliver the message to the recipient's email server.
DELIVERED The recipient's email server has accepted the message and the message has been successfully delivered to the recipient.
DEFERRED The recipient’s email server has temporarily rejected message, and subsequent attempts will be made to deliver the message. This is also referred to as a soft bounce.
BOUNCE The recipient's email server could not or would not accept the message, and no further attempts will be made to deliver the message. This is also referred to as a hard bounce.
OPEN The recipient opened the message.
CLICK The recipient clicked on a link within the message.
PRINT The recipient printed the message.
FORWARD The recipient forwarded the message.
STATUSCHANGE The recipient changed her email subscriptions in some way.
SPAMREPORT The recipient flagged the message as spam.

Submission Events

When an email message is created and sent by HubSpot on behalf of a customer, we first verify the recipient is eligible to receive it. If not, we reject the message, triggering the creation of a DROPPED event. Otherwise, we submit it to our delivery provider for further handling, triggering a SENT event. An email message will almost always have exactly one submission event associated with it; for example, there will never be multiple SENT events for a message.

We make every effort to reject messages before passing them along to our delivery provider. However, sometimes our delivery provider will decide to reject a message even after we have verified its eligibility. This follow-on rejection results in a DROPPED event being created, in addition to the previously-created SENT event.

Submission events all share the following properties:

Property Name Type Description
subject string The subject line of the email message.
from string The 'from' field of the email message.
replyTo list of strings The 'reply-to' field of the email message.
cc list of strings The 'cc' field of the email message.
bcc list of strings The 'bcc' field of the email message.

Additionally, DROPPED events have the following properties:

Property Name Type Description
dropReason string (enumeration) The reason why the email message was dropped. See below for the possible values.
dropMessage string The raw message describing why the email message was dropped. This will usually provide additional details beyond 'dropReason'.

Drop Reasons

Drop Reason Description
PREVIOUSLY_BOUNCED A previous message to the recipient resulted in a bounce.
PREVIOUS_SPAM A previous message to the recipient was flagged as spam.
PREVIOUSLY_UNSUBSCRIBED_MESSAGE The recipient previously unsubscribed from this subscription.
PREVIOUSLY_UNSUBSCRIBED_PORTAL The recipient previously unsubscribed from all subscriptions from the portal.
INVALID_TO_ADDRESS The email address in the 'to' field failed validation.
INVALID_FROM_ADDRESS The email address in the 'from' field failed validation.
BLOCKED_DOMAIN The recipient's domain was blocked.
BLOCKED_ADDRESS The recipient explicitly requested to not receive any emails via HubSpot.
EMAIL_UNCONFIRMED Double opt-in was enabled and the recipient had not yet confirmed his/her subscription.
CAMPAIGN_CANCELLED The associated email campaign was cancelled.
MTA_IGNORE Our delivery provider decided to drop the message. Any additional details will be included in 'dropMessage'.
PORTAL_OVER_LIMIT Your portal had gone over its monthly limit for email sends.
PORTAL_SUSPENDED Your portal was suspended for non-compliance or deliverability issues.

Delivery Events

Once our delivery provider has accepted an email message, we create a PROCESSED event. At this point, the delivery provider has queued the message for delivery. If everything goes smoothly, the delivery provider will dequeue the message and successfully deliver it to the recipient's email server, and we generate a DELIVERED event.

Occasionally, things don't go smoothly, and one of two things happen: delivery is deferred because of a temporary rejection, or delivery fails and will not be retried.

In the first case, the message could not be delivered to the recipient's email server for some non-fatal, usually transient reason, such as a spurious time-out. The delivery provider will re-queue the message for later delivery, and we create a DEFERRED event. A message can be deferred multiple times before it completes the delivery phase, with a new event created on each attempt. (Note that DEFERRED is also referred to as a soft bounce in HubSpot; the terms are used interchangeably.)

If delivery fails, no further attempts will be made to deliver the message, and we create a BOUNCE event. This can occur for a variety of reasons, such as the recipient being unknown by the email server. (Note that BOUNCE is also referred to as a hard bounce in HubSpot; the terms are used interchangeably.)

The specific delivery event types have the following properties:

DELIVERED

Property Name Type Description
response string The full response from the recipient's email server.
smtpId string An ID attached to the message by HubSpot.

DEFERRED

Property Name Type Description
response string The full response from the recipient's email server.
attempt 32-bit integer The delivery attempt number.

BOUNCE

Property Name Type Description
category string (enumeration) The best-guess of the type of bounce encountered. If an appropriate category could not be determined, this property is omitted. See below for the possible values. Note that this is a derived value, and may be modified at any time to improve the accuracy of classification.
response string The full response from the recipient's email server.
status string The status code returned from the recipient's email server.

Bounce Categories

Bounce Category Description
UNKNOWN_USER The recipient did not exist.
MAILBOX_FULL The recipient's mailbox was full and could not receive any messages.
CONTENT The recipient's filters identified content in the body of the email that was suspicious or spammy.
SPAM The message was flagged as spam.
POLICY The message was flagged as spam.
GREYLISTING The email server requires a longer history of email activity from the sender.
MAILBOX_MISCONFIGURATION A mailbox misconfiguration was detected.
ISP_MISCONFIGURATION An ISP misconfiguration was detected.
DOMAIN_REPUTATION The sending domain has a poor reputation or a reputation that doesn't meet the standards of the recipient server.
DMARC The sender’s domain does not pass a DMARC check. Please review your SPF and DMARC policies.
SENDING_DOMAIN_MISCONFIGURATION Domain authentication failed due to a policy on the recipient's end.
TIMEOUT The receiving email server timed out and is no longer accepting email.
THROTTLED The recipient's email server was throttling messages.
UNCATEGORIZED An uncategorized error was detected.
IP_REPUTATION The message originated from a suspicious (or previously unknown) IP address.
DNS_FAILURE The recipient’s domain name server settings were misconfigured at the time the email was sent.
TEMPORARY_PROBLEM Some temporary problem occurred.

User Engagement Events

Once an email message reaches its recipient, there are four different event types which can occur: OPEN, CLICK, PRINT, and FORWARD. These represent the recipient's interaction with the message and its content, and can occur multiple times. For example, each time any URL is clicked, a new CLICK event is created, even if that URL has previously been clicked and generated such an event.

User engagement events all share the following properties:

Property Name Type Description
ipAddress string The IP address where the event originated.
userAgent string The user agent responsible for the event, e.g. “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36”
browser JSON A JSON object representing the browser which serviced the event. Its comprised of the properties: 'name', 'family', 'producer', 'producer_url', 'type', 'url', 'version'.
location JSON A JSON object representing the location where the event occurred. Its comprised of the properties: 'city', 'state', 'country'.

Additionally, CLICK events have the following properties:

Property Name Type Description
url string The URL within the message that the recipient clicked.
referer string The URL of the webpage that linked to the URL clicked. Whether this is provided, and what its value is, is determined by the recipient's email client.

And OPEN events may have the following property:

Property Name Type Description
duration 64-bit integer (milliseconds) If provided and nonzero, the approximate number of milliseconds the user had opened the email.

User Status Events

A recipient can also affect her communication preferences via the email message. By clicking on the subscription preferences link in the message, she can change her subscriptions, either subscribing or unsubscribing from various lists, triggering a STATUSCHANGE event. Note that a status change can be for any list(s), not just the one which is associated with the current email message.

An email message may also be flagged as spam by the recipient, resulting in a SPAMREPORT event. Note that this is independent of subscription status -- flagging a message as spam does not simply unsubscribe the recipient from the list in question. Rather, the subscription status is left unchanged, and a flag is set which indicates that recipient should never receive an email message from HubSpot. Once this has happened, you'll need manual intervention by HubSpot to unset the flag.

A STATUSCHANGE event has the following additional properties:

Property Name Type Description
source string (enumeration) The source of the subscription change. See below for the possible values.
requestedBy string The email address of the person who requested the change on behalf of the recipient. If not applicable, this property is omitted.
portalSubscriptionStatus string (enumeration, 'SUBSCRIBED' or 'UNSUBSCRIBED') The recipient's portal subscription status. (Note that if this is 'UNSUBSCRIBED', the property 'subscriptions' is not necessarily an empty array, nor are all subscriptions contained in it necessarily going to have their statuses set to 'UNSUBSCRIBED'.)
subscriptions JSON An array of JSON objects representing the status of subscriptions for the recipient. Each JSON subscription object is comprised of the properties: 'id', 'status'.
bounced boolean (true, or omitted entirely) A HubSpot employee explicitly initiated the status change to block messages to the recipient. (Note this usage has been deprecated in favor of dropping messages with a 'dropReason' of BLOCKED_ADDRESS.)

Subscription Change Sources

Source Description
SOURCE_LIST_UNSUBSCRIBE The recipient used a list-unsubscribe header.
SOURCE_RECIPIENT The recipient used the subscription UI.
SOURCE_IMPORT The customer imported the subscriptions into their portal.
SOURCE_HUBSPOT_CUSTOMER The customer used the subscription UI.
SOURCE_SPAM_REPORT A spam report generated by an automated system was received.
SOURCE_NON_DELIVERY_REPORT A non-delivery report (typically a bounce) was received.
SOURCE_DIRECT_COMPLAINT A direct complaint via abuse@hubspot.com was received.
SOURCE_MTA_RECORD Our delivery provider provided the change, during our normal synchronization with their system-of-record.
SOURCE_HUBSPOT A HubSpot employee made the change.
SOURCE_MIGRATION HubSpot migrated the subscriptions from a previous version of the product.
SOURCE_HUBSPOT_CLEANUP HubSpot cleaned up the subscriptions.
SOURCE_KNOWN_SPAM_TRAP This recipient address is a known spam trap, and should not receive emails.

'Unbounce' Events

There is a 13th event type, which is unrelated to a specific email message. UNBOUNCE events occur when a particular email address is either automatically or manually unbounced by HubSpot. This has the effect of resetting the bounce status of the recipient, potentially allowing that recipient to receive emails from your portal.

Property Name Type Description
user string The email address of the user who submitted the unbounce request.

Event References

Many events are related to other events that occurred either before or after it. We use EventIds, as described in the first section above, to build this reference chain.

Note that event references are relatively new, and older events may not have them populated.

'sentBy'

As discussed previously, each email message has either a SENT or DROPPED event (or one of each) associated with it. This will be the first event generated for any given message. If a message generates a SENT event, all subsequently-generated events will reference that event via the property 'sentBy'.

This backward-reference can be useful to get more information on the parent SENT event, or to manually find all events associated with a given message.

'obsoletedBy'

Sometimes, a follow-on event occurs for a given message which signifies an earlier event should be completely ignored. This relationship is captured in a forward-reference in the property 'obsoletedBy'.

For instance, in the case where we generate both a SENT event and a subsequent DROPPED event, the SENT event is ultimately irrelevant, and is obsoleted by the DROPPED event. Accordingly, the SENT event will reference the DROPPED event via 'obsoletedBy'.

'causedBy'

Certain events occur precisely because of some previous event, often for a different message. This relationship is captured in a backward-reference in the property 'causedBy'. It can be used to get additional details on why a particular event occurred from the event which caused it.

For example, a DROPPED event will occur when there was a previous BOUNCE event for the same recipient. In this case, the DROPPED event will have its 'dropReason' set to PREVIOUSLY_BOUNCED, and its 'causedBy' will reference that previous BOUNCE event.

Docs for this section or API