beam-ai-team/heyreach-connect

HeyReach Connect

Meta-skill for HeyReach LinkedIn automation integration.

Safety Contract

Before creating/updating campaigns, importing leads, changing sender accounts, launching outreach, or exporting campaign data, show the workspace/account, campaign ID/name, lead count, payload summary, destination path, and expected external side effects. Require explicit user approval in the current turn before mutating HeyReach or writing files. Listing campaigns and reading metrics with an approved scope do not require additional approval.

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)

uv run python skills/integrations/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: skills/integrations/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

uv run python skills/integrations/heyreach/heyreach-master/scripts/list_campaigns.py --json

Add Leads

uv run python skills/integrations/heyreach/heyreach-master/scripts/add_leads.py \
  --campaign-id camp-123 \
  --linkedin-urls "linkedin.com/in/user1,linkedin.com/in/user2"

Get Stats

uv run python skills/integrations/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