# Connect HubSpot

You'll save visitors' answers to HubSpot and use their properties and lists to personalize your website, with signup actions that fit your follow-up.

Available on the Pro plan.

Connect HubSpot to save visitors' answers to their contact records, ready for your follow-up. You can also use an identified contact's properties and list memberships to show them relevant content on your website.

## Connect HubSpot

You'll need permission to manage your RightMessage project's integration and authorize the HubSpot account you want to use. Each project connects to one email platform or CRM. Review where you use an existing connection before replacing it.

1. Open your RightMessage project settings and choose **Integration**.
2. On **Email platforms & CRMs**, select **HubSpot**.
3. In **Overview**, click **Connect to HubSpot**.
4. Sign in to HubSpot, choose the account, and approve access.
5. Return to RightMessage and check for **Connected to HubSpot** and a healthy connection.

![HubSpot connection controls in RightMessage, with no credentials entered](https://rightmessage.com/help/screens/integrations-hubspot-connection.light.webp)

HubSpot uses OAuth. Authorization saves the Portal ID and tokens, so you don't need to copy them into the connection screen. Use **Reconnect to HubSpot** if it needs renewed access.

Prepare a test contact you control and a page with the [RightMessage snippet installed](https://rightmessage.com/help/everything-you-need-to-know-about-your-rightmessage-tracking-script). If you'll identify people through HubSpot's tracking code, install that too. If you'll submit to a HubSpot form, you'll need access to the form and its property definitions.

## Recognize subscribers from email links

An identifying link lets RightMessage look up the contact who clicked it. Add `rm_hs` with HubSpot's contact-email merge field to your website links. For example, a link to [WorkForge](https://workforge.rightmessage.com) could be:

```text
https://workforge.rightmessage.com/solutions.html?rm_hs={{contact.email}}
```

Use your own page URL. If it already has a query string, append `&rm_hs={{contact.email}}`. Send a message to a test contact so HubSpot fills in the merge field. A URL with literal braces won't identify anyone. The generic `email` parameter also supports a URL-encoded email lookup.

1. Give your test contact a distinctive HubSpot property value or list membership.
2. Open the delivered link in a fresh browser session on the page with RightMessage installed.
3. In the [on-site debugger](https://rightmessage.com/help/using-the-rightmessage-debugger), check the contact and their HubSpot data.
4. Visit another page in the same browser without the parameter. RightMessage should remember the contact. Another browser or device needs its own identification.

HubSpot's tracking code can also identify a visitor when its token resolves to a contact. An anonymous tracking cookie alone won't do that. Supported HubSpot form callbacks can supply a valid email, but the contact still needs to be available for lookup. Submitting the form and making the contact available are separate stages.

## Choose what to sync

RightMessage reads native fields, custom properties, and list membership after identification. Use a property for choice answers, and a native field or writable custom property for typed answers. HubSpot doesn't offer native tag sync.

> **Use properties for question answers**
>
> The editor offers **Lists** as a sync mode, but automatic answer-to-list writes don't work correctly. Choose **Property** for question answers. The separate **Add to list** contact action can add a submitted contact to a writable static/manual list.

1. Open **Questions**, choose your question, and open **Sync with HubSpot**.
2. Choose **Property** in **Sync mode**. Single-answer questions default to a field. Multiple-answer questions can default to **Lists**, so change those before mapping.
3. Choose **Destination** and complete **Answer → value** for each answer. Map typed answers to a compatible native field or custom property.
4. If your flow collects email, open the Email question's **Setup**. Keep **Identify the visitor** enabled and choose a **Contact action**.
5. Select the destination lists or forms when your action requires them.
6. Review the mappings and click **Publish** when you're ready to make them live.

Choose the contact action that fits your follow-up:

| If you'd like to…                                 | Choose                    |
| ------------------------------------------------- | ------------------------- |
| Create or update a contact without a list or form | **Create/Update contact** |
| Add the contact to a writable static/manual list  | **Add to list**           |
| Record a submission to an eligible HubSpot form   | **Submit form**           |

HubSpot's rules manage dynamic lists. Use a static/manual list for direct additions. RightMessage's form picker excludes forms with CAPTCHA enabled.

A newsletter signup can use **Submit form** when your automation starts with that HubSpot form submission. You don't need a matching HubSpot form for every RightMessage offer if you only want to update the contact.

Multiple answers saved to a property are comma-separated. Choose a compatible text or multiple-checkbox property rather than a single-choice property. Save an **Other** write-in to a separate property with **Save write-ins to HubSpot**. Switching **Sync mode** clears previous mappings after confirmation.

To create a text property from the picker, choose **New HubSpot property**. Enter **Field Name** using letters, numbers, and underscores, then click **Create**. Create specialized property types and option sets in HubSpot first.

### Match your HubSpot form's requirements

If you use **Submit form**, check the selected form in HubSpot before collecting signups. RightMessage's required setting controls its own question or form. It doesn't change what HubSpot requires.

1. List the required fields using their internal property names, not just their visible labels.
2. Collect and map a value for each one. RightMessage includes the contact's email, but doesn't invent other required values.
3. Match each property's type. Use text properties for free text, number properties for numeric answers, and compatible date properties for dates.
4. For dropdown and radio properties, map to an existing option. For multiple-checkbox properties, every selected value must match an allowed option.
5. For a single boolean checkbox, use `true` or `false`, not arbitrary answer labels.
6. Check HubSpot's consent requirements alongside the disclosure and consent controls you show in RightMessage.

RightMessage translates recognized option labels to HubSpot's internal option values. If any supplied choice doesn't match, it skips that whole property update. It doesn't save only the matching choices or create a new option.

An unchecked consent box on a RightMessage Email question prevents identification and sending data. Checking it doesn't supply HubSpot's form-specific subscription consent. The current HubSpot consent payload sets `consentToProcess` to `false`, sends empty text, and includes no communication permissions. It doesn't pass through the visitor's checkbox choice.

Your selected HubSpot form defines the required fields. There's no universal list of extra fields every form needs. The native catalog includes **First Name**, **Last Name**, **Email**, **Phone**, **Mobile Phone**, **Company**, **Website**, **Job Title**, **Address**, **City**, **State**, **Zip**, **Country**, **Lifecycle Stage**, **Contact Owner**, and **Lead Status**. Contact Owner needs the HubSpot owner ID, not the display name.

Other writable properties appear as custom properties. Read-only properties are excluded. Name and Address questions can use **One field per part** to save their parts separately.

> **Check the form submission, not only the contact**
>
> If portal details are missing or HubSpot rejects a form with certain validation errors, RightMessage can write the supplied properties directly to the contact instead. This includes consent or CAPTCHA-related validation failures. The contact can change without a successful form submission or form-based automation. Authentication, rate-limit, and upstream failures aren't treated as successful fallback submissions.

The list catalog loads at most 10,000 lists. Properties, forms, and lists can stay cached for 24 hours. If a recent change is missing, use **Clear Cache** rather than rebuilding mappings.

### If you need a HubSpot event action

In a RightMessage form's **Action**, choose **Trigger an event** and select an existing HubSpot behavioral event. **Event metadata** supports Liquid templates. This is a form action, not an Email question's **Contact action**.

Create the event definition in HubSpot first. RightMessage uses its internal event name, not arbitrary text. The current OAuth connection doesn't request the event-definition permission needed to populate the picker. Reconnecting alone won't add it. If no events appear, use a supported contact, list, or form action.

Check event delivery separately. An event action can update the contact even when HubSpot doesn't record the event. Outgoing events don't make HubSpot event or purchase history available for incoming conditions, and this connection has no direct automation-enrollment action.

Follow [Map answers to contact fields and tags](https://rightmessage.com/help/synchronizing-contact-data-with-your-email-platform-or-crm) for shared mapping and return-visit behavior.

## Check the connection

1. Submit your published form or flow with the test contact.
2. In HubSpot, check the exact property values and expected static-list membership.
3. If you chose **Submit form**, look for that submission in the contact's activity.
4. Check the automation you expected to start.
5. Repeat with a new email you control to test contact creation too.

If a new property, form, or list is missing, open **Integration → HubSpot → Overview** and click **Clear Cache**, then reopen its picker. If one property stays unchanged, check its internal name, type, and option values. If the contact changes but form activity is missing, check required fields and validation before reconnecting.

When the contact has the answers you sent and the list or form action you chose is recorded, your setup is working. [Verify an integration change](https://rightmessage.com/help/verify-an-integration-change) walks through these checks, including the form submission your automation depends on.