heyreach

Package Information

Released: 6/30/2025
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0-beta
Author: bcharleson

Available Nodes

HeyReach
Interact with HeyReach API for LinkedIn automation

Documentation

n8n-nodes-heyreach

HeyReach Logo

A comprehensive n8n community node for HeyReach - the LinkedIn automation platform that helps you scale your outreach campaigns with advanced targeting and personalization.

npm version
License: MIT
GitHub issues

🚀 What is this?

This node allows you to create, retrieve, and manage your HeyReach LinkedIn automation resources directly from n8n workflows. It provides robust error handling, comprehensive API coverage, and seamless integration with HeyReach's powerful LinkedIn automation platform.

Perfect for:

  • Automating LinkedIn outreach campaigns
  • Managing leads and prospect lists
  • Analyzing campaign performance
  • Integrating LinkedIn automation with your existing workflows
  • Building sophisticated lead nurturing sequences

✨ Features

  • Complete API Coverage: Access all major HeyReach resources (Campaigns, Leads, Lists, Analytics, Conversations, Network)
  • Smart Error Handling: Intelligent handling of HeyReach API quirks and edge cases
  • Production Ready: Thoroughly tested with comprehensive error handling
  • Easy Setup: Simple authentication with API key
  • Rich Documentation: Extensive examples and troubleshooting guides

📦 Installation

Community Nodes (Recommended)

For users on n8n v0.187.0+, you can install this node directly through the n8n interface:

  1. Go to Settings > Community Nodes in your n8n instance
  2. Click Install
  3. Enter n8n-nodes-heyreach and click Download
  4. Restart your n8n instance
  5. The HeyReach node will appear in your node palette

Manual Installation

For self-hosted n8n instances:

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the node
npm install n8n-nodes-heyreach

# Restart n8n

Docker Installation

For Docker-based n8n installations:

# Add to your Dockerfile or docker-compose.yml
RUN npm install -g n8n-nodes-heyreach

# Or install at runtime
docker exec -it n8n npm install n8n-nodes-heyreach

Requirements

  • n8n version 0.187.0 or higher
  • Node.js 18.10.0 or higher
  • Valid HeyReach account with API access

🔧 Setup & Authentication

Getting Your HeyReach API Key

  1. Log into HeyReach: Visit app.heyreach.io and sign in
  2. Navigate to API Settings: Go to Settings → API Keys
  3. Generate API Key: Click "Generate New API Key" or copy your existing key
  4. Copy the Key: Save this key securely - you'll need it for n8n

Creating n8n Credentials

  1. Add Credential: In n8n, go to Credentials → Add Credential
  2. Select Type: Search for and select "HeyReach API"
  3. Enter API Key: Paste your HeyReach API key
  4. Test Connection: Click "Test" to verify the connection works
  5. Save: Give your credential a name and save it

Quick Start

Once authenticated, you can:

  • Manage Campaigns: Pause, resume, and monitor your LinkedIn outreach campaigns
  • Handle Leads: Add leads to campaigns, manage tags, and track interactions
  • Organize Lists: Create and manage prospect lists for targeted outreach
  • Analyze Performance: Get detailed analytics on campaign and lead performance
  • Monitor Conversations: Track LinkedIn conversations and responses
  • Manage Network: Access and analyze your LinkedIn network connections

🎯 Available Operations

This node provides comprehensive access to HeyReach's LinkedIn automation platform:

📊 Campaign Management

Perfect for managing your LinkedIn outreach campaigns:

  • Get Campaign: Retrieve detailed information about a specific campaign
  • Get Many Campaigns: List all campaigns with advanced filtering options
  • Pause Campaign: Safely pause active campaigns (with intelligent error handling)
  • Resume Campaign: Resume paused campaigns to continue outreach
  • Add Leads to Campaign: Seamlessly add leads to your outreach campaigns

👥 Lead Operations

Comprehensive lead management capabilities:

  • Get Lead: Retrieve lead details by LinkedIn profile URL
  • Add Tags: Add organizational tags to leads for better categorization
  • Get Tags: Retrieve all tags associated with a lead

📋 List Management

Organize and manage your prospect lists:

  • Get Many Lists: Retrieve all your prospect lists with metadata
  • Create List: Create new targeted prospect lists
  • Add Leads to List: Add leads to existing lists for organization

📈 Analytics & Insights

Data-driven insights for campaign optimization:

  • Get Overall Stats: Comprehensive campaign performance metrics including:
    • Response rates and engagement metrics
    • Date range filtering for trend analysis
    • Account-specific analytics
    • Daily performance breakdowns

💬 Conversation Management

Monitor and manage LinkedIn conversations:

  • Get Many Conversations: Access LinkedIn conversations with advanced filtering:
    • Filter by read/unread status
    • Filter by specific campaigns
    • Filter by LinkedIn account
    • Filter by message types and date ranges

🌐 Network Operations

Manage and analyze your LinkedIn network:

  • Get Network for Sender: Access LinkedIn network data with:
    • Advanced search capabilities
    • Company and location filtering
    • Connection level filtering (1st, 2nd, 3rd degree)
    • Profile completeness scoring

💡 Usage Examples

Example 1: Campaign Performance Monitoring

Monitor your campaign performance and automatically pause underperforming campaigns:

{
  "nodes": [
    {
      "name": "Get Campaign Analytics",
      "type": "n8n-nodes-heyreach.heyReachApi",
      "parameters": {
        "resource": "analytics",
        "operation": "getOverallStats",
        "campaignId": "12345",
        "dateFrom": "2024-01-01",
        "dateTo": "2024-01-31"
      }
    },
    {
      "name": "Check Performance",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "number": [
            {
              "value1": "={{ $json.responseRate }}",
              "operation": "smaller",
              "value2": 5
            }
          ]
        }
      }
    },
    {
      "name": "Pause Low-Performing Campaign",
      "type": "n8n-nodes-heyreach.heyReachApi",
      "parameters": {
        "resource": "campaign",
        "operation": "pause",
        "campaignId": "12345"
      }
    }
  ]
}

Example 2: Automated Lead Management

Automatically add new leads from a CRM to HeyReach campaigns:

{
  "nodes": [
    {
      "name": "Get New Leads from CRM",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://your-crm.com/api/leads",
        "method": "GET"
      }
    },
    {
      "name": "Add Leads to HeyReach Campaign",
      "type": "n8n-nodes-heyreach.heyReachApi",
      "parameters": {
        "resource": "campaign",
        "operation": "addLeads",
        "campaignId": "67890",
        "leads": "={{ $json.leads }}"
      }
    }
  ]
}

Example 3: Conversation Management

Monitor and respond to LinkedIn conversations:

{
  "nodes": [
    {
      "name": "Get Unread Conversations",
      "type": "n8n-nodes-heyreach.heyReachApi",
      "parameters": {
        "resource": "conversation",
        "operation": "getMany",
        "filters": {
          "isRead": false
        }
      }
    },
    {
      "name": "Process Each Conversation",
      "type": "n8n-nodes-base.splitInBatches",
      "parameters": {
        "batchSize": 10
      }
    }
  ]
}

API Documentation

For detailed API documentation, visit: https://documenter.getpostman.com/view/23808049/2sA2xb5F75

Rate Limits

HeyReach API allows a maximum of 300 requests per minute. The node includes automatic rate limit handling.

🔧 Troubleshooting

Common Issues

Campaign Pause/Resume Errors

Issue: Getting "You cannot pause an inactive campaign" error
Solution: This node includes smart error handling that automatically verifies if the campaign was actually paused despite the API error. The operation will succeed if the campaign status changes correctly.

API Rate Limits

Issue: Receiving rate limit errors
Solution: The node includes automatic rate limiting (300 requests/minute). If you hit limits, the node will automatically retry with exponential backoff.

Authentication Errors

Issue: "Invalid API key" or authentication failures
Solution:

  1. Verify your API key in HeyReach Settings > API Keys
  2. Ensure the credential is properly saved in n8n
  3. Test the connection using the "Test" button in credentials

Node Not Appearing

Issue: HeyReach node doesn't appear in n8n node palette
Solution:

  1. Restart your n8n instance after installation
  2. Clear browser cache (Cmd+Shift+R)
  3. Check n8n logs for installation errors

Debug Mode

Enable debug logging by setting the environment variable:

export N8N_LOG_LEVEL=debug

🛠️ Development Setup

Prerequisites

  • Node.js 18.10.0 or higher
  • npm or yarn
  • n8n development environment

Local Development

  1. Clone the repository:

    git clone https://github.com/bcharleson/n8n-nodes-heyreach.git
cd n8n-nodes-heyreach

  2. Install dependencies:

    npm install

  3. Build the node:

    npm run build

  4. Link for local testing:

    # Link the package globally
npm link

# In your n8n installation directory
npm link n8n-nodes-heyreach

  5. Start n8n in development mode:

    n8n start --tunnel

Docker Development

For Docker-based development with hot-reloading:

# Build the node
npm run build

# Run n8n with volume mounting
docker run -d \
  --name n8n-heyreach-dev \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v $(pwd):/home/node/.n8n/nodes/node_modules/n8n-nodes-heyreach \
  n8nio/n8n:latest

Testing

Run the test suite:

npm test

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Build and test: npm run build && npm test
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

📚 Documentation

Comprehensive documentation is available in the /docs folder:

Support

For issues and feature requests, please visit: https://github.com/bcharleson/n8n-nodes-heyreach

Development Status

This package is production-ready:

  • ✅ Phase 1 Complete: Foundation, authentication, and structure
  • ✅ Phase 2 Complete: Core resources (Campaign, Lead, List) with 9 operations
  • ✅ Phase 3 Complete: Analytics and advanced features (Conversation, Network, Analytics) with 6 additional operations
  • ✅ Phase 4 Complete: Testing, documentation, and production readiness validation

🚀 Ready for production use with comprehensive LinkedIn automation capabilities.

License

MIT

📋 Contributing

We welcome contributions to improve the HeyReach n8n node! Here's how you can help:

🐛 Bug Reports

If you encounter any issues:

  1. Check existing issues first
  2. Create a detailed bug report with:
    • Steps to reproduce
    • Expected vs actual behavior
    • n8n version and node version
    • Error messages or logs

💡 Feature Requests

Have an idea for improvement?

  1. Check if it's already been requested
  2. Open a feature request with:
    • Clear description of the feature
    • Use case and benefits
    • Any relevant HeyReach API documentation

🔧 Pull Requests

Ready to contribute code?

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Build and test: npm run build && npm test
  5. Commit with clear messages: git commit -m 'Add amazing feature'
  6. Push to your branch: git push origin feature/amazing-feature
  7. Open a Pull Request with detailed description

📞 Support

  • GitHub Issues: For bugs and feature requests
  • Documentation: Check the /docs folder for detailed guides
  • Community: Share your workflows and get help from other users

📊 Version History

0.1.0-beta - Initial Beta Release

  • 🎯 Complete HeyReach API integration with 15 operations across 6 resources
  • 🔐 Secure authentication with X-API-KEY and comprehensive credential validation
  • 📊 Campaign management (get, getMany, pause, resume, addLeads) with intelligent status validation
  • 👥 Lead management (getLead, addTags, getTags) with LinkedIn profile validation
  • 📋 List management (getMany, create, addLeadsToList) with flexible input modes
  • 📈 Analytics with date range filtering, metrics selection, and daily breakdowns
  • 💬 Conversation management with comprehensive filtering and computed fields
  • 🌐 Network access with search, filtering, and profile completeness scoring
  • 🛡️ Robust error handling for all HeyReach API limitations and edge cases
  • 📚 Complete documentation with usage examples, troubleshooting, and parameter reference
  • 🚀 Production-ready with full TypeScript support and n8n best practices
  • ✅ Comprehensive testing and validation for all operations

Discussion