How to import free subscribers and map custom fields or tags

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

---

How to complete your first subscribers import 

1. When prompted in your account dashboard, click on the Import content and list option. 
   
   

   
   Note: our experience and the exact options available to you may vary based on the responses you gave earlier while onboarding. You can import subscribers at any time by going to Settings > Subscribers Import > New Subscribers Import.
2. First, you’ll be given the opportunity to import any content you may have from another newsletter platform. If you wish to do so, follow the instructions found in our guide, How to import previous content into beehiiv, then pick back up with step 3. 
   
   If you do not wish to do so, click on the Skip button to move on to the subscriber import step. 
   
   
   
   

3. Once you enter the Subscribers Import step, you’ll be prompted to select an import method. By default, Upload a CSV file will be preselected, but you can also choose to Copy and paste a list of email addresses.
   
   Click Choose File and select the CSV file from your device. Once added, click on the Finish button to proceed.
   
   

   
   
   Or, if you wish to copy and paste your subscribers, you can do so by selecting Copy and paste a list of email addresses from the dropdown, then inputting your list of emails, separated by commas. 
   
   Once added, click on the Finish button to proceed. 
   
   
   
   Tech Note: You will be able to upload as many subscribers as your beehiiv plan type and plan tier allow. You may also be prompted to complete Stripe Identity Verification or upgrade to a higher plan tier to accommodate the number of subscribers on your list at this time.
4. Once uploaded, you will be able to view the status of your import by going to Settings > Subscribers Import where you’ll be presented with a Historical Imports table to view any imports you’ve already made. 
   
   
   
   
   

---

How to complete additional subscribers imports

1. From the left panel Dashboard, scroll down and click Settings.
    
2. Your publication settings will open. Click Subscribers Import from the left panel. 
   
   
   
3. You’ll be presented with a table of your Historical Imports to see the Import Status of subscribers imports that you may have completed in the past. 
   
   
   
   
   Above that, you’ll see a Subscribers Import section. Click on New Subscribers Import to continue. 
   
   
   
4. You may be prompted to complete Stripe Identity Verification. This quick verification process takes 1-3 minutes and also gives you access to other features on the platform. Click on the Start Stripe Identity Verification to get started.
   
   
   
   

5. Once you enter the Subscribers Import step, you’ll be prompted to select an import method. By default, Upload a CSV file will be preselected, but you can also choose to Copy and paste a list of email addresses.
   
   Click Choose File and select the CSV file from your device. Once added, click on the Next button to proceed.
   
   

   
   
   Or, if you wish to copy and paste your subscribers, you can do so by selecting Copy and paste a list of email addresses from the dropdown, then inputting your list of emails, separated by commas. 
   
   Once added, click on the Next button to proceed. 
   
   
   
   Tech Note: You will be able to upload as many subscribers as your beehiiv plan type and plan tier allow.

6. Next, you’ll be presented with Advanced Configuration options. Simple toggle on any of these options if you so choose, then click on the Confirm Subscribers Import button to finalize. 
   
   

   
   Reminder: You first need to set up your Welcome Email to enable the Send Welcome Email option and any automations would need to be set up and activated to enable the Add to Automation(s) option.
7. Once uploaded, you will be able to view the status of your import by returning to Settings > Subscribers Import where you’ll be presented with a Historical Imports table to view any imports you’ve already made. 
   
   
   
   
   

---

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 from the CSV file as either custom fields or subscriber tags within beehiiv.

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

• Custom fields are data fields that your subscribers share with you, like name, age, address, and any additional information that is unique to each subscriber.
• Subscriber tags are 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 Create 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.

You can also select from a preset option to instantly create a custom field using commonly collected subscriber details like First name, Last name, Full name, or Company.

Click on the Save button to finalize your selections. 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 with tag(s) applied to them, you won’t be able to override the existing tag data with the import. Any existing tags will remain in place and any additional tags will be added to that subscriber.
• 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, you can 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 any newly imported custom fields, click on an individual subscriber’s name and navigate to the Custom Fields section in the panel on the left side of the dashboard.

---

Frequently asked questions about importing subscribers 

Why were only 70 out of 100 emails on my CSV imported successfully?

When importing a CSV, beehiiv automatically filters out duplicate and inactive emails to maintain a clean subscriber list.

Here’s what might have happened to the other 30 emails:

• Duplicate Emails: If the same email appears multiple times on your CSV or already exists on your subscriber list, it will be excluded from the import.
• Inactive Emails: If an email address is no longer active (like when someone changes jobs and their work email becomes invalid), it will also be filtered out.

As a best practice, we recommend performing regular list cleaning to remove inactive subscribers. Together, these steps help ensure your subscriber list is accurate and optimized for effective email campaigns.

Why isn’t my CSV import working due to formatting issues?

For your CSV import to work correctly, the ‘Email’ column must be the first (leftmost) column in your spreadsheet, and there cannot be any blanks in the Email column.

If your CSV is formatted correctly and valid emails are still being blocked, you can click on Chatbot Assistance in the bottom-right corner of this page or visit the Help page in the top navigation bar of your account for further support.
 

My custom fields are not uploading. What should I do?

Some custom fields are reserved for beehiiv-specific requirements and cannot be uploaded as-is; please refer to this article for our list of reserved fields. However, you can resolve this by renaming the column in your CSV before uploading.

For example: The reserved field ‘city’ can be renamed to ‘imported_city’ to allow the upload. (This is because ‘city’ is a reserved custom field used for analytic tracking.) 

Make sure to rename any other reserved fields in a similar way to successfully upload your data.

I forgot to upload subscriber custom fields upon import. What can I do?
You can reupload your CSV with the custom field columns present. Then, map the fields as shown above. Once complete, the custom fields will be added to the subscribers in your account.