clawdbot-beehiiv

A Clawdbot plugin for AI-powered beehiiv newsletter management. Manage publications, subscribers, posts, segments, automations, and get powerful analytics insights.

Features

• 30 tools for comprehensive newsletter management
• Custom analytics for subscriber growth, engagement trends, and churn analysis
• Bulk operations for efficient subscriber management
• Full API coverage including webhooks, automations, and premium tiers

Installation

npm install clawdbot-beehiiv

Or add to your Clawdbot configuration.

Configuration

Add to your Clawdbot plugin configuration:

{
  "plugins": {
    "beehiiv": {
      "apiKey": "your-beehiiv-api-key",
      "defaultPublicationId": "pub_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "paginationLimit": 50
    }
  }
}

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your beehiiv API key from Settings > Integrations > API | | defaultPublicationId | string | No | Default publication ID for operations | | paginationLimit | number | No | Results per page (1-100, default: 50) |

Tools

Publications (2)

| Tool | Description | |------|-------------| | beehiiv_list_publications | List all publications with optional stats | | beehiiv_get_publication | Get publication details by ID |

Subscriptions (7)

| Tool | Description | |------|-------------| | beehiiv_list_subscriptions | List subscribers with filtering | | beehiiv_get_subscription | Get subscriber by ID or email | | beehiiv_create_subscription | Create new subscriber | | beehiiv_update_subscription | Update subscriber details | | beehiiv_delete_subscription | Remove subscriber | | beehiiv_bulk_create_subscriptions | Bulk import subscribers | | beehiiv_add_subscription_tag | Add tag to subscriber |

Posts (4)

| Tool | Description | |------|-------------| | beehiiv_list_posts | List posts with filtering | | beehiiv_get_post | Get post with stats | | beehiiv_create_post | Create post (Enterprise only) | | beehiiv_delete_post | Delete a post |

Segments (4)

| Tool | Description | |------|-------------| | beehiiv_list_segments | List all segments | | beehiiv_get_segment | Get segment details | | beehiiv_get_segment_subscribers | List subscribers in segment | | beehiiv_delete_segment | Delete a segment |

Automations (3)

| Tool | Description | |------|-------------| | beehiiv_list_automations | List all automations | | beehiiv_get_automation | Get automation details | | beehiiv_add_to_automation | Add subscriber to automation |

Custom Fields (3)

| Tool | Description | |------|-------------| | beehiiv_list_custom_fields | List custom fields | | beehiiv_create_custom_field | Create custom field | | beehiiv_delete_custom_field | Delete custom field |

Tiers (2)

| Tool | Description | |------|-------------| | beehiiv_list_tiers | List premium tiers | | beehiiv_get_tier | Get tier details |

Referrals (1)

| Tool | Description | |------|-------------| | beehiiv_get_referral_program | Get referral program details |

Webhooks (4)

| Tool | Description | |------|-------------| | beehiiv_list_webhooks | List webhooks | | beehiiv_create_webhook | Create webhook | | beehiiv_update_webhook | Update webhook | | beehiiv_delete_webhook | Delete webhook |

Analytics (6)

| Tool | Description | |------|-------------| | beehiiv_analyze_subscriber_growth | Analyze growth trends | | beehiiv_analyze_post_performance | Compare post metrics | | beehiiv_analyze_engagement_trends | Track engagement over time | | beehiiv_top_performing_posts | Rank posts by metric | | beehiiv_subscriber_acquisition_report | UTM source breakdown | | beehiiv_churn_analysis | Analyze unsubscribe patterns |

Usage Examples

List Publications with Stats

"Show me all my beehiiv publications with subscriber counts"

Find a Subscriber

"Look up subscriber [email protected] and show their engagement stats"

Add New Subscribers

"Add these emails to my newsletter: [email protected], [email protected]"

Analyze Performance

"What are my top performing posts by open rate?"
"Show me my subscriber growth over the last 30 days"
"Is my newsletter engagement trending up or down?"

Manage Segments

"List all my segments with subscriber counts"
"Show me subscribers in the 'VIP' segment"

API Reference

This plugin uses the beehiiv API v2. Key details:

• Base URL: https://api.beehiiv.com/v2
• Authentication: Bearer token
• Rate Limiting: Automatic retry with exponential backoff

Expand Options

Most list and get operations support expand parameters:

Publications:

• stats, stat_active_subscriptions, stat_average_open_rate, stat_average_click_rate, stat_total_sent

Subscriptions:

• stats, custom_fields, referrals, subscription_premium_tiers, tags

Posts:

• stats, free_web_content, free_email_content, premium_web_content, premium_email_content

Segments:

• stats

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.