Importing your newsletter data

Moving your data (much like moving homes) can be incredibly stressful. Buttondown can make moving your newsletter from an existing platform a little easier by seamlessly importing your subscribers, tags, metadata, archives, and more.

Before you import existing newsletter data, get your Buttondown account set up and ready to send more newsletter emails.

Make sure you've completed the following steps:

• Confirm your Buttondown account
• Fill out your general newsletter details, including your newsletter's name, author, and description
• Customize your newsletter's CSS
• Create your newsletter's branding, including your preferred color palette and logo

After you've configured your Buttondown account and customized your newsletter, it’s important to make sure that your subscribers are expecting your move to Buttondown.

Here are a few quick questions to ask yourself before we proceed:

• Have all of your subscribers from your previous newsletter service consented to receive your Buttondown-based newsletter? If so, they won't need to re-confirm their subscription when you move to Buttondown.
• Are you importing your subscribers from a listserv? If so, is everyone on that listserv aware that your newsletter is moving to Buttondown? Buttondown sees any listserv as a single subscriber, regardless of how many people are on it. If a person on your listserv unsubscribes from your newsletter, it may affect the listserv as a whole.

After you've customized your newsletter and prepared your subscribers to move to Buttondown, you can begin the data import process.

The simplest way to import your subscriber data is by uploading a comma-separated values (CSV) file to Buttondown. Buttondown recognizes columns in CSVs from common import sources like Kit, MailChimp, or Substack. When Buttondown recognizes a column, it automatically maps the data in that column to corresponding fields in Buttondown.

If Buttondown doesn't recognize a column, you receive a prompt to map columns to Buttondown fields manually. Buttondown prompts you to choose which columns correspond to certain pieces of data, which lets you import subscribers while keeping their existing tags, join dates, and metadata.

In order to import your data to Buttondown, you have to format it in a CSV file.

Here’s an example of what a CSV file might look like, either as a table or as a raw file.

Email,Date,Interests,Name,Location,Notes
icarus@buttondown.email,1/1/23,Tech,Icarus,Crete,Flew too high
odysseus@buttondown.email,1/2/23,"Sports, Politics",Odysseus,Ithaca,Stuck at sea
helen@buttondown.email,1/3/23,"World News, Politics", Helen,Troy,Face that launched a thousand ships

Common newsletter email services like Kit, MailChimp, or Substack let you export your subscriber data as a CSV file. After you upload the CSV file to Buttondown, it can automatically import the following values for each of your subscribers:

• Email address
• The date they subscribed to your newsletter
• Any assigned tags, which you can use to group your subscribers together or send tailored content
• Any assigned metadata, such as the subscriber’s name, location, or other structured-key values
• Any free-form notes you may have made for your personal reference

The only required field is your subscriber's email address. All the above values are optional and don’t have to be included in your CSV file. You can also add details like tags, metadata, and notes to subscribers after you import them to Buttondown.

When you move large quantities of data, it is very important to keep that data well organized.

Here are a few tips for formatting your CSV file:

• You don’t need to include a header row, but you can if you want to, just for your own reference. If you do include a header row, you can format it however you like.
• Format all dates Day/Month/Year. For example: October 7, 2021 should be formatted as 07/10/2021.
• If one subscriber has multiple tags, we recommend including all the tags in the same column and separating them with commas, like so: “Sports, Politics”
• If one subscriber has multiple items of metadata, we recommend adding them in separate columns, not in the same column.The example below has two separate metadata columns for Name and Location.
• Last, but not least, you can format your subscriber Notes however you like. If you don’t have any notes, that’s fine too!

When you're satisfied with the contents of your CSV file, export it from Google Sheets, Excel, or your preferred app.

This video shows how to download a CSV file from Google Sheets.

This section explains how to import subscriber information to Buttondown.

Here's how to import your CSV file to Buttondown:

1. Navigate to the “Subscribers" tab of your Buttondown dashboard.
2. Click “Import.” A pop-up window appears.
3. Drag your CSV file into the pop-up and follow the prompts that appear. These prompts ask you to choose the values you’d like to assign as tags, metadata, notes, and more. Buttondown automatically detects some kinds of imports and automatically assigns values when it recognizes one.

This video shows the process of importing a CSV to Buttondown and customizing specific values.

Depending on how many subscribers you import, it can take as little as a few seconds or as much as a few hours to import your data. Don't worry, you don't have to sit at your computer while you wait. We’ll send you an email to notify you when your import is complete.

If you import a very large quantity of subscribers, we may temporarily deactivate your account while we verify that the data you're importing is correct.

You can review your subscriber data in Buttondown at any time. The easiest place to look is the “Subscribers” tab of your Buttondown dashboard.

From the "Subscribers" tab, you can customize your subscriber list view to include tags, metadata, and other useful information. To customize the view, click the plus (+) button in the upper right hand corner. You can also click any subscriber’s email address to view your notes or edit that subscriber's data.

This video shows the plus (+) button and options being selected from its menu.

You can also check out the “Tags” tab of the Buttondown dashboard. Here, you’ll have the option to edit each tag, view the subscribers grouped by each tag, and more.

This video shows the "Tags" tab's overflow menu button and options being selected from its menu.

You can also import past emails from your newsletter to Buttondown, so your whole newsletter archive is in one place. Start by exporting your archives as a ZIP file from your previous email service. Every email service goes about data exports in a slightly different way. Rather than trying to document them all here, we recommend checking out our migration guides. We may have a specific guide for your previous email service.

Here's how to import your newsletter archive to Buttondown:

1. Generate a ZIP file of your newsletter archive from your previous service.
2. Navigate to the “Emails” tab.
3. Click the Import button.
4. Choose the service you’re migrating from, then click Choose a ZIP.
5. Drag and drop your ZIP file over the Choose a ZIP button.

This video shows the workflow of clicking Import and uploading a ZIP file.

That's it! After a moment or two, your archives should appear in the “Emails” tab of your Buttondown dashboard.

Now that you’ve successfully imported your data, there’s no better way to celebrate than by crafting the first edition of your brand new newsletter. Our guide to sending emails explains the process of uploading images, adding custom links, leveraging tags, completing mail merges, and more.

The more the merrier! Learn how to grow your newsletter's following by sharing your Buttondown URL, embedding an HTML form, or embedding an iFrame.