Registration and Setup

Ready to dive into Buttondown? This topic will help you sign up and configure some important settings before you send a newsletter your subscribers. If you want help sending a newsletter, read Sending your first email.

Getting Ready

Buttondown is entirely based in your browser (nifty, right?). There's nothing to install, so registration is quick and easy—but it’ll be even easier if you have a few things ready before you start.

You must have:

A browser with cookies, JavaScript, and in-browser pop-ups enabled
An active email address that you know the password to
A strong password for your Buttondown account (hint: this should be different than the password to your email!)

Signing Up for A Buttondown Account

When you’re ready to roll, register for a Buttondown account.

Here are the steps you must complete when you create a Buttondown account:

Choose your username
Add your email
Create a password
Confirm your account

Choose your username

First thing’s first: you’ll need to create your username. If you have existing subscribers that you're migrating to Buttondown, you may want to use the username they're familiar with. Whether you have existing subscribers or not, you should pick a username that is unique and memorable. Your username is part of your public Buttondown URL (but don’t worry, you can change this later if you need to).

Enter your username in the "Username" field and continue. If the username you chose is already being used by another account, an error will display and you'll have to choose a different username.

Add your email address

Enter your go-to email address for receiving notifications, account updates, and billing information. This might be your personal email or an email associated with your business.

Later, if you decide to send your newsletter from the Buttondown server, your subscribers won’t see the email address that you registered with. Instead, they’ll see a Buttondown email address formatted as username@mail.buttondown.email.

It’ll look something like this:

Sample email address if sending from Buttondown server

Alternatively, you can send your newsletter from a custom domain. This is optional--there's nothing wrong with using a common email domain like Gmail or Protonmail. If you want to send from a custom domain, make sure your email address matches your domain.

Create a password

You know the drill—use lots of numbers, letters, and symbols. If you use a password manager that has a password generating feature, that's a great option to get a complex, secure password.

After you've chosen a username, entered your email, and created a password, you're all set. Click "Create an account."

This video shows the "Register" screen with information in all the fields.

Confirm your account

After you create an account, Buttondown sends a confirmation email to the email address you entered. Check your email for an email from "justin@buttondown.email". There's a link in that email. Click it to verify your account.

This video shows the confirmation email and moves the cursor onto a link that says "click here."

Still waiting for the confirmation email? Check your spam folder.

Crafting Your Newsletter's Look and Feel

Boom, you’re in! You can start sending newsletters right away (if you want to do this, read Sending your first email), but before you do, you might want to customize your newsletter a bit more.

Adding some details like your name and a description of your newsletter will help readers recognize you and understand what your newsletter is about. You can also customize your newsletter's appearance. If you want to do that, continue reading.

When you log in to Buttondown, you're taken to your newsletter's "Settings" page.

The first section is the "General" section. This is the fun part. Customize the fields in the "General" section however you like!

Three of these fields are particularly important:

What you put in the “Author” field appears to your readers as your email's "From" field.
Write your newsletter's “Description” in Markdown, HTML, or plaintext.
Your time zone is used for scheduled newsletter recommendations, as well as for timestamps in your archives.

Customize your newsletter's design

The "Design" section lets you customize the visual elements that appear consistently in every newsletter you send: the header and footer, custom colors or other elements with CSS, and which email template you want to use.

The content you put in the “Header” and “Footer” will appear at the top and bottom (respectively) of every newsletter that you send. For example, you might want to put a link to your website in the footer. You can write in Markdown, HTML, or plaintext.

The "CSS" section lets you customize your newsletter’s appearance. To learn more, read CSS.

This video shows a newsletter's "Design" section with information in the "Header" and "Footer" sections.

Establish your newsletter's "Branding"

Your newsletter’s branding includes its color palette, or “Tint Color,” as well as its logo, or “Icon.” Your “Tint color” appears an accent in places like hyperlinks or the “Subscribe” button. The “Icon” appears on top of your newsletters, in your archives, and as part of your social “Share” button. The "Share image" appears when you or your subscribers share your newsletter on social media.

To customize the "Tint color," choose one of the default colors from the menu, or click the three-dot overflow menu to choose a different color.
To customize the "Icon," click to upload a 300 x 300 pixel image. Square PNGs display the best.
To customize the "Share image," click to upload a 1080 x 1080 share image. Square PNGs display the best.

Import your subscribers

Already have a list of subscribers? Have no fear! You can upload that list to Buttondown as a CSV (or "comma-separated values") file. Buttondown can automatically import the following values for each of your subscribers:

Email address
Time joined (this can be imported in the standard “month/day/year” format)
Notes (these are completely open-ended, and don’t have to follow a specific format)
Tags (read more about tags here)
Metadata (read more about metadata here)

Let’s say you have your subscriber database loaded into a Google or Excel spreadsheet. Toggle to “File,” and select “Download.” Then select “Comma-Separated Values (.csv)” to export your CSV file.

Now let’s move back to Buttondown—specifically, the “Subscribers” page. From here, click the “Import” button to upload your CSV file. Once your file uploads, you’ll be guided through a series of questions to identify the columns of your CSV file.

Once you’ve completed each of the guided questions, click “Done,” and Buttondown will start importing your subscribers. Note that if you’re uploading a large quantity of subscribers, it may take a few hours to process. But when Buttondown is ready, you should see your newly imported subscribers (along with their accompanying notes, tags, metadata, and more) in the “Subscribers” page.

Visit our “Importing Your Data” doc to learn even more about downloading CSVs and importing subscribers, as well as importing past newsletter archives.

So you’ve found yourself in the “Emails” page. You may not have any newsletters there yet, but you will soon! Click the “New” button in the upper right corner to get started.

You’ll be transported to Buttondown’s intuitive writing interface, where you can easily toggle between “Preview Mode” and “Editor Mode.” "Preview Mode" renders your Markdown or HTML draft in a more readable format. "Editor Mode" provides a tool bar for formatting your text, adding links, adding images, and more. When you’re ready, jump in to code your newsletter in either Markdown or HTML. Buttondown will automatically save your progress as you go!

Once you’re happy with your newsletter’s subject and body text, you’ll be ready to send a draft. Click “Send Draft” and enter your preferred email address for previewing your newsletter. Then click “Add Recipient,” and off it goes!

Wait just a few moments, and your draft should pop up in your inbox with “[PREVIEW]” in the subject line.

After you make any necessary edits to your draft, you’re almost ready to click “Send”—there are just a few other quick details to attend to. Here’s a checklist to make sure everything’s ship shape:

Have you checked all of your links?
How many subscribers are you sending your newsletter to? Will you be sending to all of your subscribers, or only those with certain tags?
Are you ready to send this newsletter immediately, or would you rather schedule it for later?

Once you’ve double checked all the little details, it’s time to click “Send.” You’ll see a congratulatory pop-up with buttons to share your newsletter via social media or a copy-and-paste-able URL. And, in case of emergency, you’ll also have an option to “Undo” sending your newsletter.

You’ve done it! For further information about uploading images, adding custom unsubscribe links, sending out mail merges, and more, check out our detailed guide for “Sending Your First Email.”

Going Above and Beyond

You may want to schedule your newsletter to send at a specific date or time. You can do this by clicking the “Scheduling” button at the bottom of your draft. Set your target date and time, and double check your time zone before clicking “Save.” One last step: Make sure you click “Send” in the bottom right corner before exiting your draft. Buttondown will still send it at the time you specified, but it needs to get the official go-ahead from you clicking “Send”!

Take a look at our “Scheduling an Email” doc for FAQs and further information.

Build your subscriber base

You’ve sent your first newsletter, and now you’re ready to cultivate your subscriber base. You can start by sharing your Buttondown URL, embedding an HTML form across your platforms, or embedding an iFrame on your website. Our doc on “Building Your Subscriber Base” is a great place to start.

Organize your subscriber base

Tags can be used to sort your subscribers, as well as to send out targeted email blasts. Like tags, metadata can also provide additional context for subscribers. That context can come in handy if you’re searching for a specific set of subscribers.

Want to learn more about tags and metadata? Our “Building Your Subscriber Base” doc is the best way to do so.

Use a custom domain

You may choose to send and archive newsletters through a custom domain in order to consolidate your brand presence. Learn more about custom domains by checking out our docs for “Getting a Custom Domain,” “Hosting on a Custom Domain,” and “Sending From a Custom Domain.”

Upgrade to a paid account

Buttondown is free for your first hundred subscribers. After that, we charge a small fee to help keep the lights on. Pay a visit to our “Billing” doc to explore all of Buttondown’s pricing options.

Schedule a chat with us

We’re here in case you need to ask any questions or talk through your account. Reach out to us at support@buttondown.email. We’re always excited to speak with you!