Beta

Developers

The beehiiv API allows you to interact programmatically with beehiiv's rich feature set. Currently we offer subscriber management, but have plans to roll out access to other features in the future.

The API is currently in beta and only available on paid plans.

Fundamentals

  • All requests should be authenticated and sent over https.
  • The base URL is http://api.beehiiv.com/<version>
    • We are currently on v1 and will make you aware of future versions that have breaking changes.
    • Old versions may become deprecated.
  • Requests are subject to the rate limits specified in the Rate Limits section below.

Authentication

Beehiiv uses API keys to authenticate all requests to the API. Keys can be created in the beehiiv dashboard and are scoped to a publisher.

The API expects an X-ApiKey header that follows the following format:

X-ApiKey: <myapikey>

For example:

$ curl --location --request GET 'https://api.beehiiv.com/v1/endpoint' \
  --header 'X-ApiKey: 123456'

Make sure you store your token in a secure place. We will not be able to recover an API key if lost — you will need to generate a new one and expire the old one.

API keys are considered sensitive data and should not be shared with anyone. Be careful not to expose the API key in your source code or any other public location (including front-end code).


Rate Limits

Each endpoint has an individual rate limit and interval. For example, 30 requests (limit) per 1 minute (interval). If you exceed the rate limit, you will receive a 429 response.

To see your current usage, you can check the response headers of your request for the following:

  • X-RateLimit-Limit: The maximum number of requests you can make in the current interval.
  • X-RateLimit-Remaining: The number of requests remaining in the current interval.
  • X-RateLimit-Retry-After: The number of seconds before the current interval is over.

Subscribers

The subscribers API allows you to manage your subscriber list via the API. Right now, we only support adding subscribers — if you need more than this, please contact support.

Create Subscriber

Create a new subscriber by sending a POST request to /subscribers with the following parameters:

  • email: The email address of the subscriber.
    • Required.
  • publication_id: The ID of the publication you want to subscribe to.
    • Required.
  • reactivate_existing: Whether or not to reactivate the subscriber if they have already unsubscribed. This option should be used only if the subscriber is knowingly resubscribing.
    • Optional. Defaults to false.
  • send_welcome_email: Whether or not to send a welcome email to the subscriber.
    • Optional. Defaults to false.
  • utm_source: The source of the subscriber.
    • Optional.

This endpoint is rate limited to 30 requests per minute. If you are trying to upload in bulk, please do so in the application with a CSV.

See the example request and response below.

POST /subscribers


Publications

You can use the publications API to get a list of all your publications.

All Publications

Get a list of all your publications by sending a GET request to /publications.

This endpoint is rate limited to 30 requests per minute.

See the example request and response below.

GET /publications

© 2022 beehiiv, Inc. All rights reserved.