> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- id: cdb49ccb-884f-4040-ab05-22602d27c239 --- # Email Events API Overview > Learn more about the Email Events API endpoints. The email events API is used to get information about events generated by marketing emails or email campaigns sent through a HubSpot account. **Use case for this API:** if a member of your marketing team wants to optimize email campaigns, you can use this API to gather data and power a machine learning model that determines the best time to send emails to different contact segments. ### Email events Every email sent via HubSpot generates a 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 look up a specific event via [this endpoint](/api-reference/legacy/reporting/email-analytics/events/get-email-public-v1-events). 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 | The ID of the HubSpot account that sent the email message. | | `appId` | 32-bit integer | An ID referencing the HubSpot application that sent the email message. | | `appName` | string | The name of the HubSpot application that 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](/api-reference/legacy/reporting/email-analytics/campaigns/get-email-public-v1-campaigns-campaign_id). | Events can be looked up in bulk via [this endpoint](/api-reference/legacy/reporting/email-analytics/events/get-email-public-v1-events) using `'recipient'`, both `'appId'` and `'campaignId'`, or any combination of the above properties. The following additional properties are also available for all event types (including `UNBOUNCE`): | Property name | Type | Description | | ------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | These event reference properties are covered in more detail in the [section](#event-references) at the bottom of this article. ## Event types There are 12 event types that can be generated by HubSpot's Email API during the lifecycle of an email message. They are broadly grouped into categories: Submission, Delivery, User Engagement, and User Status. Event types, event categories, and their relationships are diagrammed below. ![](https://static.hsappstatic.net/developer_site_web/static-2.153/img/events.svg) | Event type | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SENT` | The message was sent to and received by HubSpot's delivery provider, which has queued it for further handling. | | `DROPPED` | The message was rejected, either by HubSpot or by HubSpot's delivery provider, and no attempt will be made to deliver the message. | | `PROCESSED` | The message has been received by HubSpot's 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. | | `BOUNCE` | The recipient's email server couldn't or wouldn't accept the message, and no further attempts will be made to deliver the message. | | `OPEN` | The recipient opened the message. | | `CLICK` | The recipient clicked on a link within the message. | | `STATUSCHANGE` | The recipient changed their email subscriptions in some way. | | `SPAMREPORT` | The recipient flagged the message as spam. | | `SUPPRESSION` | The message was not sent, the recipient has been unengaged with previous marketing emails. | Some event types, such as bot events, may be included in the response to the `/events` API but won't appear when you're analyzing the [*Recipients* tab for a marketing email in your HubSpot account](https://knowledge.hubspot.com/email/analyze-your-marketing-email-campaign-performance), which filters out certain raw event types and limits the total events shown to 30 events per event type. ### Submission events When an email message is created and sent by HubSpot on behalf of a customer, HubSpot first verifies whether the recipient is eligible to receive it. If not, HubSpot rejects the message, triggering the creation of a `DROPPED` event. Otherwise, it's submitted to HubSpot's 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. HubSpot makes every effort to reject messages before passing them along to the delivery provider. However, sometimes HubSpot's delivery provider will decide to reject a message even after its eligibility has been verified. 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 account. | | `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 their subscription. | | `CAMPAIGN_CANCELLED` | The associated email campaign was canceled. | | `MTA_IGNORE` | HubSpot's delivery provider decided to drop the message. Any additional details will be included in `'dropMessage'`. | | `PORTAL_OVER_LIMIT` | Your account went over its monthly limit for email sends. | | `PORTAL_SUSPENDED` | Your account was suspended for non-compliance or deliverability issues. | | `QUARANTINED_ADDRESS` | The recipient has been quarantined due to repeated hard bounce rates. | | `ADDRESS_LIST_BOMBED` |  The recipient has been quarantined due to suspicious form activity. [Learn more](https://knowledge.hubspot.com/marketing-email/understand-spam-traps-and-email-blocklists). | ### Delivery events Once HubSpot's delivery provider has accepted an email message, HubSpot creates 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 deliver it to the recipient's email server, generating a `DELIVERED` event. Occasionally, things don't go smoothly, and one of two things happens: delivery is deferred because of a temporary rejection, or delivery fails and won't 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 HubSpot creates a `DEFERRED` event. A message can be deferred multiple times before it completes the delivery phase, with a new event created on each attempt. If delivery fails, no further attempts will be made to deliver the message, and HubSpot creates a `BOUNCE` event. This can occur for a variety of reasons, such as the recipient being unknown by the email server. 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 couldn't 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 didn't exist. | | `MAILBOX_FULL` | The recipient's mailbox was full and couldn't receive any messages. | | `CONTENT` | The recipient's filters identified content in the body of the email as 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 that can occur: `OPEN`, `CLICK`, `PRINT`, and `FORWARD`. These represent the recipient's interaction with the message and its content, and each 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 | | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. It's comprised of the properties: `'city'`, `'state'`, `'country'`. | | `filteredEvent` | boolean | A boolean representing whether the event has been filtered out of reporting based on customer reports settings or not. | 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 update their communication preferences via the email message. By clicking on the subscription preferences link in the message, they can change their 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 indicating that recipient should never receive another email message from HubSpot. Once this happens, you'll need manual intervention by HubSpot to remove 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 requesting the change on behalf of the recipient. If not applicable, this property is omitted. | | `portalSubscriptionStatus` | string (enumeration, `'SUBSCRIBED'` or `'UNSUBSCRIBED'`) | The recipient's HubSpot 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 account. | | `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` | HubSpot's delivery provider provided the change, during normal synchronization with the 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 resets the bounce status of the recipient, potentially allowing them to receive emails sent from the account. | 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. As described in the first section above, HubSpot uses EventIds to build this reference chain. ### 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, signifying that an earlier event should be ignored. This relationship is captured in a forward-reference in the property `'obsoletedBy'`. For instance, in the case where HubSpot generates 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 caused the following event. 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 it's `'causedBy'` will reference that previous `BOUNCE` event.