Sending Your First Email

This topic explains everything about how to send your first email, from importing subscribers to Buttondown to scheduling an email to send in the future.

(Optional) Import your subscribers

If you already have a list of subscribers, you can upload that list to Buttondown as a comma-separated values, or CSV, file. If you don't, no worries! Start by reading Draft your first newsletter below.

Buttondown automatically imports the following values for each of your subscribers, if available:

• Email address
• Time joined (format this in a “month/day/year” format)
• Notes (these are completely open-ended and don’t have to follow a specific format)
• Tags
• Metadata

In either Google Sheets or Excel:

• Choose File and then Download to initiate a download of your spreadsheet.
• Select “Comma-Separated Values (.csv)” to export your CSV file.

This video shows the process to export a Google Sheet to CSV.

• In Buttondown, navigate to the Subscribers page.
• Click Import to upload your CSV file.
• After your CSV uploads, answer a series of questions to help Buttondown identify the columns of your CSV file and click Done.

This video shows the steps to import a CSV file to Buttondown and identify the columns. At the end, a confirmation screen explaining that the upload has begun appears.

If you’re uploading a large quantity of subscribers, it may take a few hours to process.

When the upload completes, your subscriber list will appear in the "Subscribers" page, with their accompanying notes, tags, and metadata.

This video shows Buttondown's "Subscribers" screen with an imported subscriber. The overflow menu expands to show configuration options, including the "Notes" section.

To learn more about downloading CSVs and importing subscribers and newsletter archives, read Importing Your Data.

Draft your first newsletter

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.

• "Preview Mode" renders your Markdown or HTML draft as you write so you can verify that your formatting looks the way you want.
• "Editor Mode" adds a toolbar you can use to format your text, add links, add images, and more.

• 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.

Send a test newsletter

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.

• Follow the procedure in Draft your first newsletter to draft an email.
• Click Send Draft. The "Choose draft recipients" modal appears.
• Enter the email address of the person you wish to receive your test newsletter and click Add recipient.
• Click Send draft.

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.

Send your first newsletter email

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 who you want to send this email to. You can send it to all your subscribers, or only those with certain tags?
• Decide if you want to send this email immediately, or schedule it for later.

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

• From the email drafting screen, click Send. The "Ready to send?" modal appears.
• Review the screen and verify everything looks correct.
• Click Send. Your email sends.

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.

Schedule your newsletter email

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.

Images

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:

• In the "Emails" page, click New in the upper right corner. The writing interface appears.
• In the rich text editor, click the Insert image button.
• Choose the image you wish to upload.

After the upload completes, the image appears in your email.

Custom unsubscribe links

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.

Tags and segmentation

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:

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

To learn more, read Tags.

Mail merges

A mail merge is a catchall term for sending out emails with specific fields changed.

For example, being able to send out an email that says something like:

Hello, {first_name}!

where "{first_name}" displays the first name of the recipient of that email.

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:

{% if subscriber.metadata.first_name %}
Hello {{ subscriber.metadata.first_name}}!
{% else %}
Hello friend!
{% endif %}

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!"

Sending emails based on an RSS feed

To learn about using an RSS feed, read RSS automation.

Things to do after you send your first email

So you've sent your newsletter's first email. That's great! What happens next?

Update your email's slug

The "slug" is the end of a URL. Each email has a unique slug. You can change the slug of an email if you need to.

If you update the slug of an email that you've already sent, don't worry! The old link that references an old slug still works. Buttondown keeps track of historical slugs for each email and redirects readers who go to the old link accordingly.

Update your email's issue number

Buttondown tries determine what issue number your newsletter is on. For example, your first email will be labeled number 1. But it doesn't always get this right. This is particularly a problem for people who have imported the archives of an existing newsletter from another system. If you need to, you can manually edit your issue numbers in your Archive page.

To edit your issue numbers:

• Navigate to the "Emails" page and find the email you wish to change the issue number for.
• Click to open the email, then click Web archive.
• Set the "Issue number" field to whatever number you like, then click Save.

The ID field corresponds with the issue number:

In particular, Buttondown will respect your existing issue numbers and always go one greater than the largest issue number, so if you change your most recent email to the number you want, everything after that will be in the correct order.

You can disable issue numbers completely by signing up for either a Standard or Professional plan.

Add share links to your email

You can customize the Social section of your account by adding sharing options in the "Suggested sharing options" section. We support most large social media and networking platforms and add more regularly.

Alternatively, you can add share links to your email by customizing your newsletter's footer in the settings page.

Then, you can add custom Markdown links using some template variables that Buttondown assigns you:

If you liked this email, please share it:

- on [Twitter](https://twitter.com/intent/tweet?url={{email_link}}&text={{email.subject}})
- on [Facebook](https://www.facebook.com/sharer/sharer.php?u={{email_url}})
- on [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url={{email_url}})

FAQs

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

A note about the in-browser preview

This is a common and unfortunate problem. The short answer is: email is weird, email inboxes are weird, and there's nothing you or I or anyone can do about it.

Buttondown's Markdown preview is meant to closely resemble an email inbox from a content perspective (links and HTML tags and all of those things appear as they should), but will never be able to accurate resemble the inbox from a stylistic perspective (things being arranged and formatted as you'd expect.)

Our friends over at Litmus have a really useful, detailed answer:

Web-based email clients (such as Outlook.com or Gmail) will certainly perform most the tasks listed above, but they also have a larger, more difficult job. They have to prepare the HTML to be converted into HTML that's safe to show within their own email client's HTML. This is a surprisingly difficult thing to do and most web-based email clients' preprocessors will err on the side of being overly restrictive and removing anything with even the slightest potential to affect the layout of their email client. We'll cover the various mistakes made by these preprocessors a little later, but you should expect this to be the second biggest cause of headaches when designing HTML emails - the first biggest cause is still to be discussed.

Why is my email all... purple?

If you're previewing multiple drafts of an email in Gmail, you might notice that the text is all purple! This isn't a Buttondown problem. This is Gmail thinking that multiple emails sent in the same day with the same subject are responses to one another, and it displays the thread of emails in a "conversation view".

Read about Gmail's conversation view:

The purple colouration is a display only feature that only exists in the display where it is being seen. It is not sent in any messages and you can use Gmail's show original feature to verify that - you will need to know a little about HTML coding.

The colour is applied to text that is repeated from a previous message in the current conversation and the reason it is visible to recipients is because they also are using Gmail and they also have copies of previous messages in the current conversation. What gets coloured in their conversation might be quite different from what gets coloured in yours.

How do I avoid the "Promotions" tab in Gmail?

Every author wants their email to be read as much as possible. Emails that show up in the "Primary" tab in Gmail are going to be read much more often than ones in secondary tabs like the Promotions tab.

The Promotions tab is not the enemy. It is your subscribers' friend. By filtering things into the Promotions tab, Gmail is making an effort to make reading email better. It's your job to make sure your email stands out.

You can help your email show up in the right place by using the same best practices you use to make sure your email doesn't end up in the spam folder:

• Avoid using too many links or images. These give the impression that the email is low-quality or used solely for directing readers elsewhere.
• Send emails that are not too short, or not too long. (500 to 750 words is a pretty good range.)
• Cull subscribers that aren't opening or interacting with your content. Gmail and other email clients care a lot about how often readers click, open, and reply to email. The more interaction an email gets, the more likely it is that it's a legitimate email the subscriber wants to read.

Unfortunately, this is not a foolproof method. There isn't one: Gmail's categorization schemes are deliberately vague. The best way to land in your subscribers' primary inbox is to produce great content.

You can read more about avoiding the Promotions tab on SalesHandy.