beehiiv
B
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.

StreamDescriptionReplicationReplication KeyPrimary Key
publicationsPublications that the API key can access, with all-time statsFull Table—id
postsPosts, with all-time statsFull Table—publication_id, id
subscriptionsSubscribers, with all-time statsFull Table—publication_id, id
ad_network_reportsAd network revenue for each post and ad linkFull Table—publication_id, post_id, ad_link_id
engagementsDaily opens and clicksIncrementaldatepublication_id, date
authorsPost authorsFull Table—publication_id, id
automationsAutomationsFull Table—publication_id, id
custom_fieldsSubscriber custom field definitionsFull Table—publication_id, id
newsletter_listsNewsletter listsFull Table—publication_id, id
pollsPollsFull Table—publication_id, id
post_templatesPost templatesFull Table—publication_id, id
referral_programReferral program milestonesFull Table—publication_id, id
segmentsSubscriber segmentsFull Table—publication_id, id
tiersSubscription tiersFull Table—publication_id, id

Limitations

  • Most streams are full table. Every stream except engagements reads 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 stats of publications, posts and subscriptions have no date breakdown. Use engagements for daily opens and clicks.
  • Features a publication does not use are skipped. For example, ad_network_reports is empty for a publication that is not part of the ad network.
  • Values keep their beehiiv format. Timestamps such as created and publish_date are Unix seconds, ad_network_reports.revenue is a formatted currency string such as $12.34, and nested objects such as stats are loaded as returned.
  • subscriptions holds personal data. The email column 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

FieldTypeDescription
idstringUnique publication identifier
namestringPublication name
organization_namestringName of the organization that owns the publication
referral_program_enabledbooleanWhether the referral program is on
creatednumberCreation time
statsobjectAll-time subscriber and engagement stats

posts

FieldTypeDescription
publication_idstringID of the publication
idstringUnique post identifier
titlestringPost title
subtitlestringPost subtitle
subject_linestringEmail subject line
preview_textstringEmail preview text
authorsarray[string]Author names
statusstringPost status
audiencestringAudience of the post
platformstringWhere the post is published
content_tagsarray[string]Content tags
slugstringURL slug
web_urlstringURL of the web version
newsletter_list_idstringID of the newsletter list the post is sent to
recipient_countintegerNumber of recipients
split_testedbooleanWhether the subject line is split tested
createdintegerCreation time
publish_dateintegerPublish time
displayed_dateintegerDate shown on the post
statsobjectAll-time email, web and click stats, when stats is expanded
contentobjectPost content, when content is expanded

subscriptions

FieldTypeDescription
publication_idstringID of the publication
idstringUnique subscription identifier
emailstringSubscriber email address
statusstringSubscription status
subscription_tierstringSubscription tier
subscription_premium_tier_namesarray[string]Names of the premium tiers
referring_sitestringSite the subscriber came from
referral_codestringReferral code of the subscriber
utm_sourcestringUTM source at sign-up
utm_mediumstringUTM medium at sign-up
utm_campaignstringUTM campaign at sign-up
tagsarray[string]Subscriber tags
newsletter_list_idsarray[string]IDs of the newsletter lists the subscriber is on
stripe_customer_idstringStripe customer ID of a paid subscriber
createdintegerSign-up time
statsobjectAll-time email stats, when stats is expanded
custom_fieldsarray[object]Custom field values, when custom_fields is expanded
referralsarray[object]Subscribers this subscriber referred, when referrals is expanded

ad_network_reports

FieldTypeDescription
publication_idstringID of the publication
post_idstringID of the post that carried the ad
ad_link_idstringID of the ad link
ad_linkstringAd link URL
opensintegerNumber of opens
payable_clicksintegerNumber of payable clicks
revenuestringRevenue, as a formatted currency string, e.g. $12.34
is_programmaticbooleanWhether the ad is programmatic

engagements

Supports incremental replication using date.

FieldTypeDescription
publication_idstringID of the publication
datestringDay of the engagement — replication key
total_opensintegerTotal email opens
unique_opensintegerUnique email opens
total_clicksintegerTotal clicks
unique_clicksintegerUnique clicks
total_verified_clicksintegerTotal verified clicks
unique_verified_clicksintegerUnique verified clicks

authors

FieldTypeDescription
publication_idstringID of the publication
idstringUnique author identifier
typestringAuthor type
namestringAuthor name
biostringAuthor biography
bio_image_urlstringURL of the author image
social_media_linksobjectSocial media links

automations

FieldTypeDescription
publication_idstringID of the publication
idstringUnique automation identifier
namestringAutomation name
descriptionstringAutomation description
statusstringAutomation status
trigger_eventsarray[string]Events that start the automation
newsletter_list_idstringID of the newsletter list
statsobjectAutomation stats

custom_fields

FieldTypeDescription
publication_idstringID of the publication
idstringUnique custom field identifier
kindstringField type
displaystringField name as shown in beehiiv
optionsarray[string]Allowed values of a list field
createdintegerCreation time

newsletter_lists

FieldTypeDescription
publication_idstringID of the publication
idstringUnique newsletter list identifier
namestringList name
slugstringURL slug
descriptionstringList description
statusstringList status
auto_subscribebooleanWhether new subscribers join the list automatically
show_in_preference_centerbooleanWhether subscribers can see the list in their preferences
subscriber_countintegerNumber of subscribers
tier_idsarray[string]IDs of the tiers that can access the list
created_atintegerCreation time
updated_atintegerLast modification time

polls

FieldTypeDescription
publication_idstringID of the publication
idstringUnique poll identifier
namestringPoll name
questionstringPoll question
descriptionstringPoll description
poll_typestringPoll type
statusstringPoll status
poll_choicesarray[object]Choices of the poll
trivia_answerstringCorrect answer of a trivia poll
total_responsesintegerNumber of responses
poll_responsesarray[object]Responses to the poll
statsobjectPoll stats
created_atintegerCreation time

post_templates

FieldTypeDescription
publication_idstringID of the publication
idstringUnique template identifier
namestringTemplate name
descriptionstringTemplate description
createdintegerCreation time
updatedintegerLast modification time

referral_program

FieldTypeDescription
publication_idstringID of the publication
idstringUnique milestone identifier
num_referralsintegerNumber of referrals needed for the reward
rewardobjectThe reward
auto_fulfillbooleanWhether beehiiv fulfils the reward automatically

segments

FieldTypeDescription
publication_idstringID of the publication
idstringUnique segment identifier
namestringSegment name
typestringSegment type
statusstringSegment status
activebooleanWhether the segment is active
total_resultsintegerNumber of subscribers in the segment
last_calculatedintegerWhen the segment was last calculated
statsobjectSegment stats

tiers

FieldTypeDescription
publication_idstringID of the publication
idstringUnique tier identifier
namestringTier name
descriptionstringTier description
statusstringTier status
pricesarray[object]Prices of the tier
statsobjectTier 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.

Meltano Cloud Connector

beehiiv connector is available on Meltano. It is built, maintained, supported, and tested by Meltano.

Why Meltano Cloud?
Expert supportDirect access to the team that built and maintains Meltano Cloud. Same-day responses during UK business hours. When something breaks, we fix it fast because we know exactly how it works.
Rigorously testedEvery connector goes through comprehensive testing and quality checks before production. Daily monitoring catches issues before they hit your pipelines. We don't just wrap open-source taps and hope for the best. We validate, we test, we maintain.
No maintenance overheadAPI changes. Connector updates. Schema drift. Breaking changes from upstream sources. We handle it all. Your team focuses on using data. Our team focuses on making sure it's there when you need it.
Ingest & transform data with AIConnect Claude or any MCP-compatible assistant to Meltano Cloud. Add connectors, run pipelines, build dbt models and diagnose failed runs in plain English, against the same Git-backed project your team works in.
Access to Meltano Slack communityJoin 5,500+ data engineers and analytics practitioners. The community is active, helpful, and always on. Good for quick questions, sharing patterns, and learning what others are building.