beam-ai-team/heyreach-master

HeyReach Master (Internal)

Internal resource library containing:

• API client (heyreach_client.py)
• Config checker (check_heyreach_config.py)
• All operation scripts
• Reference documentation

---

Architecture: DRY Principle

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.

---

Shared Resources

All HeyReach skills reference these resources (progressive disclosure).

references/

setup-guide.md - Complete setup wizard

• Getting API key from HeyReach
• Environment configuration
• Verifying connection

api-reference.md - HeyReach API patterns

• Base URL and authentication
• All endpoints documented
• Request/response examples
• Pagination patterns

error-handling.md - Troubleshooting

• Common errors and solutions
• HTTP error codes
• Rate limiting
• Debug tips

scripts/

Authentication & Configuration

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:

• Automatic retry with exponential backoff
• Rate limit handling (300 req/min)
• Consistent error responses
• API key management from .env

---

Intelligent Error Detection Flow

When a HeyReach skill fails due to missing configuration, the AI should:

Step 1: Run Config Check with JSON Output

uv run python 00-system/skills/heyreach/heyreach-master/scripts/check_heyreach_config.py --json

Step 2: Parse the 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 |

Step 3: Help User Fix Issues

If ai_action is prompt_for_api_key:

1. Tell user: "HeyReach integration needs setup. I need your API key."
2. Show them: "Get it from HeyReach: Settings → API"
3. Ask: "Paste your HeyReach API key:"
4. Once they provide it, write directly to .env:

   HEYREACH_API_KEY=their-key-here
   

5. Re-run config check to verify

---

Environment Variables

Required in .env:

HEYREACH_API_KEY=your-api-key-here

---

API Base URL

All API requests go to: https://api.heyreach.io/api/public

Authentication header: X-API-KEY: {api_key}

Rate limit: 300 requests/minute

---

Script Usage Patterns

List Campaigns

from heyreach_client import get_client

client = get_client()
result = client.post("/v2/campaigns/All", {"offset": 0, "limit": 100})
campaigns = result.get("items", [])

Get Campaign Details

result = client.get(f"/v2/campaigns/{campaign_id}")

Add Leads

leads = [
    {"linkedInUrl": "https://linkedin.com/in/user1"},
    {"linkedInUrl": "https://linkedin.com/in/user2"}
]
result = client.post(f"/v2/campaigns/{campaign_id}/leads", {"leads": leads})

Error Handling

from heyreach_client import get_client, HeyReachError

try:
    client = get_client()
    result = client.get("/v2/campaigns/123")
except HeyReachError as e:
    print(f"Error {e.status_code}: {e.message}")
except ValueError as e:
    print(f"Config error: {e}")

---

Version: 1.0 Created: 2025-12-19 Status: Production Ready