> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> Let agents send transactional emails from your HubSpot account using a private app access token.

The HubSpot integration lets agents send transactional emails from a pre-approved HubSpot email template. It uses HubSpot's Single-Send API, authenticated with a private app access token you create in your HubSpot account.

This integration is specifically the **transactional email** capability. If you are looking to sync HubSpot form submissions into a Circuit index, see [HubSpot Forms](/admin/integrations/feeds/hubspot-forms) instead.

## What you can do

* **Send transactional emails**: agents can send a HubSpot transactional email template to a contact, with custom field values you supply at call time.
* **Use any approved template**: each agent uses one transactional email template, identified by its email ID. You can configure multiple agents with different templates.
* **Reuse HubSpot's deliverability**: emails are sent through HubSpot's transactional sending infrastructure, including the dedicated IP that comes with the add-on.

## Before you start

* **Marketing Hub Professional or Enterprise** with the **Transactional Email add-on**. The Single-Send API is gated to this configuration. Without the add-on, you will not see the `transactional-email` scope when creating a private app.
* **Super Admin** access in HubSpot. Only super admins can create private apps.
* A transactional email already drafted in HubSpot, configured to send **via API**. You will need its email ID.

## Connect HubSpot

<Steps>
  <Step title="Create a private app in HubSpot">
    In HubSpot, click your account name (top right) and choose **Settings**. In the left sidebar, go to **Integrations** > **Private Apps** and click **Create a private app**.
  </Step>

  <Step title="Name the app and add the transactional-email scope">
    On the **Basic Info** tab, give the app a recognizable name like "Circuit transactional email." On the **Scopes** tab, search for `transactional-email` and check it. Do not add scopes the integration does not need.

    If the `transactional-email` scope does not appear in the list, your account does not have the Transactional Email add-on. Contact your HubSpot administrator.
  </Step>

  <Step title="Create the app and copy the access token">
    Click **Create app** at the top right and confirm. HubSpot generates an access token. On the app's **Auth** tab, click **Show token**, then **Copy**. Treat this token like a password: it grants the scopes you selected with no further user prompt.
  </Step>

  <Step title="Find the email ID of the transactional template">
    In HubSpot, go to **Marketing** > **Email**. Open the transactional email the agent should send. There are two ways to retrieve its ID:

    * **Drafted email**: open the email in the editor. The URL looks like `https://app.hubspot.com/email/{PORTAL_ID}/edit/{EMAIL_ID}/settings`. The numeric `{EMAIL_ID}` segment is the value you need.
    * **Published email**: on the email's performance page, the email ID is shown in the **Performance** section. Click to copy.

    The transactional email must have its send method set to **Through an API**. If not, open the email's send settings, choose **Through an API**, then click **Review and publish**.
  </Step>

  <Step title="Paste the token and email ID into Circuit">
    In Circuit, open **Settings** > **Integrations** and choose **HubSpot**. Paste the access token into the `hubspot_access_token` field. Paste the email ID into the `hubspot_email_id` field. Save. The integration status changes to **Connected**.
  </Step>
</Steps>

## What Circuit accesses

Circuit uses one HubSpot scope:

```
transactional-email
```

| Scope                 | Why Circuit needs it                                                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transactional-email` | Call HubSpot's Single-Send API (`POST /marketing/v3/transactional/single-email/send`) to send the approved template to a contact. This is the only HubSpot capability Circuit uses through this integration. |

Circuit sends emails by HubSpot email ID. It does not pull contact lists, modify CRM records, or read email engagement data through this integration.

<Note>
  The access token is created and owned by your HubSpot workspace. Circuit stores it encrypted at rest. It is never returned to the browser or exposed in Circuit's API.
</Note>

## For IT and security teams

HubSpot private app access tokens are scoped, long-lived credentials issued by your HubSpot account. There is no OAuth consent screen and no Circuit-published app in HubSpot's marketplace for this integration.

* **Who can create private apps**: HubSpot restricts private app creation to **Super Admins**. Non-admins cannot generate these tokens.
* **Scope review**: the private app's **Scopes** tab is the source of truth for what the token can do. Audit this tab before sharing the token with anyone, including pasting it into Circuit.
* **Account-wide control**: HubSpot account admins can disable private apps entirely under **Settings** > **Integrations** > **Private Apps** > gear icon, which revokes all tokens issued by your account.
* **Logging**: HubSpot logs every private app API call on the app's **Logs** tab, including endpoint, status code, and timestamp.
* **Rotation**: there is no automatic refresh. Tokens are valid until revoked. Rotate the token at intervals that match your internal policy by deleting and recreating the private app, then updating the value in Circuit.

See [Integration security and admin consent](/it/integration-security) for how Circuit handles credentials across all integrations.

## Disconnect or rotate access

To disconnect from Circuit's side, open **Settings** > **Integrations** > **HubSpot** in Circuit and click **Disconnect**. Circuit deletes the stored token immediately.

To revoke from HubSpot's side:

* **Rotate**: open the private app in HubSpot, go to the **Auth** tab, and click **Rotate token**. The old token stops working. Paste the new value into Circuit.
* **Revoke entirely**: from the private app's actions menu, click **Delete**. The token is invalidated and Circuit's next call returns an authentication error.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;401 Unauthorized&#x22; or &#x22;The authentication credentials are invalid&#x22;">
    The access token is wrong, was rotated, or the private app was deleted. Re-copy the token from the **Auth** tab in HubSpot and paste it into Circuit. If the app was deleted, create a new one.
  </Accordion>

  <Accordion title="&#x22;This account does not have access to the transactional email API&#x22;">
    Your HubSpot account is missing the Transactional Email add-on. The Single-Send API requires Marketing Hub Pro or Enterprise plus the add-on. Contact your HubSpot administrator.
  </Accordion>

  <Accordion title="The transactional-email scope is not in the scope list when creating the private app">
    Same root cause: the Transactional Email add-on is not enabled on the account. The scope is hidden until the add-on is provisioned.
  </Accordion>

  <Accordion title="&#x22;Email not found&#x22; or 404 when the agent tries to send">
    The `hubspot_email_id` does not match a transactional email in this HubSpot account, or the email has not been published with the **Through an API** send method. Open the email in HubSpot, set the send method to **Through an API**, and publish. Then re-copy the ID and update the value in Circuit.
  </Accordion>

  <Accordion title="Email is sent but the recipient never receives it">
    Check the email's **Recipients** tab in HubSpot. The recipient may be on a HubSpot suppression list (bounced, unsubscribed, or marked as spam). Transactional emails respect HubSpot's contact-level send restrictions.
  </Accordion>
</AccordionGroup>

## Reference

* **Auth method**: HubSpot private app access token (user-supplied)
* **Scopes requested**: `transactional-email`
* **Required HubSpot tier**: Marketing Hub Professional or Enterprise, plus the Transactional Email add-on
* **API endpoint used**: `POST /marketing/v3/transactional/single-email/send`
* **Agent properties**: `hubspot_access_token`, `hubspot_email_id`
* **Where you create the private app**: HubSpot **Settings** > **Integrations** > **Private Apps**
* **HubSpot's own docs**: [Private apps](https://developers.hubspot.com/docs/api/private-apps), [Transactional email API guide](https://developers.hubspot.com/docs/api-reference/marketing-transactional-single-send-v3/guide), [Send transactional emails](https://knowledge.hubspot.com/marketing-email/send-transactional-emails)