Internal resource library for HeyReach integration. Contains shared API client, operation scripts, and reference documentation.
Internal resource library containing:
heyreach_client.py)check_heyreach_config.py)Problem solved: HeyReach skills would have duplicated content (setup instructions, API docs, auth flow, error handling).
Solution: Extract shared content into heyreach-master/references/ and heyreach-master/scripts/, then reference from each skill.
Result: Single source of truth, reduced context per skill.
All HeyReach skills reference these resources (progressive disclosure).
setup-guide.md - Complete setup wizard
api-reference.md - HeyReach API patterns
error-handling.md - Troubleshooting
check_heyreach_config.py - Pre-flight validation
uv run python check_heyreach_config.py [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--json | No | False | Output structured JSON for AI consumption |
Exit codes: 0=configured, 1=partial, 2=not configured
When to Use: Run this FIRST before any HeyReach operation. Use to validate API key is configured, diagnose authentication issues, or check if setup is needed.
heyreach_client.py - Shared API client
from heyreach_client import get_client, HeyReachError
client = get_client()
result = client.post("/v2/campaigns/All", {"offset": 0, "limit": 100})
Features:
When a HeyReach skill fails due to missing configuration, the AI should:
uv run python 00-system/skills/heyreach/heyreach-master/scripts/check_heyreach_config.py --json
ai_action Field| ai_action | What to Do |
|---|---|
proceed_with_operation | Config OK, continue with the original operation |
prompt_for_api_key | Ask user: "I need your HeyReach API key from Settings → API" |
create_env_file | Create .env file and ask user for credentials |
verify_api_key | Key exists but connection failed - verify it's correct |
retry_later | API timeout - try again |
check_network | Connection error - verify network |
If ai_action is prompt_for_api_key:
.env:
HEYREACH_API_KEY=their-key-here
Required in .env:
HEYREACH_API_KEY=your-api-key-here
All API requests go to: https://api.heyreach.io/api/public
Authentication header: X-API-KEY: {api_key}
Rate limit: 300 requests/minute
from heyreach_client import get_client
client = get_client()
result = client.post("/v2/campaigns/All", {"offset": 0, "limit": 100})
campaigns = result.get("items", [])
result = client.get(f"/v2/campaigns/{campaign_id}")
leads = [
{"linkedInUrl": "https://linkedin.com/in/user1"},
{"linkedInUrl": "https://linkedin.com/in/user2"}
]
result = client.post(f"/v2/campaigns/{campaign_id}/leads", {"leads": leads})
from heyreach_client import get_client, HeyReachError