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 import free subscribers 

1. From the left panel Dashboard, scroll down and click Settings.
   
   
   
   
   
   
2. Your publication settings will open. If you have multiple publications, select one from the dropdown options. Click Subscribers Import from the left panel.
   
   
   
   
   
   
3. Depending on the amount of subscribers you need to import, choose accordingly.
   
   
   Tech Note: Anyone importing more than 10 subscribers into beehiiv will need to verify their identity through Stripe Identity Verification.
   
   To import 1 to 10 subscribers: Click New Subscribers Import.
   
   
   
   
   
   To import 11 to 10,000 subscribers: After completing Stripe Identity Verification, click New Subscribers Import.
   
   
   
   
   
   To import over 10,000 subscribers: After completing Stripe Identity Verification, scroll down to the Request to raise your import limit section and click Open Request Form. A form will appear on the right for you to make the request directly from your account.
   
   
   
   
   
   
4. After clicking New Subscribers Import, 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 Next to proceed.
   
   
   
   
   
   
5. You'll be presented with a few Advanced Configurations (optional). You can choose to Send Welcome Email, Add to Automation(s), or Apply Subscriber Tags. Simply toggle each option on to activate it.
   
   A summary of your selections will appear on the right. Click Confirm Subscribers Import to proceed.
   
   
   
   
   
   
6. A confirmation message will appear, prompting you to verify that all contacts on the list have knowingly opted in to receive emails from you. Click 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 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 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 with tag(s) applied to them, you won’t be able to override the existing tag data with the import.
• 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.