heyreach_skill

Overview

This skill is an internal HeyReach resource library that centralizes shared API client code, operation scripts, and reference documentation for all HeyReach integrations. It reduces duplication across skills by providing a single source of truth for setup, auth, error handling, and common operations. Use it to validate configuration, run common API calls, and follow troubleshooting flow for integration failures.

How this skill works

The library exposes a pre-built API client (heyreach_client.py) with automatic retries, rate-limit handling, and consistent error types. A configuration checker script inspects environment variables and returns structured JSON ai_action directives to guide the next steps. Reference docs cover setup, endpoints, request/response examples, pagination, and error troubleshooting.

When to use it

• Run the config checker before any HeyReach operation to verify API key and network access.
• Use the shared API client for list, get, and write operations to ensure consistent retries and rate-limit behavior.
• Follow the Intelligent Error Detection Flow when an integration fails to diagnose and fix auth or network issues.
• Reference the setup and API docs when onboarding a new HeyReach skill or updating endpoints.
• Use the scripts to automate pre-flight checks in CI or developer workflows.

Best practices

• Always run check_heyreach_config.py --json as the first step and parse ai_action to decide next actions.
• Store HEYREACH_API_KEY in a .env file and use the provided client which reads .env automatically.
• Handle HeyReachError exceptions from the client and surface status_code and message to users or logs.
• Respect the documented rate limit (300 req/min) and rely on the client's backoff logic for retries.
• Re-run the config checker after making config changes to confirm resolution.

Example use cases

• Validate integration readiness in a CI job by running the config checker and failing early on missing credentials.
• List campaigns programmatically using the shared client: client.post('/v2/campaigns/All', {...}).
• Add leads to a campaign with client.post('/v2/campaigns/{id}/leads', {'leads': [...]}) while relying on automatic retry and rate-limit handling.
• Troubleshoot auth failures by following ai_action from the config checker: prompt for API key, create .env, or verify the key.
• Implement user-facing prompts that ask for the HeyReach API key and then write HEYREACH_API_KEY to .env before re-checking.