Building your subscriber base
There are three main ways you can grow your subscriber base without writing a single line of code:
- sharing your Buttondown URL
- embedding an HTML form
- embedding an iFrame
Sharing your Buttondown URL
Embedding an HTML form
Buttondown exposes a URL endpoint that you can point any sort of <form> tag at and get an HTML-friendly form. This is great for platforms like Wordpress or Cargo that are very HTML-friendly; additionally, you can style this form to your heart's content.
Below is an example of a basic form using this endpoint:
You can also add one (or more tags) to automatically apply to new subscribers by specifying the tag value in your form, like the following snippet (which would tag a new subscriber with foo):
<input type="hidden" name="tag" value="foo" />
Embedding an iFrame
If you want a seamless, pre-styled way to include a subscription option on your site, the iFrame may be the tool for you:
Adding tags to your subscribers
Using query parameters
If you're using Buttondown's subscribe page (e.g. https://buttondown.email/jmduke), you can automatically add new tags to new subscribers by adding a query parameter to the URL, such as:
https://buttondown.email/jmduke?tag=python
This will automatically give folks who subscribe through the link a tag named python.
If you want to apply multiple tags at once, you can add multiple such query parameters:
https://buttondown.email/jmduke?tag=python&tag=vue
Using HTML
If you'd prefer to use HTML, augment your form to add an input tag with a name of tag. (You can supply multiple inputs; Buttondown will apply all tags.)
An example is below. Note that the value associated with the tag being passed over is the name of the tag, not the ID; you can in fact supply either one and Buttondown will do the right thing (including automatically creating a tag with the given name if no such tag exists).
<formaction="https://buttondown.email/api/emails/"method="post"target="popupwindow"class="embeddable-buttondown-form"><label for="email">Email</label><inputtype="email"name="email"placeholder="you@example.com"//><label for="email">Pokemon</label><br /><input type="radio" id="Squirtle" name="tag" value="Squirtle" /><label for="Squirtle">Squirtle</label><input type="radio" id="Bulbasaur" name="tag" value="Bulbasaur" /><label for="Bulbasaur">Bulbasaur</label><input type="radio" id="Charmander" name="tag" value="Charmander" /><label for="Charmander">Charmander</label><br /><br /><input type="hidden" value="1" name="embed" /><input type="submit" value="Subscribe" /><p><a href="https://buttondown.email" target="_blank">Powered by Buttondown.</a></p></form>
Adding metadata to your subscribers
On your Buttondown subscribe form
Buttondown's subscription form doesn't ask for any metadata by default; it's only interested in your subscribers' email address. (And their payment information, if you're running a paid newsletter.)
If you're interested in collecting more information, though, you can add custom subscribe form inputs. (This is a bit of a mouthful, I know!) You can find these at the bottom of your design settings page. Inputs have three attributes:
- A key, which corresponds with the key that will be set in the metadata for your subscriber.
- A label, which is the text that will be displayed to the user.
- Whether or not the metadata is required. If the metadata is required, then the input is required to be filled out by the subscriber.
Using HTML
I'm a fan of showing, not telling, so I'll lead with the relevant code sample:
The trick is to set inputs with the name of metadata__<key>, as you can see in the code sample above:
<inputid="first-name"type="text"name="metadata__first-name"requiredplaceholder="John"/>
Note that these can be freeform text inputs, like above, or hidden inputs if you instead want to invisibly augment your subscription forms with given metadata. (For instance, you can imagine setting metadata for everyone coming through a particular tag or webpage.)
Another example playground is below:
<formaction="https://buttondown.email/api/emails/"method="post"target="popupwindow"class="embeddable-buttondown-form"><label for="email">Email</label><inputtype="email"name="email"placeholder="you@example.com"/><label for="first-name">First name</label><inputid="first-name"type="text"name="metadata__first-name"requiredplaceholder="John"/><input type="hidden" value="1" name="embed" /><input type="submit" value="Subscribe" /><p><a href="https://buttondown.email" target="_blank">Powered by Buttondown.</a></p></form>
Automatically sending an email to new subscribers
You can do this by going to your settings page and checking out the section entitled Welcome:

Dealing with spammy subscribers
Chances are, this is because you're using an embedded subscription widget and you don't have subscription confirmation turned on. First off — you should turn that on!
I'll be building out captcha support in the future as well but in the meantime, if you still are seeing lots of spammy subscribers email me and I'll take a look.
Changing an existing subscriber's email address
If you need to change a subscriber's address (maybe they emailed you asking you to do so; maybe you know that they're starting to use a new one) you can go into the Notes screen for that subscriber and tap their address to change it! I've recorded a video here showing off that process.
FAQs
Captcha support
I am piloting a program using https://www.hcaptcha.com/ and will be bringing it (on an opt-in basis) to GA soon!
Instagram's browser is a little, uh, finicky. Take out the target="popupwindow" attribute from the form tag and you should be good to go.
Medium
To embed your subscription widget in Medium, all you need to do is post the link to your newsletter (e.g. https://buttondown.email/jmduke) in Medium — it should automatically embed.