majiayu000 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
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
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:
- Tell user: "HeyReach integration needs setup. I need your API key."
- Show them: "Get it from HeyReach: Settings → API"
- Ask: "Paste your HeyReach API key:"
- Once they provide it, write directly to
.env:HEYREACH_API_KEY=their-key-here - 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