# How to Integrate Retool with HubSpot Marketing Hub

- Tool: Retool
- Difficulty: Intermediate
- Time required: 25 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to HubSpot Marketing Hub using a REST API Resource with a HubSpot private app token as a Bearer token. Build marketing operations dashboards that manage email campaigns, view landing page analytics, track marketing contacts, and monitor automation workflow performance — all combining HubSpot's marketing data with your internal business data in one Retool interface.

## Build a HubSpot Marketing Hub Operations Dashboard in Retool

HubSpot Marketing Hub's native reporting is powerful but bounded by HubSpot's own dashboard framework. Marketing operations teams frequently need to combine HubSpot's campaign performance data with revenue data from CRM databases, attribution data from ad platforms, or customer records from internal systems. Retool provides the flexible interface layer to build exactly these hybrid dashboards, querying HubSpot's API alongside other data sources.

With a Retool-HubSpot Marketing Hub integration, you can build a campaign performance panel that shows email open rates, click rates, and form conversions alongside revenue attribution from Salesforce or your internal database. You can build an automation workflow health dashboard that surfaces enrollment rates, error states, and step-by-step performance for active marketing workflows. Or you can create a landing page analytics view that combines HubSpot page views and conversion rates with traffic source data from Google Analytics.

HubSpot's private app token system makes this integration particularly clean: you create a token with exactly the scopes your Retool dashboard needs, and the token works as a Bearer token in every API request. This approach is safer than OAuth for server-side integrations because you control the scope granularity and rotation without requiring user re-authentication.

## Before you start

- A HubSpot account with Marketing Hub access (Starter, Professional, or Enterprise)
- Super Admin or Admin access in HubSpot to create private apps
- A Retool account with permission to create Resources
- Familiarity with HubSpot's marketing features (emails, workflows, forms, landing pages)
- Basic understanding of REST API concepts and Bearer token authentication

## Step-by-step guide

### 1. Create a HubSpot private app and generate an access token

HubSpot's recommended authentication method for server-side integrations is private apps, which provide a scoped access token without requiring OAuth user authentication flows. To create one, log in to HubSpot as a Super Admin and click the Settings gear icon in the top navigation bar. In the Settings left sidebar, navigate to Integrations → Private Apps. Click 'Create a private app' in the top right. On the Basic Info tab, give the app a descriptive name like 'Retool Marketing Dashboard' and an optional description. Switch to the Scopes tab to configure which HubSpot APIs your Retool integration can access. For a full marketing dashboard, add the following scopes by searching for them: 'crm.objects.contacts.read' (to read contact records), 'marketing-email' (to read email campaign data — note: requires Marketing Hub Professional or Enterprise), 'forms' (to read form submissions and form definitions), 'workflows' (to read automation workflow data), 'content' (to read landing pages and blog data). Select read-only scopes wherever possible to minimize risk. Click 'Create app' in the top right. HubSpot displays your access token — copy it immediately. This token does not expire by default (unlike OAuth tokens) but can be rotated manually if compromised. Store the token securely; you will paste it into Retool's resource configuration in the next step.

**Expected result:** You have a HubSpot private app with the appropriate marketing scopes and a copied access token ready for configuration in Retool.

### 2. Create the HubSpot Marketing Hub REST API Resource in Retool

In Retool, click the Resources tab in the left sidebar and click Add Resource. Select REST API from the resource type list. Name the resource 'HubSpot Marketing API' (distinct from any existing HubSpot CRM native connector you may have). In the Base URL field, enter: https://api.hubapi.com — this is HubSpot's unified API base URL used by all HubSpot APIs. Scroll to the Authentication section and select Bearer Token from the authentication dropdown. In the Bearer Token field, paste the private app access token you copied from HubSpot. Alternatively — and more securely — first add the token to Retool's Configuration Variables (Settings → Configuration Variables → Add Variable) as a secret named HUBSPOT_PRIVATE_TOKEN, then reference it in the Bearer Token field as {{ retoolContext.configVars.HUBSPOT_PRIVATE_TOKEN }}. Scroll to the Headers section and add a default header: set the key to Content-Type and value to application/json. This ensures POST requests send JSON bodies correctly. Click Save Changes. Retool does not automatically test REST API connections, so you will verify the connection in the next step by running a test query. The HubSpot API uses versioned paths — most marketing endpoints are under /marketing/v3/ or /crm/v3/ which you will specify as the path in individual queries, not in the base URL.

**Expected result:** A HubSpot Marketing API resource appears in your Retool Resources list. You can proceed to create queries against it.

### 3. Query marketing email campaigns and analytics

Create your first marketing queries to verify the connection and populate the dashboard with campaign data. In a Retool app, open the Code panel and click + to add a new query. Select your HubSpot Marketing API resource. Name the query 'getMarketingEmails'. Set the Method to GET and the Path to /marketing/v3/emails. Add URL parameters: 'limit' set to {{ 50 }}, 'state' set to 'PUBLISHED' to retrieve active campaigns (or remove this filter to see all states including drafts). This endpoint returns a list of marketing emails with their configuration and high-level properties. Run the query and check the Results panel. To get performance statistics for a specific email, create a second query named 'getEmailStats'. Set Method to GET and Path to /marketing/v3/emails/{{ marketingEmailsTable.selectedRow.id }}/statistics/list. This returns individual recipient-level statistics. For aggregate campaign statistics, use the path /marketing/v3/emails/{{ marketingEmailsTable.selectedRow.id }}/statistics/histogram with a URL parameter 'interval' set to 'DAY'. Add a JavaScript transformer to the getMarketingEmails query to extract the most useful properties for display: id, name, subject, state, publishDate, stats.sent, stats.open, stats.click, stats.bounce. Run the query and verify data appears.

```
// Transformer: normalize HubSpot marketing email list for display
const emails = data.results || [];
return emails.map(email => ({
  id: email.id,
  name: email.name || '(Unnamed)',
  subject: email.subject || '',
  state: email.state,
  publish_date: email.publishDate
    ? new Date(email.publishDate).toLocaleDateString()
    : 'Not published',
  sent: email.stats?.counters?.sent || 0,
  open_rate: email.stats?.ratios?.openRatio
    ? (email.stats.ratios.openRatio * 100).toFixed(1) + '%'
    : 'N/A',
  click_rate: email.stats?.ratios?.clickRatio
    ? (email.stats.ratios.clickRatio * 100).toFixed(1) + '%'
    : 'N/A',
  unsubscribes: email.stats?.counters?.unsubscribed || 0
}));
```

**Expected result:** The getMarketingEmails query returns a list of marketing email campaigns with formatted open rates, click rates, and send counts ready for display in a Table component.

### 4. Query HubSpot forms and landing page data

Extend the dashboard with form submission and landing page data. Create a query named 'getHubSpotForms'. Set Method to GET and Path to /forms/v2/forms. This returns all forms in your HubSpot account with their configuration. For submissions to a specific form, create a query named 'getFormSubmissions'. Set Method to GET and Path to /form-integrations/v1/submissions/forms/{{ formsTable.selectedRow.guid }}. Add URL parameters: 'limit' set to {{ 50 }} and 'after' for pagination. The submissions endpoint returns an array of submission objects, each with a 'values' array of field-value pairs. Add a JavaScript transformer that flattens the values array into named properties for easy display in a Retool Table. For landing pages, create a query named 'getLandingPages'. Set Method to GET and Path to /cms/v3/pages/landing-pages. Add parameters: 'limit' set to {{ 25 }}, 'state' set to 'PUBLISHED'. This returns published landing pages with their URL, publish date, and performance metadata. To get landing page analytics, use the path /analytics/v2/breakdown/page with parameters specifying the page URL and date range. Drag a Tabs component onto the canvas to organize the dashboard — create tabs for Emails, Forms, Landing Pages, and Workflows. Place the appropriate Table and Chart components in each tab.

```
// Transformer: flatten HubSpot form submission values
const submissions = data.results || [];
return submissions.map(sub => {
  const fields = {};
  (sub.values || []).forEach(field => {
    fields[field.name] = field.value;
  });
  return {
    submitted_at: new Date(sub.submittedAt).toLocaleString(),
    email: fields.email || '',
    firstname: fields.firstname || '',
    lastname: fields.lastname || '',
    company: fields.company || '',
    hs_context_page: sub.pageTitle || '',
    source_url: sub.pageUrl || ''
  };
});
```

**Expected result:** The dashboard has tabs showing marketing emails, form submissions, and landing pages, each populated with data from HubSpot's API and formatted for easy review by marketing operations teams.

### 5. Monitor HubSpot marketing workflows and build campaign attribution

Add workflow monitoring to complete the marketing operations dashboard. Create a query named 'getWorkflows'. Set Method to GET and Path to /automation/v3/workflows. This returns all HubSpot automation workflows with their type, status, and enrollment counts. Filter to active workflows by checking the 'enabled' property in a transformer. For enrollment details on a specific workflow, use Path /automation/v3/workflows/{{ workflowsTable.selectedRow.id }} which includes the workflow's action steps. To build campaign attribution — connecting HubSpot marketing activity to business outcomes — create a companion query using a separate Resource (PostgreSQL database or another CRM) that retrieves revenue records. Use a JavaScript query in Retool to join the datasets: match HubSpot contact emails from form submissions to customer records in your database, then aggregate the revenue associated with each marketing campaign. This cross-Resource joining is one of Retool's most powerful patterns for marketing teams. Create a Chart component showing attributed revenue per email campaign, comparing campaigns by ROI. Add a date range picker at the dashboard top level and bind both the HubSpot queries and the database query to the same date range parameters. For complex marketing attribution logic involving multiple HubSpot APIs, custom revenue attribution models, and scheduled reporting Workflows, RapidDev's team can help architect and build your Retool marketing operations solution.

```
// JavaScript query: join HubSpot campaign contacts with internal revenue data
const campaigns = getMarketingEmails.data || [];
const revenueByEmail = getRevenueFromDB.data || [];

const revenueMap = {};
revenueByEmail.forEach(r => { revenueMap[r.email] = r.total_revenue; });

return campaigns.map(campaign => ({
  campaign_name: campaign.name,
  sends: campaign.sent,
  open_rate: campaign.open_rate,
  click_rate: campaign.click_rate,
  attributed_revenue: revenueMap[campaign.id] || 0,
  roi: campaign.sent > 0
    ? '$' + ((revenueMap[campaign.id] || 0) / campaign.sent).toFixed(2) + ' per send'
    : 'N/A'
}));
```

**Expected result:** The marketing dashboard displays active HubSpot workflows with enrollment counts and a campaign attribution panel that connects HubSpot email performance to revenue outcomes from internal data sources.

## Best practices

- Use HubSpot private apps instead of legacy API keys — private apps offer scope-based access control, better security, and are the only supported authentication method after HubSpot deprecated API keys in 2022
- Store the HubSpot private app token in Retool Configuration Variables as a secret (Settings → Configuration Variables) rather than directly in the Bearer Token field to enable rotation without reconfiguring the resource
- Request only the minimum required scopes when creating the HubSpot private app — read-only scopes for reporting dashboards, write scopes only when your Retool app needs to create or modify HubSpot objects
- Add query caching (60-120 seconds) to email campaign list queries to avoid hitting HubSpot's API rate limits (100 requests per 10 seconds for most endpoints) when multiple users view the dashboard simultaneously
- Use JavaScript transformers to normalize HubSpot's nested JSON response structures into flat arrays before binding to Table and Chart components — this makes column configuration much simpler
- Build enrollment and update operations (workflow enrollment, contact property updates) in separate Retool apps from read-only reporting dashboards — this limits write access to team members who need it
- Schedule nightly Retool Workflows to fetch and cache HubSpot campaign statistics into Retool Database — this reduces API load and provides faster dashboard load times for historical reporting

## Use cases

### Build a marketing email campaign performance dashboard

Create a Retool dashboard that queries all HubSpot marketing email campaigns, displaying performance metrics including sends, opens, clicks, bounces, and unsubscribes in a Table component. Add Charts for engagement trend over time and per-campaign comparison. Include filters for campaign status (drafted, scheduled, sent) and date range. Connect the campaign list to a detail panel that shows individual email performance with a click map description and top-clicked links.

Prompt example:

```
Build a Retool dashboard that lists all HubSpot marketing email campaigns in a Table with columns for name, status, send date, open rate, click rate, and unsubscribe rate. Add a date range filter and status dropdown. When a campaign is selected, show a detail panel with recipient count, delivered percentage, and top-clicked links pulled from the HubSpot email analytics API.
```

### Build a HubSpot form submissions and lead intake panel

Create a Retool panel that aggregates form submissions across all HubSpot forms, showing lead intake volume by form, date, and source. Display submissions in a Table with contact properties including name, email, company, and form source page. Add qualification workflow buttons that create HubSpot contacts or enroll them in automation workflows based on the form data. This gives sales operations teams a faster lead review interface than HubSpot's native submissions view.

Prompt example:

```
Build a Retool form submissions dashboard that queries all HubSpot forms, shows submission counts per form in a Chart, and displays a filterable Table of recent submissions with contact name, email, company, and source URL. Add an 'Enroll in Workflow' button that calls the HubSpot API to add the selected contact to a specified automation workflow.
```

### Build a marketing automation workflow health monitor

Create a Retool operations panel that tracks the health of all active HubSpot marketing workflows — showing enrollment counts, step completion rates, and contacts stuck at individual steps. Surface workflows with high error rates or unexpected enrollment drops. Add an alert mechanism that uses Retool Workflows to send Slack notifications when a workflow's enrollment rate drops significantly, helping marketing operations teams catch broken automation before it impacts campaign performance.

Prompt example:

```
Build a Retool dashboard that lists all active HubSpot marketing workflows in a Table with columns for workflow name, total enrolled, active contacts, completed, and failed. Add a Chart showing enrollment trends for the selected workflow over time. Include a 'View Enrolled Contacts' panel that shows contacts currently at each workflow step.
```

## Troubleshooting

### API returns 401 Unauthorized for all HubSpot Marketing Hub requests

Cause: The private app access token in Retool's resource Bearer Token field is incorrect, expired, or was not copied completely. HubSpot private app tokens are long strings and partial copies are a common mistake.

Solution: In HubSpot, navigate to Settings → Integrations → Private Apps, select your private app, and click 'Show token' to view the full access token. Copy the entire token string (it should start with 'pat-' for private app tokens). In Retool's Resource settings, verify the Bearer Token field contains the complete token without any extra spaces or line breaks. If the token was rotated or deleted in HubSpot, generate a new one by clicking 'Rotate' in the private app settings and update the Retool Configuration Variable.

### 403 Forbidden when querying /marketing/v3/emails — access denied

Cause: The 'marketing-email' scope was not included when creating the HubSpot private app, or your HubSpot account does not have a Marketing Hub Professional or Enterprise subscription, which is required for the marketing emails API.

Solution: In HubSpot Settings → Integrations → Private Apps, edit your private app and add the 'marketing-email' scope under the Marketing category. After saving, HubSpot may regenerate the access token — if so, update your Retool Configuration Variable with the new token. If the error persists, verify your HubSpot portal's subscription includes Marketing Hub Professional or Enterprise, as the marketing email API is not available on Starter plans.

### Form submissions query returns data for some forms but 404 for others

Cause: Different HubSpot form types use different API versions and endpoints. Standard HubSpot forms use /form-integrations/v1/submissions/forms/{guid}, but forms created with HubSpot's newer form builder may use a different endpoint or GUID format.

Solution: Use the getHubSpotForms query (/forms/v2/forms) to retrieve the correct GUID for each form — display both the form name and GUID in a Select component so you can verify you are using the right identifier. Check the 'formType' property in the form data; non-standard form types may require the /crm/v3/objects/feedback_submissions endpoint instead. Log the exact GUID being passed to the submissions endpoint in your query's URL to verify it matches.

### Marketing email statistics show zero values even for campaigns that were recently sent

Cause: HubSpot's marketing email statistics have a processing delay of 1-2 hours after a send completes. Additionally, the statistics endpoint for individual emails may return a different data structure depending on whether the email is a 'batch' send or a workflow-triggered send.

Solution: Wait at least 2 hours after a campaign send before checking statistics. Verify in the HubSpot marketing emails UI that statistics are visible there first — if they appear in HubSpot but not in Retool, check the transformer logic for the correct field paths. The API response structure for statistics includes both 'counters' and 'ratios' sub-objects — ensure your transformer accesses email.stats.counters.sent rather than email.stats.sent directly.

## Frequently asked questions

### What is the difference between the HubSpot native Retool connector and the REST API Resource approach?

Retool's native HubSpot connector is optimized for CRM operations — reading and writing contacts, companies, deals, and tickets using a visual query builder with HubSpot-specific actions. The REST API Resource approach gives you access to marketing-specific endpoints (email campaigns, workflows, forms, landing pages) that the native connector does not cover. For a complete HubSpot dashboard, you may use both: the native connector for CRM data and the REST API Resource for marketing data.

### Do HubSpot private app tokens expire?

No, HubSpot private app tokens do not expire automatically — they remain valid indefinitely unless you manually rotate them in HubSpot settings or the private app is deleted. This simplifies the Retool integration compared to OAuth tokens that require periodic refresh. However, you should rotate the token whenever a team member who managed the integration leaves, or if you suspect the token has been exposed.

### Can I create HubSpot marketing emails or contacts from Retool?

Yes. Use POST requests to /crm/v3/objects/contacts for contact creation, and /marketing/v3/emails for creating draft marketing emails. Creating and sending emails programmatically via the API requires Marketing Hub Professional or Enterprise. Ensure your private app has 'write' scopes in addition to 'read' scopes for the objects you want to create or modify.

### What are HubSpot's API rate limits?

HubSpot enforces a rate limit of 100 API requests per 10 seconds for free and Starter accounts, and higher limits for Professional and Enterprise accounts. In Retool, add query caching to frequently-accessed queries (30-120 seconds depending on data freshness requirements) to stay within rate limits when multiple users access the dashboard simultaneously. For bulk data operations, HubSpot also offers batch endpoints that process multiple records per request.

---

Source: https://www.rapidevelopers.com/retool-integrations/hubspot-marketing-hub
© RapidDev — https://www.rapidevelopers.com/retool-integrations/hubspot-marketing-hub