
beehiiv
tap-beehiiv (meltanolabs variant)
beehiiv is a newsletter platform. Publishers use it to write and send newsletters, manage subscribers, and earn from ads and paid subscriptions.
This tap extracts publications, posts, subscriptions, ad network reports, daily engagement and publication settings such as authors, segments and tiers.
Prerequisites
API Key: In beehiiv, create an API key in the API settings of your workspace. The tap reads every publication that the key can access, unless you set Publication IDs. The rate limit depends on your beehiiv plan and applies per key, so use a key for the tap only.
Available Streams
A new publication is synced with no change to the configuration. Every record of a
publication stream has a publication_id column.
| Stream | Description | Replication | Replication Key | Primary Key |
|---|---|---|---|---|
publications | Publications that the API key can access, with all-time stats | Full Table | — | id |
posts | Posts, with all-time stats | Full Table | — | publication_id, id |
subscriptions | Subscribers, with all-time stats | Full Table | — | publication_id, id |
ad_network_reports | Ad network revenue for each post and ad link | Full Table | — | publication_id, post_id, ad_link_id |
engagements | Daily opens and clicks | Incremental | date | publication_id, date |
authors | Post authors | Full Table | — | publication_id, id |
automations | Automations | Full Table | — | publication_id, id |
custom_fields | Subscriber custom field definitions | Full Table | — | publication_id, id |
newsletter_lists | Newsletter lists | Full Table | — | publication_id, id |
polls | Polls | Full Table | — | publication_id, id |
post_templates | Post templates | Full Table | — | publication_id, id |
referral_program | Referral program milestones | Full Table | — | publication_id, id |
segments | Subscriber segments | Full Table | — | publication_id, id |
tiers | Subscription tiers | Full Table | — | publication_id, id |
Limitations
- Most streams are full table. Every stream except
engagementsreads all records on each run. - Deleted records stay in the destination. A record deleted in beehiiv stops appearing
in the sync. Set Emit Activate Version Messages to remove it from destinations that
support
ACTIVATE_VERSION. - Stats are all-time totals. The
statsof publications, posts and subscriptions have no date breakdown. Useengagementsfor daily opens and clicks. - Features a publication does not use are skipped. For example,
ad_network_reportsis empty for a publication that is not part of the ad network. - Values keep their beehiiv format. Timestamps such as
createdandpublish_dateare Unix seconds,ad_network_reports.revenueis a formatted currency string such as$12.34, and nested objects such asstatsare loaded as returned. subscriptionsholds personal data. Theemailcolumn is the address of each subscriber.
Data recovery / backfill
Only engagements keeps a bookmark between syncs: the latest date it has loaded for each
publication. Every other stream re-syncs completely on each run, so it needs no backfill.
To backfill engagements, reset the pipeline state, and lower Start Date first if you
need older days. Lowering Start Date alone has no effect once a bookmark exists.
The tables below list the main fields of each stream. posts and subscriptions have more
fields; the full schemas are in the tap's catalog. Times are in Unix seconds.
publications
| Field | Type | Description |
|---|---|---|
id | string | Unique publication identifier |
name | string | Publication name |
organization_name | string | Name of the organization that owns the publication |
referral_program_enabled | boolean | Whether the referral program is on |
created | number | Creation time |
stats | object | All-time subscriber and engagement stats |
posts
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique post identifier |
title | string | Post title |
subtitle | string | Post subtitle |
subject_line | string | Email subject line |
preview_text | string | Email preview text |
authors | array[string] | Author names |
status | string | Post status |
audience | string | Audience of the post |
platform | string | Where the post is published |
content_tags | array[string] | Content tags |
slug | string | URL slug |
web_url | string | URL of the web version |
newsletter_list_id | string | ID of the newsletter list the post is sent to |
recipient_count | integer | Number of recipients |
split_tested | boolean | Whether the subject line is split tested |
created | integer | Creation time |
publish_date | integer | Publish time |
displayed_date | integer | Date shown on the post |
stats | object | All-time email, web and click stats, when stats is expanded |
content | object | Post content, when content is expanded |
subscriptions
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique subscription identifier |
email | string | Subscriber email address |
status | string | Subscription status |
subscription_tier | string | Subscription tier |
subscription_premium_tier_names | array[string] | Names of the premium tiers |
referring_site | string | Site the subscriber came from |
referral_code | string | Referral code of the subscriber |
utm_source | string | UTM source at sign-up |
utm_medium | string | UTM medium at sign-up |
utm_campaign | string | UTM campaign at sign-up |
tags | array[string] | Subscriber tags |
newsletter_list_ids | array[string] | IDs of the newsletter lists the subscriber is on |
stripe_customer_id | string | Stripe customer ID of a paid subscriber |
created | integer | Sign-up time |
stats | object | All-time email stats, when stats is expanded |
custom_fields | array[object] | Custom field values, when custom_fields is expanded |
referrals | array[object] | Subscribers this subscriber referred, when referrals is expanded |
ad_network_reports
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
post_id | string | ID of the post that carried the ad |
ad_link_id | string | ID of the ad link |
ad_link | string | Ad link URL |
opens | integer | Number of opens |
payable_clicks | integer | Number of payable clicks |
revenue | string | Revenue, as a formatted currency string, e.g. $12.34 |
is_programmatic | boolean | Whether the ad is programmatic |
engagements
Supports incremental replication using date.
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
date | string | Day of the engagement — replication key |
total_opens | integer | Total email opens |
unique_opens | integer | Unique email opens |
total_clicks | integer | Total clicks |
unique_clicks | integer | Unique clicks |
total_verified_clicks | integer | Total verified clicks |
unique_verified_clicks | integer | Unique verified clicks |
authors
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique author identifier |
type | string | Author type |
name | string | Author name |
bio | string | Author biography |
bio_image_url | string | URL of the author image |
social_media_links | object | Social media links |
automations
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique automation identifier |
name | string | Automation name |
description | string | Automation description |
status | string | Automation status |
trigger_events | array[string] | Events that start the automation |
newsletter_list_id | string | ID of the newsletter list |
stats | object | Automation stats |
custom_fields
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique custom field identifier |
kind | string | Field type |
display | string | Field name as shown in beehiiv |
options | array[string] | Allowed values of a list field |
created | integer | Creation time |
newsletter_lists
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique newsletter list identifier |
name | string | List name |
slug | string | URL slug |
description | string | List description |
status | string | List status |
auto_subscribe | boolean | Whether new subscribers join the list automatically |
show_in_preference_center | boolean | Whether subscribers can see the list in their preferences |
subscriber_count | integer | Number of subscribers |
tier_ids | array[string] | IDs of the tiers that can access the list |
created_at | integer | Creation time |
updated_at | integer | Last modification time |
polls
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique poll identifier |
name | string | Poll name |
question | string | Poll question |
description | string | Poll description |
poll_type | string | Poll type |
status | string | Poll status |
poll_choices | array[object] | Choices of the poll |
trivia_answer | string | Correct answer of a trivia poll |
total_responses | integer | Number of responses |
poll_responses | array[object] | Responses to the poll |
stats | object | Poll stats |
created_at | integer | Creation time |
post_templates
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique template identifier |
name | string | Template name |
description | string | Template description |
created | integer | Creation time |
updated | integer | Last modification time |
referral_program
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique milestone identifier |
num_referrals | integer | Number of referrals needed for the reward |
reward | object | The reward |
auto_fulfill | boolean | Whether beehiiv fulfils the reward automatically |
segments
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique segment identifier |
name | string | Segment name |
type | string | Segment type |
status | string | Segment status |
active | boolean | Whether the segment is active |
total_results | integer | Number of subscribers in the segment |
last_calculated | integer | When the segment was last calculated |
stats | object | Segment stats |
tiers
| Field | Type | Description |
|---|---|---|
publication_id | string | ID of the publication |
id | string | Unique tier identifier |
name | string | Tier name |
description | string | Tier description |
status | string | Tier status |
prices | array[object] | Prices of the tier |
stats | object | Tier stats |
Settings
API Key
beehiiv API key.
Publication IDs
Publication IDs to sync. Leave empty to sync every publication that the API key can access.
Start Date
Earliest date to sync for ad_network_reports, by send date, and engagements. Leave
empty to sync all ad network reports and the last 30 days of engagements.
Posts Expand
Objects to expand on posts, e.g. stats, free_web_content or premium_email_content.
Expanding content makes the sync considerably slower.
Subscriptions Expand
Objects to expand on subscriptions, e.g. stats, custom_fields, referrals or
newsletter_lists.
Emit Activate Version Messages
Emit ACTIVATE_VERSION messages for full-table streams, so that destinations that support
them remove records that no longer exist in beehiiv.
beehiiv connector is available on Meltano. It is built, maintained, supported, and tested by Meltano.