# beehiiv

## Prerequisites

Before using beehiiv components in Appmixer, you need:

1. A beehiiv account on the **Scale plan ($49/mo)** or higher — the free Launch plan does not include API access
2. An API key generated from the beehiiv dashboard
3. **Owner** or **Admin** role in your beehiiv workspace

***

## 1. Create a beehiiv Account

Sign up at <https://app.beehiiv.com/signup>.

{% hint style="warning" %}
API access is only available on the **Scale plan** ($49/month) or higher. The free Launch plan does not include API access.
{% endhint %}

## 2. Generate an API Key

1. Log into your beehiiv account at <https://app.beehiiv.com>
2. Scroll down to **Workspace Settings** in the left sidebar
3. Click **API**
4. Click **Create New Key**
5. Enter a name for the key (e.g., "Appmixer Integration")
6. Click **Create New Key**
7. Copy the generated API key immediately

{% hint style="warning" %}
The API key is **only shown once** at the time of creation. Make sure to copy and store it in a secure location before closing the dialog.
{% endhint %}

{% hint style="info" %}
You must have an **Owner** or **Admin** role in your workspace to access API key settings.
{% endhint %}

## 3. Connect in Appmixer

When adding a beehiiv component in Appmixer, you will be prompted to authenticate. Provide:

| Field       | Value                           |
| ----------- | ------------------------------- |
| **API Key** | The API key generated in Step 2 |

The API key is used as a Bearer token for all requests to the beehiiv API (`https://api.beehiiv.com/v2`).

***

## Available Components

### Actions

| Component            | Description                               |
| -------------------- | ----------------------------------------- |
| **CreateSubscriber** | Create a new subscriber for a publication |
| **GetSubscriber**    | Retrieve a subscriber by ID               |
| **FindSubscriber**   | Find a subscriber by email address        |
| **ListSubscribers**  | List all subscribers of a publication     |
| **UpdateSubscriber** | Update an existing subscriber             |
| **DeleteSubscriber** | Remove a subscriber (unsubscribe)         |
| **CreatePost**       | Create a new newsletter post              |
| **GetPost**          | Retrieve a post by ID                     |
| **ListPosts**        | List all posts of a publication           |
| **ListPublications** | List all publications in the workspace    |
| **ListAutomations**  | List automations for a publication        |
| **ListCustomFields** | List custom fields of a publication       |
| **ListSegments**     | List segments of a publication            |

### Triggers

| Component                   | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| **NewSubscriber**           | Triggers when a new subscriber signs up               |
| **SubscriberConfirmed**     | Triggers when a subscriber confirms via double opt-in |
| **SubscriberDeleted**       | Triggers when a subscriber unsubscribes               |
| **SubscriberUpgraded**      | Triggers when a subscriber upgrades to premium        |
| **SubscriberDowngraded**    | Triggers when a subscriber downgrades from premium    |
| **PostSent**                | Triggers when a post is published/sent                |
| **PostUpdated**             | Triggers when a post is updated                       |
| **SurveyResponseSubmitted** | Triggers when a survey response is submitted          |

## Troubleshooting

### "Authentication failed: Invalid API key"

The API key is incorrect or has been revoked. Generate a new API key from **Workspace Settings > API** in the beehiiv dashboard.

### No publications returned

Make sure your API key has access to at least one publication. The beehiiv API scopes all operations under a publication — most components require a Publication ID.

### "403 Forbidden" errors

Your beehiiv plan may not include API access. Verify you are on the **Scale plan** ($49/mo) or higher.