hubspot-list-emails_skill

Overview

This skill lists email engagement records from HubSpot CRM so you can review recent correspondence tied to your contacts and deals. It returns structured email metadata and text previews, plus pagination cursors for large result sets. Use natural triggers like “list emails” or “show emails” to invoke it.

How this skill works

The skill queries HubSpot’s engagements/email objects and returns JSON with each record’s id, subject, text preview, direction, status, and timestamp. It supports limit and pagination parameters to control page size and navigate results. The output also includes a paging cursor for fetching subsequent pages.

When to use it

• Quickly review recent sent and received emails for an account or contact
• Audit email history before a sales call or customer meeting
• Fetch a batch of email records for import, reporting, or troubleshooting
• Confirm that outbound emails were logged and determine their status
• Pagination through long email histories when you need more than the default page

Best practices

• Run the pre-flight config check to validate HubSpot credentials and scopes before listing emails
• Start with the default limit, then increase using --limit when you need more records per call
• Use the returned paging.after cursor to reliably paginate through results
• Filter or post-process client-side if you need complex date or sender filtering (the skill returns raw engagement records)
• Handle API errors (401, 403, 429) by re-authorizing, adding scopes, or retrying after backoff

Example use cases

• List the 10 most recent emails related to your CRM to prepare for a customer call
• Fetch 25 emails with --limit 25 for a weekly audit of outreach activity
• Use --after "cursor" to continue retrieving a long archive of logged emails
• Inspect email previews to find follow-up actions or unresolved threads before escalations
• Combine with contact associations to correlate emails with specific contacts or deals