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

Safety Contract

This shared library may read and mutate HeyReach outreach data. Before scripts create/update campaigns, import leads, change senders, launch outreach, or export data, show the account, campaign target, lead count, payload summary, destination path when used, and expected side effects. Require explicit user approval in the current turn before mutating HeyReach or writing files. Config checks and read-only metric/list operations do not require additional approval after scope is confirmed.

---

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 skills/integrations/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