Announcement: New scope required to get the content of email engagements

As part of our ongoing efforts to improve transparency regarding what data connected apps have access to, we're adding a new scope that controls access to the content of email engagements.

What is changing?

Starting today, new apps and apps not currently using the Engagements API will require an additional scope to get the content of emails through the Engagements API. This will affect any engagement record with the type field set to EMAIL, INCOMING_EMAIL, or FORWARDED_EMAIL.

This new scope will be named sales-email-read. This scope works with the existing contacts scope, as the contacts scope will still be needed to access the Engagements API.

Requests that access engagement data when the access token does not have the sales-email-read scope will have the details of records with the EMAIL, INCOMING_EMAIL, or FORWARDED_EMAIL type redacted in the response:

{
  "associations": {
    "workflowIds": [],
    "ownerIds": [],
    "ticketIds": [],
    "contactIds": [
      226758
    ],
    "dealIds": [],
    "quoteIds": [],
    "companyIds": [
      11174312
    ],
    "contentIds": []
  },
  "engagement": {
    "timestamp": 1556890404000,
    "allAccessibleTeamIds": [],
    "queueMembershipIds": [],
    "lastUpdated": 1565207557798,
    "portalId": 62515,
    "active": true,
    "type": "INCOMING_EMAIL",
    "id": 10053151,
    "createdAt": 1556890428072
  },
  "attachments": [],
  "metadata": {
    "cc": [],
    "to": [],
    "validationSkipped": [],
    "html": "The content of this email has been redacted. To include it in the response, your app must require the sales-email-read scope.",
    "bcc": []
  }
}

Who will be impacted:

Please note that this only affects the details for engagements with the EMAIL, INCOMING_EMAIL, or FORWARDED_EMAIL type. 

Who will NOT be impacted:

If your integration does not use the content or details of email engagements, then no changes will be needed for your integration, and you can continue to use the contacts scope alone to access the Engagements API.  Additionally, if your integration uses an API key, this change will not affect you and you will continue to receive the full details for email engagements.

Why is this happening?

Emails sent from HubSpot through a connected inbox are sent through the user's email service provider. We're adding this additional scope to make it more clear to users connecting your app that the emails sent to individual contacts from their personal emails can be viewed by the app.

When is this happening?

The sales-email-read scope can be added to your app now, and users will be able to approve this new scope immediately. If you are working with a newly created app, or an existing app that is not currently using the Engagements API, we will begin enforcing this scope for new app installs starting today. Any installations that do not request the sales-email-read will receive the redacted data for email engagements.

If you have an existing integration with active users using the Engagements API, we'll be reaching out directly with more details about updating your app.

Please let us know if you have any questions by joining the conversation in our community here.