playbooks

home / skills / abdullahbeam / nexus-design-abdullah / hubspot-list-emails

hubspot-list-emails skill

/00-system/skills/hubspot/hubspot-list-emails

This skill lists HubSpot email engagements from your CRM, returning recent emails with subject, preview, and status to inform follow-ups.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-list-emails

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: hubspot-list-emails
description: "List email engagements from HubSpot CRM. Load when user says 'list emails', 'show emails', 'email history', 'hubspot emails'. Returns logged email records."
---

# List HubSpot Emails

**Specialized skill** for listing email engagements from HubSpot CRM.

## Pre-Flight Check

Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.

---

## Usage

### Basic List (default 10 emails)
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_emails.py --json
```

### With Limit
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_emails.py --limit 25 --json
```

### With Pagination
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_emails.py --after "cursor_value" --json
```

---

## Output Format

```json
{
  "results": [
    {
      "id": "14389550562",
      "properties": {
        "hs_email_subject": "Follow up on proposal",
        "hs_email_text": "Hi John, following up on...",
        "hs_email_direction": "EMAIL",
        "hs_email_status": "SENT",
        "hs_timestamp": "2025-12-13T10:00:00Z"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}
```

---

## Display Format

```
Found {count} emails:

1. Follow up on proposal
   Direction: Sent
   Status: SENT
   Date: 2025-12-13 10:00
   Preview: Hi John, following up on...
   ID: 14389550562

2. Re: Demo request
   Direction: Received
   ...
```

---

## Email Direction Values

| Value | Meaning |
|-------|---------|
| EMAIL | Outbound (sent) |
| INCOMING_EMAIL | Inbound (received) |
| FORWARDED_EMAIL | Forwarded |

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.emails.read` scope |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-log-email` - Log new email
- `hubspot-get-associations` - Get email's linked contacts

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

FAQ

What fields are returned for each email?

Each record includes id, hs_email_subject, hs_email_text (preview), hs_email_direction, hs_email_status, and hs_timestamp.

How do I retrieve more emails than the default?

Use the --limit flag to increase page size and use the paging.next.after cursor to request the next page.

What do direction values mean?

EMAIL means outbound/sent, INCOMING_EMAIL means inbound/received, and FORWARDED_EMAIL means a forwarded message.

How should I handle authentication errors?

Run the config check and re-run hubspot connect setup if ai_action is not proceed_with_operation; fix missing scopes or refresh tokens for 401/403 issues.