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

<form
  action="
    https://buttondown.email/api/emails/
  "
  method="post"
  target="popupwindow"
  class="embeddable-buttondown-form"
>
  <label for="email">Email</label>
  <input
    type="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:

JSFiddle

The trick is to set inputs with the name of metadata__<key>, as you can see in the code sample above:

<input
  id="first-name"
  type="text"
  name="metadata__first-name"
  required
  placeholder="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:

<form
  action="
    https://buttondown.email/api/emails/
  "
  method="post"
  target="popupwindow"
  class="embeddable-buttondown-form"
>
  <label for="email">Email</label>
  <input
    type="email"
    name="email"
    placeholder="you@example.com"
  />
  <label for="first-name">First name</label>
  <input
  id="first-name"
  type="text"
  name="metadata__first-name"
  required
  placeholder="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

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.