How to import free subscribers and map custom fields

In this article, we cover the steps for importing free subscriber content and mapping custom fields for general purposes. For information on importing previous newsletter content to beehiiv, please refer to this article

Video Disclaimer: The beehiiv platform has evolved since the filming of this video, so parts of the user interface featured in the video will be slightly different than what you see in your account. In particular, we have expanded upon the list of outside service providers that we offer a content import process for, and you will only need to watch the video to the 1:51 mark to see the importing subscriber content. 

Watch and learn: Migrating your newsletter


Important Note: In order to complete the following steps, you will need to have a CSV file of the subscribers that you wish to import. If you were on a previous platform, you can export the list directly from them. 

For easier mapping during the import, it's best practice to review your CSV file and make sure the header fields use the same names as the tags and custom fields that you’ll be using in beehiiv, and remove any data that you don’t plan to use. 

How to import free subscriber content

  1. From the left hand panel in your beehiiv account, go to Settings > Publication > then click on the Import Subscribers tab.

  2. Depending on  the amount of subscribers you need to import, you’ll choose accordingly. 
    • To import 2,500 subscribers  or less, under Import Subscribers, click on the black Start Import button. 

    • To import up to 10,000 subscribers, you’ll first need to be verified by our payment partner, Stripe. 
      • Under Raise your import limit, click on the pink Start Stripe Identity Verification button. 
      • Then, after you have completed the Stripe verification process, click on the black Start Import button.
    • To import more than 10,000 subscribers, you’ll need to go through the Stripe verification process and then contact our support team for further assistance. (You can also refer to this article on why we set import limits.)


      1. After clicking on the black Start Import button, you’ll be prompted to choose an import method. Select Upload a CSV file and then choose the CSV file that you want to import.

        If you have a welcome email setup or an active automation, you can choose those options or leave them blank. You can also select or skip the email validation.

      2. Review your selections and click on Import Subscribers.

      3. A confirmation message will pop up where you will need to confirm that the contacts in the list have knowingly opted-in to receiving emails from you. Click on Import to confirm.


How to map custom fields during a subscriber import 

After the subscriber import process has begun, you’ll be prompted to start mapping out the fields (or tags) from the CSV file as custom fields within beehiiv.

Some things to consider when mapping custom fields/tags:

  • Email is the only required field, so if no columns are selected, emails will still be imported from the CSV.
  • If you have additional fields in your CSV beyond the standard email address, you can choose which of these fields to import.
  • If a contact in the CSV already exists within your subscriber list, you’ll have the option to overwrite existing custom field data when you import.
    • If you don’t want to do this, simply uncheck that box.


If you have an existing custom field corresponding to any of the data fields that you’re importing, you can select it from the dropdown. Otherwise, you can create a new one by selecting New Custom Field.


When adding a new custom field, you’ll need to give it a name and select a data type. Choose from Text, Number, True/False, Date, or Date & Time.


Repeat this process until you have chosen an option for each custom field you are importing. When done making your mapping selections, be sure to review them all for accuracy, then click on the Import button.

Once completed, scroll down to the Historical Imports section and you will see how many subscribers were accepted.

You can then view the new subscribers by navigating to the Audience > Subscribers section of your account.

To see the newly imported custom fields, click on an individual subscriber’s name and navigate to the Custom Fields section. 


Was this article helpful?