cleanup-lists

Cleanup Lists

Audit HubSpot lists to remove clutter. Unused lists slow down the UI, confuse team members, and can mask the lists that actually matter.

Prerequisites

• HubSpot API token in .env
• Python with hubspot-api-client installed via uv
• Note: Lists API access may return 403 on some plan tiers. If so, perform the audit manually in the UI.

Step-by-Step Instructions

Stage 1: Before — Inventory All Lists

Pull all lists via the API:

from hubspot import HubSpot

api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))

lists = []
offset = 0
while True:
    response = api_client.crm.lists.lists_api.get_page(offset=offset, limit=100)
    lists.extend(response.results)
    if not response.paging or not response.paging.next:
        break
    offset = response.paging.next.after

For each list, record: list ID, name, type (active/static), member count, created date, last updated date.

Export to CSV for review.

Stage 2: Execute — Identify Candidates for Deletion

Flag lists matching any of these criteria:

1. Zero members and created more than 30 days ago
2. Not referenced by any workflow, email, or ad audience
3. Duplicate names or nearly identical filter criteria
4. Test/temp lists (names containing "test", "temp", "copy of", "old")
5. Static lists that have not been updated in 6+ months

Cross-reference with workflows and email campaigns before deleting — a list with zero members might still be used as an enrollment trigger.

Stage 3: After — Delete and Document

1. Delete confirmed unused lists via the API or UI.
2. Document what was deleted (list name, ID, reason) in a cleanup log.
3. Inform team members if any lists they created were removed.

Stage 4: Rollback

• HubSpot does not have a list recycle bin. Deleted lists cannot be restored.
• Before deleting, export the list definition (filters/criteria) so it can be recreated if needed.
• Static lists: export member IDs before deletion if the membership data matters.

Tips

• Run this quarterly as part of the database cleanup routine.
• Establish a naming convention going forward (e.g., prefix with team name or purpose).
• Archive lists by prefixing with "[ARCHIVE]" instead of deleting if you are unsure.