Buttondown Documentation
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:
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:
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 ConvertKit, 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.
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 ConvertKit, 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:
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:
Day/Month/Year
. For example: October 7, 2021 should be formatted as 07/10/2021
.Sports
, Politics
”Name
and Location
.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:
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:
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 your first email 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.