# Heyreach — how to use (mcp.ai)

Connect your Heyreach account and use 19 tools for marketing automation straight from your AI agent. Connect with your own API key. HeyReach is a multichannel outreach platform designed to help businesses and professionals engage with their audience effectively.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_heyreach?ms=1787291340000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `heyreach_add_leads_to_list_v2`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/heyreach`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/heyreach/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/heyreach/add/leads/to/list/v2` — Tool to add leads to a lead list in HeyReach for LinkedIn campaigns. Accepts up to 100 leads per request and returns counts of added, updated, and failed leads.
  - body: { leads: object[], listId: integer }
- `POST https://api.mcp.ai/api/heyreach/check/api/key` — Tool to check if the API key is valid. Use before making other API calls to confirm authentication.
- `POST https://api.mcp.ai/api/heyreach/create/empty/list` — Tool to create an empty list. Use after deciding on the list name and type.
  - body: { name: string, type?: string }
- `POST https://api.mcp.ai/api/heyreach/create/tags` — Tool to create one or multiple tags for your workspace. Use when you need to organize leads with custom labels.
  - body: { tags: object[] }
- `POST https://api.mcp.ai/api/heyreach/create/webhook` — Tool to create a new webhook. Use when you need programmatic callbacks for HeyReach events after confirming a valid API key.
  - body: { eventType: string, webhookUrl: string, campaignIds?: integer[], webhookName: string }
- `POST https://api.mcp.ai/api/heyreach/delete/webhook` — Tool to delete an existing webhook. Use when you need to remove callbacks for outdated or unwanted webhooks.
  - body: { webhookId: string }
- `POST https://api.mcp.ai/api/heyreach/get/all/campaigns` — Tool to retrieve all campaigns. Use when you need a paginated list of campaigns for management or reporting.
  - body: { limit?: integer, offset?: integer, keyword?: string, statuses?: string[], accountIds?: integer[] }
- `POST https://api.mcp.ai/api/heyreach/get/all/leads` — Tool to retrieve all leads in a HeyReach list. Use when you need paginated collection of leads after confirming a valid API key.
  - body: { limit?: integer, listId: integer, offset?: integer, keyword?: string, createdTo?: string, createdFrom?: string, leadLinkedInId?: string, leadProfileUrl?: string }
- `POST https://api.mcp.ai/api/heyreach/get/all/linkedin/accounts` — Tool to retrieve all LinkedIn accounts. Use when you need a paginated list of LinkedIn accounts after confirming a valid API key.
  - body: { limit?: integer, offset?: integer, keyword?: string }
- `POST https://api.mcp.ai/api/heyreach/get/all/lists` — Tool to retrieve all lists. Use when you need a paginated list of lists after confirming a valid API key.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/heyreach/get/all/webhooks` — Tool to retrieve all webhooks. Use when you need a paginated collection of webhooks after confirming a valid API key.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/heyreach/get/companies/from/list` — Tool to get companies from a company list. Use when you need a paginated list of companies after specifying a list ID.
  - body: { limit?: integer, listId: integer, offset?: integer, keyword?: string }
- `POST https://api.mcp.ai/api/heyreach/get/conversations/v2` — Tool to retrieve paginated LinkedIn conversations with advanced filters. Use when you need to fetch inbox conversations filtered by lead or profile details.
  - body: { limit?: integer, offset?: integer, filters: object }
- `POST https://api.mcp.ai/api/heyreach/get/lead` — Tool to retrieve detailed information for a lead by profile URL. Use after obtaining the exact LinkedIn profile URL to fetch full lead details.
  - body: { profileUrl: string }
- `POST https://api.mcp.ai/api/heyreach/get/lists/for/lead` — Tool to retrieve all lists that contain a specific lead by profile URL. Use when you need to find which lists a lead belongs to.
  - body: { limit?: integer, offset?: integer, profileUrl: string }
- `POST https://api.mcp.ai/api/heyreach/get/my/network/for/sender` — Tool to get the LinkedIn network for a specified sender account. Use when you need to retrieve paginated connections for a sender.
  - body: { pageSize: integer, senderId: integer, pageNumber: integer }
- `POST https://api.mcp.ai/api/heyreach/get/overall/stats` — Tool to get overall statistics for LinkedIn accounts and campaigns. Use when you need performance metrics including connection requests, messages, replies, and engagement rates for specified date rang
  - body: { dateTo?: string, dateFrom?: string, accountIds?: integer[], campaignIds?: integer[] }
- `POST https://api.mcp.ai/api/heyreach/get/webhook/by/id` — Tool to retrieve a webhook by its ID. Use when you need detailed configuration of a specific webhook after listing or creating it.
  - body: { webhookId: integer }
- `POST https://api.mcp.ai/api/heyreach/update/webhook` — Tool to update an existing webhook’s configuration. Use when you need to modify a webhook's name, URL, event type, campaigns, or activation status after confirming the webhookId.
  - body: { isActive?: boolean, eventType?: string, webhookId: string, webhookUrl?: string, campaignIds?: integer[], webhookName?: string }

## Example prompts
- "What can I do in Heyreach?"
- "Show me a summary of my Heyreach account"

## More
- Page: https://mcp.ai/heyreach
- Agent spec (llms.txt): https://mcp.ai/heyreach/llms.txt
- Postman collection: https://mcp.ai/heyreach/postman.json