How to import free subscribers and map custom fields or tags

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. 
    • If you're importing more than 10 subscribers into beehiiv, you'll first need to complete Stripe Identity Verification to verify your identity. You can do so by going to Settings > Publications > Import Subscribers, and then click on the Start Stripe Identity Verification button. Then, after you have completed the Stripe verification process, click on the Start New Import button.

    • If you’d like to import more than 10,000 subscribers, you’ll need to complete the Stripe verification process as outlined above, then fill out a form to submit. You can access the form by going to Settings > Publication > Import Subscribers, then scroll down to Raise your import limit and click on Complete this form.

      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.

        Import subscribers.png

        If you have a welcome email setup or an active automation, you can choose those options or leave them blank. You can also apply subscriber tags.

      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 and subscriber tags 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.

What’s the difference between custom fields and subscriber tags? 

  • Custom fields refer to data fields that your subscribers share with you, like name, age, address, and any additional information that is unique to each subscriber. 
  • Subscriber Tags refer to internal labels used to identify and group subscribers in your account. A good example of this is tagging subscribers as “friends and family” or “affiliates” to identify that group.

To map a column to either a subscriber tag or a custom field, simply select which of those you’d like to map it to from the dropdown options by clicking on the down arrow to access them.


Some things to consider when mapping custom fields

  • Email is the only required custom 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. 


Some things to consider when mapping subscriber tags

  • If a contact in the CSV already exists within your subscriber list, you won’t be able to override the existing tag data with the import.
  • Click on Select an Option and then choose Subscriber Tags from the dropdown and check the box for any tag columns you’d like to import. There are no additional details to configure to import tags

Tech Note: If you have multiple tags for a subscriber, be sure that your tags are formatted correctly within the specified tag column and there are no unescaped commas. 


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?