Installation

This guide walks you through installing Email Cleaner in your HubSpot portal.

Prerequisites

• Any HubSpot account, including Free. The Email Cleaner card works on every plan; the Clean Email workflow action needs a plan with workflows (Professional or Enterprise)
• Permission to install apps and customize record views in your portal (and to manage workflows, if you use the workflow action)
• An OpsAgent account with an organization set up

Installation Steps

1. Start Installation

Navigate to the Email Cleaner app page in OpsAgent and click Install App.

2. Select Your Portal

If you have multiple HubSpot portals connected, choose the one where you want to install Email Cleaner.

3. Authorize Permissions

HubSpot asks you to approve the access Email Cleaner needs:

• Required: read access to contacts, companies, deals, and tickets, so the card can read the record it is on
• Optional (pre-selected): read access to orders, projects, appointments, courses, listings, services, invoices, and custom objects, so the card also works on those records
• Optional (pre-selected): edit access to those objects, needed only to save a cleaned address from the card

If you leave out an optional permission, the card on that kind of record says so. You can grant it later with Reinstall App on the app's Configuration page in OpsAgent, or, for edit access, with Grant edit access on the card. The Clean Email workflow action needs no extra permission.

Review the access and click Connect app.

4. Choose Your Cleaning Behaviors (Optional)

Email Cleaner works immediately after install: the base cleaning (trim, lowercase, strip invalid characters, remove internal whitespace, validate format) always runs. You can also turn on optional behaviors: Strip Plus Addressing, Fix Common Typos, Normalize Domain, and Flag Disposable & Role-Based. All four are off by default.

Change them in OpsAgent on the app's Settings page, or in HubSpot under the app's Settings tab; both edit the same settings. See the Settings Reference for what each setting does.

5. Add the Card to Your Record View

In HubSpot, open a contact (or any record type you want to clean emails on), click Customize, and add the Email Cleaner card to the sidebar. The "Add Card to Contact View" onboarding step in OpsAgent links straight to the right settings page.

6. Verify Installation

Check that:

1. The app appears in your OpsAgent dashboard under installed apps
2. The Email Cleaner card shows on the records you added it to
3. On plans with workflows, the Clean Email action appears when editing a HubSpot workflow (look for it under the "Email Cleaner" app heading)

Troubleshooting

Authorization Failed

Make sure you have admin or super-admin permissions in your HubSpot portal. Standard users may not be able to authorize app connections.

The Card Has No Access or Cannot Save

The permission for that kind of record was not granted at install. To save, click Grant edit access on the card: OpsAgent opens the Reinstall dialog for your portal. Tick Save Cleaned Email, click Update Permissions, and approve edit access in HubSpot. For read access to a kind of record, use Reinstall App on the app's Configuration page in OpsAgent and allow it for that object.

Workflow Actions Not Appearing

Workflows need a HubSpot plan that includes them (Professional or Enterprise). On such a plan, it can take a few minutes after installation for HubSpot to register new workflow actions. Try refreshing the workflow editor. If they still don't appear, verify the app is active in your OpsAgent dashboard.