Buttondown Documentation
Ready to send your first email? This article outlines every step of the process, from importing subscribers to Buttondown to scheduling an email to send in the future.
If you already have a list of subscribers, you can upload that list to Buttondown as a comma-separated values, or CSV, file. To learn more about downloading CSVs and importing subscribers and newsletter archives, read Importing your data.
If you don't have that list, no worries! Start by reading Draft your first newsletter below.
The “Emails” page is the command center for your newsletter. When you write, schedule, and send newsletters, they'll appear here. You may not have any newsletters there yet, but you will soon!
Here's how to write a newsletter:
In the "Emails" page, click New in the upper right corner. The writing interface appears.
(Optional) Click the buttons in the upper right corner to toggle between “Preview Mode” and “Editor Mode.
Enter the text for your email in Markdown or HTML. Buttondown saves what you write automatically.
This video shows how to start a new email draft and toggle between the different editing view modes.
Before you send a newsletter email to your subscribers, you can send a draft of it to yourself to confirm that everything is working as expected.
This movie shows how to send a draft email to one person.
The draft will appear in the recipient's email shortly. You can identify it because it will have the string [PREVIEW] in the subject line.
This video shows a preview of a newsletter email in an email inbox.
If you sent a draft email to yourself, you can review it now in Buttondown and make any edits you think are necessary. You’re almost ready to click Send and deliver this email to your subscribers. But before you do, you should make sure everything is polished and ready.
Here’s a checklist to make sure everything’s ready:
After you double-check all the details, you can send your email. Here's how:
This video shows the process of sending an email.
After you send the email, a congratulatory pop-up appears with buttons to share it on social media or a copy-and-paste-able URL. You'll also see an option to Undo sending the email if you change your mind at the last minute.
You don't have to send an email as soon as you write it. You can schedule it to send later, at a specific date or time. You can do this by clicking the “Scheduling” button at the bottom of your draft.
To learn more, read Scheduling an Email.
You can upload images to Buttondown and insert those images in your emails. Buttondown supports all visual file formats, including .jpg, .png, .gif, and many more.
Buttondown uses Amazon S3 (a common file hosting platform) to safely and securely store your images. Images you upload to Buttondown last indefinitely by default. This means that even if you were to delete the email in which images are referenced, the images themselves still exist on Buttondown's servers. There's no option in the Buttondown UI to delete uploaded images, but you can do so with the API.
To upload an image:
After the upload completes, the image becomes available to insert into an email.
Buttondown automatically appends an unsubscribe link at the end of all emails you send, but you may want to manually place one in your email as well (for instance, if you send your newsletter infrequently, you might place it at the top of the email). The unsubscribe link for your newsletter is unique. You can generate it with the {{ unsubscribe_url }} shortcode and use that in place of a URL in an email.
Here is an example unsubscribe link in Markdown:
This link renders on draft emails, but the URL won't do anything if you click it.
You can read more about the different available variables here.
Tags let you create subgroups of your subscribers. Subscribers can have one or more tags, so if you want to include someone in more than one tag group, you can.
You can send emails including certain tags, making it easy to tailor your newsletter's content to who's going to enjoy it the most or find it the most relevant.
There are a few different ways to apply a tag to a subscriber:
To manually add a tag to a subscriber:
To learn more, read Tags.
A mail merge is a catchall term for sending out emails with specific fields changed.
For example, programmatically displaying the first name of the email recipient. Something like:
Buttondown supports mail merges with subscriber metadata. You can set metadata for a given subscriber with the API, or manually in that subscriber's "Notes" section:
After you set the metadata, you can refer to it in an email by including this variable: {{ subscriber.metadata.first_name }}.
Metadata doesn't just let you change small fields like names. You can also use a code snippet to show a paragraph, or define a conditional statement based on whether or not metadata is defined.
Here's an example:
In this example, the first two lines state that if a subscriber has the first_name object, the opening line of the email should greet the subscriber using that name. If the subscriber's first_name is Alice, the opening line will read "Hello Alice!" The third and fourth lines specify that if there is not a first_name object defined, the opening line of the email should read "Hello friend!"
So you've sent your newsletter's first email. That's great! What happens next? You can:
Here are responses to some common questions we get about writing and sending your first email in Buttondown.
As always, we’re happy to answer any questions you may have via support@buttondown.email.