HubSpot CRM Emails API Scopes: Resolving MISSING

Hey ESHOPMAN community! As experts helping you supercharge your e-commerce operations with HubSpot, we know that getting your systems to talk to each other seamlessly is half the battle. Integrating email engagement data from HubSpot into your custom applications or dashboards can provide invaluable insights for your sales and marketing teams. But sometimes, even with clear documentation, the HubSpot API can throw a curveball. We recently stumbled upon a fascinating discussion in the HubSpot Community that perfectly illustrates this, and it’s a goldmine for anyone building public OAuth apps.

The Head-Scratcher: Missing Scopes for CRM Emails API

The original poster in the community thread was trying to read email engagement content using HubSpot’s CRM Emails API (specifically endpoints like GET /crm/v3/objects/emails). Sounds straightforward, right? Well, not quite. They kept running into a pesky 403 MISSING_SCOPES error, with the API explicitly demanding either crm.schemas.emails.read or crm.objects.emails.read. The problem? These scopes simply weren't available in their public OAuth app’s scope picker, even though they had successfully requested and granted sales-email-read.

Here’s a snippet of the error they were seeing:

{
  "category": "MISSING_SCOPES",
  "message": "This app hasn't been granted all required scopes to make this call.",
  "errors": [
    {
      "context": {
        "requiredGranularScopes": [
          "crm.schemas.emails.read",
          "crm.objects.emails.read",
          "sales-email-read"
        ]
      }
    }
  ]
}

It’s a classic developer dilemma: the error message tells you what you need, but what it needs isn't available. This led to a lot of head-scratching, wondering if it was a platform limitation or an ongoing issue.

Unraveling the Mystery: The Community Steps In

A senior community moderator quickly tagged in a few API experts, and the conversation began to uncover some crucial details.

One expert initially suggested checking the most recent API version's documentation and considering a migration to HubSpot’s Developer Platform if the app was still on a legacy model. This is always a solid first step for any API issue – ensuring you’re on the latest and greatest. However, the original poster confirmed they were already using the Developer Platform with a public OAuth app and had even tried the latest API endpoints, like GET /crm/objects/2026-03/emails. Despite this, the API continued to return the same 403 MISSING_SCOPES error, still demanding those elusive crm.objects.emails.read and crm.schemas.emails.read scopes.

Another community member weighed in, suggesting it looked like a platform limitation and advised contacting HubSpot support if the documented scopes and actual access requirements didn’t match. This is often a last resort, but a valid one when you’ve exhausted all other options.

The Breakthrough: It's All About the Contacts!

The key insight came from the same API expert (who had initially suggested checking the API version). After the original poster clarified their setup, the expert provided a critical piece of information and a working example.

It turns out that while the error message explicitly requested crm.objects.emails.read and crm.schemas.emails.read, the solution for public OAuth apps on the Developer Platform involves a slightly different set of scopes. The expert successfully read emails from a Developer Test Portal by including sales-email-read along with crm.objects.contacts.read (and crm.objects.contacts.write if you need to modify contact data). This strongly suggests that email engagements, being activities associated with contacts, are accessible through contact-related scopes.

This is a vital distinction for anyone looking to deeply integrate HubSpot data with their custom applications, whether you're building a new feature for your existing ecommerce website builder online or trying to create own ecommerce website from scratch with HubSpot as your CRM backbone.

How to Configure Your Public OAuth App for Email Access

If you’re building a public OAuth app on HubSpot’s Developer Platform and need to read email engagement data, here’s the actionable takeaway:

Understand Your Scopes: Even if the API error message requests specific email object scopes, try including contact-related read scopes.
Modify Your *-hsmeta.json File: In your app’s configuration file (e.g., src/app/your-app-hsmeta.json), ensure your requiredScopes array includes the following:

{
  "uid": "your_app_uid",
  "type": "app",
  "config": {
    "description": "Your app description.",
    "name": "Your App Name",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": [
        "http://localhost:3000"
      ],
      "requiredScopes": [
        "oauth",
        "crm.objects.contacts.read",
        "sales-email-read"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": [
        "https://api.hubapi.com"
      ],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

(Note: We've omitted crm.objects.contacts.write from the example above for a read-only scenario, but include it if you need write access.)

Test Your API Call: With the correct scopes configured and your app reinstalled (to ensure new scopes are granted), you should be able to make calls like this one to retrieve email data:

curl --location 'https://api.hubapi.com/crm/objects/2026-03/emails?limit=100' \
--header 'Authorization: Bearer ••••••'

ESHOPMAN Team Comment

This community discussion perfectly highlights a common challenge in API development: sometimes the explicit error message isn't the whole story. For HubSpot users, RevOps, and marketers building custom integrations or using an online store maker that needs deep HubSpot connectivity, this is a crucial lesson. We believe that understanding these nuances is key to building robust, scalable e-commerce solutions. Always look at related object scopes when direct ones aren't available, and leverage the community – it's an invaluable resource for navigating these complexities.

So, there you have it! A seemingly complex API scope issue resolved by a deeper understanding of how HubSpot structures its data and permissions, thanks to the collaborative spirit of the community. This kind of nuanced insight is invaluable for anyone building powerful integrations to manage their customer relationships and supercharge their sales. Keep experimenting, keep learning, and don't be afraid to dive into the community forums when you hit a wall!