playbooks

home / skills / abdullahbeam / nexus-design-abdullah / hubspot-log-email

hubspot-log-email skill

/00-system/skills/hubspot/hubspot-log-email

This skill logs email engagements into HubSpot by recording subject, body, direction, and timestamp to track interactions.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-log-email

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

Files (1)
SKILL.md
2.0 KB
---
name: hubspot-log-email
description: "Log an email engagement in HubSpot CRM. Load when user says 'log email', 'record email', 'add email', 'email sent'. Requires subject and body."
---

# Log HubSpot Email

**Specialized skill** for logging email engagements in 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

### Required Parameters
- `--subject` - Email subject line (required)
- `--body` - Email body content (required)

### Optional Parameters
- `--direction` - EMAIL (sent) or INCOMING_EMAIL (received)
- `--timestamp` - ISO timestamp (defaults to now)

### Examples

**Log sent email:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/log_email.py \
  --subject "Follow up on proposal" \
  --body "Hi John, following up on our conversation about the enterprise package..." \
  --json
```

**Log received email:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/log_email.py \
  --subject "Re: Proposal" \
  --body "Thanks for sending over the details..." \
  --direction "INCOMING_EMAIL" \
  --json
```

---

## Output Format

```json
{
  "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"
  }
}
```

---

## Display Format

```
āœ… Email logged!
  ID: 14389550562
  Subject: Follow up on proposal
  Direction: Sent
  Status: SENT
  Timestamp: 2025-12-13 10:00
```

---

## Error Handling

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

---

## Related Skills

- `hubspot-list-emails` - List all emails
- `hubspot-get-associations` - Link email to contact

Overview

This skill logs an email engagement in HubSpot CRM using required subject and body fields. It supports marking direction (sent or incoming) and optional timestamp to record when the email occurred. The skill returns a HubSpot email record ID and key properties for verification. It is designed for quick, scriptable recording of email activity into HubSpot.

How this skill works

The skill accepts subject and body as required inputs and optional direction (EMAIL or INCOMING_EMAIL) and timestamp (ISO format). It validates configuration and HubSpot scopes, then calls the HubSpot Emails API to create a logged email engagement. On success it returns the created record with properties like subject, text, direction, status, and timestamp. Errors map to clear remediation steps for token, scope, and rate limits.

When to use it

  • You need to record an outbound email you sent into HubSpot for activity history.
  • You received an email and want to log the incoming message against CRM records.
  • Automate email logging from other systems or scripts to keep contact timelines complete.
  • Batch or scripted workflows that generate email activity without sending through HubSpot.
  • When you want a timestamped, searchable email object stored in HubSpot CRM.

Best practices

  • Always run the pre-flight config check to validate API keys and scopes before logging emails.
  • Provide a concise, descriptive subject and the full body to preserve searchable context.
  • Use ISO timestamps when logging historical messages to maintain accurate timelines.
  • Prefer explicit direction values (EMAIL or INCOMING_EMAIL) to ensure correct status mapping.
  • Handle API errors: refresh tokens on 401, request proper scopes on 403, and implement retry/backoff for 429 responses.

Example use cases

  • Record a follow-up email sent after a sales call so the contact timeline is complete.
  • Log a customer reply received via external mail system into HubSpot as an incoming email activity.
  • Integrate with support tooling to create an email activity when agents respond outside the CRM.
  • Automate nightly scripts that ingest outbound email logs from your mail server into HubSpot for compliance.
  • Attach timestamped historical correspondence to contacts during CRM data migration.

FAQ

What parameters are required to log an email?

Subject and body are required. Direction and timestamp are optional; direction defaults to sent if omitted.

What should I do if I get a 403 error?

Ensure the API token includes the crm.objects.emails.write scope. Re-run the configuration steps to grant the required scopes.