home / skills / abdullahbeam / nexus-design-abdullah / heyreach-connect

heyreach-connect skill

safe

/00-system/skills/heyreach/heyreach-connect

This skill connects to HeyReach for LinkedIn outreach, validates configuration, and routes to campaigns, leads, and analytics for streamlined automation.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill heyreach-connect

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

Files (1)

SKILL.md

3.1 KB

---
name: heyreach-connect
description: "Connect to HeyReach for LinkedIn automation. Load when user mentions 'heyreach', 'linkedin outreach', 'linkedin campaigns', 'heyreach campaigns', 'add leads', 'campaign stats'. Meta-skill that validates config and routes to operations."
---

# HeyReach Connect

Meta-skill for HeyReach LinkedIn automation integration.

## Trigger Phrases

- "heyreach" / "heyreach campaigns"
- "linkedin outreach" / "linkedin automation"
- "list campaigns" / "show campaigns"
- "campaign stats" / "campaign metrics"
- "add leads to campaign"
- "campaign leads"
- "linkedin accounts"

---

## Pre-Flight Check (ALWAYS RUN FIRST)

```bash
python 00-system/skills/heyreach/heyreach-master/scripts/check_heyreach_config.py --json
```

| `ai_action` | What to Do |
|-------------|------------|
| `proceed_with_operation` | Config OK → Continue |
| `prompt_for_api_key` | Ask user for API key, save to .env |

### Setup Guide

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HEYREACH API SETUP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Log into HeyReach at https://app.heyreach.io
2. Go to Settings → API
3. Copy your API key

Paste your HeyReach API key:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Routing Table

All scripts located in: `00-system/skills/heyreach/heyreach-master/scripts/`

| User Says | Script | Args |
|-----------|--------|------|
| "list campaigns" | list_campaigns.py | `[--limit N] [--json]` |
| "campaign details [X]" | get_campaign.py | `--campaign-id ID [--json]` |
| "pause/resume [campaign]" | toggle_campaign.py | `--campaign-id ID --status ACTIVE\|PAUSED` |
| "add leads to [campaign]" | add_leads.py | `--campaign-id ID --linkedin-urls URLs` |
| "leads in [campaign]" | get_leads.py | `--campaign-id ID [--limit N]` |
| "conversations" | get_conversations.py | `[--campaign-id ID] [--limit N]` |
| "linkedin accounts" | list_accounts.py | `[--json]` |
| "lead lists" | list_lists.py | `[--limit N]` |
| "create list [name]" | create_list.py | `--name NAME` |
| "analytics/stats" | get_stats.py | `[--json]` |
| "metrics for [campaign]" | get_metrics.py | `--campaign-id ID` |

---

## Example Workflows

### List Campaigns
```bash
python 00-system/skills/heyreach/heyreach-master/scripts/list_campaigns.py --json
```

### Add Leads
```bash
python 00-system/skills/heyreach/heyreach-master/scripts/add_leads.py \
  --campaign-id camp-123 \
  --linkedin-urls "linkedin.com/in/user1,linkedin.com/in/user2"
```

### Get Stats
```bash
python 00-system/skills/heyreach/heyreach-master/scripts/get_stats.py --json
```

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid API key - re-run setup |
| 403 | API not available for subscription |
| 404 | Campaign/lead not found |
| 429 | Rate limited (auto-retry) |

---

**Version**: 1.0

Overview

This skill connects to HeyReach to automate LinkedIn outreach and campaign management. It validates configuration, prompts for API credentials if missing, and routes requests to the appropriate HeyReach operations. The skill acts as a meta-layer so you can list campaigns, add leads, fetch metrics, and manage campaign status through simple commands.

How this skill works

On first use it runs a pre-flight configuration check to confirm API access and valid credentials. If the API key is missing or invalid, it prompts you to provide and save the key. For valid configurations it routes user intents (list campaigns, add leads, get stats, toggle campaign state, list accounts/lists) to the corresponding HeyReach API operations and returns structured results or error notices.

When to use it

When you need to list or inspect active LinkedIn outreach campaigns
To add or bulk-import LinkedIn leads into a campaign
When you need campaign-level metrics or overall outreach analytics
To pause or resume a campaign quickly
To view or manage connected LinkedIn accounts and lead lists

Best practices

Always run the initial config validation before performing operations to catch credential or permission issues early
Provide explicit campaign IDs when adding leads or fetching metrics to avoid ambiguity
Supply LinkedIn profile URLs in comma-separated form when importing leads for predictable parsing
Handle rate-limit (429) responses by implementing retries with backoff
Keep API keys secure and rotate keys through HeyReach settings if compromised

Example use cases

List all HeyReach campaigns to review active outreach workflows and messaging sequences
Add multiple LinkedIn profile URLs to a target campaign for a new lead batch
Fetch campaign metrics to evaluate send rates, replies, and conversion performance
Pause a campaign that is underperforming or being reformatted, then resume after updates
List connected LinkedIn accounts to confirm the sending identity and permissions

FAQ

What happens if the API key is invalid?

The skill will detect the invalid key during the pre-flight check and prompt you to provide a valid API key; common HTTP 401 errors indicate a bad key.

How are rate limits handled?

Rate-limit responses are surfaced and trigger auto-retry behavior with backoff; you should also implement client-side retry logic for heavy operations.