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.

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 subscriber tags and custom fields that you’ll be using in beehiiv, and remove any data that you don’t plan to use.

---

How to complete your first subscribers import 

This set of instructions will take you through uploading your first import as a part of your beehiiv onboarding. Depending on your selections during onboarding, you may not see the option on your dashboard.

If you prefer to skip the guided onboarding and explore the app before importing your subscribers, or if you do not have the option available during onboarding, follow the additional subscribers import guidance below.

1. When prompted during onboarding, click on the Import content and list option. 
   
   

   
   Note: Your experience and the exact options available to you may vary based on the responses you gave earlier in the onboarding process. You can import subscribers at any time by going to Settings > Subscribers Import > New Subscribers Import.
2. 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. 
   
   
   

3. When 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 allows. 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. After the file uploads, you can go to Settings > Subscribers Import to check the progress. Under Historical Imports, a table shows each import with its status and the counts of subscribers uploaded, accepted, and rejected. 
   
   
   

---

How to complete additional subscribers imports

1. Click the Settings icon in the bottom left corner of your account.
    
2. Your publication settings will open. If you have access to multiple publications, be sure the right one is selected at the top left. Click Subscribers Import from the left panel. 
   
   
   
3. At the top of the page, click on the New Subscribers Import button.
   
   
   
4. If you haven't completed Stripe Identity Verification, you’ll be prompted to do so. The check takes about 1-3 minutes and unlocks additional platform features. Click Start Stripe Identity Verification and follow the prompts.
   
   
   

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.
   
   Otherwise, click Choose File and select the CSV file from your device. Once added, click 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 the Next button to proceed. 
   
   
   
   Tech Note: You will be able to upload as many subscribers as your beehiiv plan type and plan tier allows. 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.

6. Under Advanced Configurations, you can optionally toggle on Send Welcome Email, Add to Automation(s), or Apply existing subscriber tags. When finished, click the Confirm Subscribers Import button to finalize.
   
   

   
   Reminder: The Send Welcome Email option is only available once your welcome email has been enabled; and the Add to Automation(s) option is available after automations are set up and active in your account.
7. After the file uploads, you can go to Settings > Subscribers Import to check the progress. Under Historical Imports, a table shows each import with its status and the counts of subscribers uploaded, accepted, and rejected.
   
   
   

---

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 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 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 some emails (70 out of 100) 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; these will show under 'Rejected' on the historical import list

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.