Publishing your first email

Ready to publish 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 publish 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:

Now write your email! Buttondown will save what you write automatically.

You can change between editor modes with the dropdown located in the top-right corner, there are a few modes you can choose:

• Fancy mode lets you write in an editor where it appears just like how it'd appear on the emails that will be sent out.
• Markdown mode lets you write in Markdown, a plain text format familiar to developers.
• Naked mode lets you fully control the email that gets sent out to your subscribers.

You can preview how your email is going to look like in the sent emails and web archive by clicking on Preview on the top-right corner.

Before you publish a newsletter email to your subscribers, you can send a draft of it to yourself to confirm that everything is working as expected.

1. Follow the procedure in Draft your first newsletter to draft an email.
2. Open the Preview pane.
3. Click the Send draft button in the top right corner.
4. This opens then "Send a draft copy" dialog.
5. Enter the email address you wish to receive your test newsletter into the search box, and "Add email address as recipient".
6. Click Send draft.

This video 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:

• Verify that all the links in your email work.
• Decide the target audience for this email. You can send it to all your subscribers, or only those with certain tags?
• Decide if you want the email to be published immediately, or schedule it for later.

After you double-check all the details, you can send your email. Here's how:

1. From the draft you're currently working on, click on the Publish button located at the top-right corner. The "Send this email" drawer will appear.
2. Review the summary provided within the drawer, and verify that everything looks correct.
3. In the "Ready to publish?" section, click Publish. Your email will be sent shortly.

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.

Within the Schedule section of the "Send this email" drawer, select Send at a specified time, then you can configure when it should be sent.

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:

[Click here to unsubscribe!]({{unsubscribe_url}}).

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:

• Tagging subscribers manually
• Customizing your subscription form
• Setting tags with the API

To manually add a tag to a subscriber:

1. Click Subscribers. The "Subscribers" page appears with a list of subscribers to your newsletter.
2. Find the subscriber you wish to add a tag to and click to select them. The subscriber's "Details" page opens.
3. Scroll to the "Tags" section and choose the tags that you wish to apply to the subscriber.
4. Click Save changes.

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:

• Continue customizing your email with our advanced email configuration options
• Start cultivating your subscriber base

Here are responses to some common questions we get about writing and sending your first email in Buttondown.

• Why is my email all... purple?
• How do I avoid the "Promotions" tab in Gmail?
• Why does my email look different on some clients?