Building your subscriber base

Now that you've got a newsletter up and running, you can think about how to add more subscribers so more people can read and engage with what you write. You might spread the word about your newsletter through social media, other publications, or simple word of mouth. However you start, potential subscribers need a place to go where they can find your newsletter and subscribe.

There are three main ways you can grow your subscriber base without writing a single line of code:

• sharing your newsletter's unique Buttondown URL
• embedding an HTML form on a webpage
• embedding an iFrame on a webpage

Every newsletter has a unique URL. When someone loads that URL, a page with the option to subscribe to your newsletter appears.

Buttondown exposes a URL endpoint that you can point any <form> tag at to get an HTML-friendly form. This is great for platforms like Wordpress or Cargo that are very HTML-friendly, as well as static site generators or JAMStack sites. Additionally, you can style this form to your heart's content.

Below is an example of a basic form that uses this endpoint:

<form
  action="
          https://buttondown.com/api/emails/embed-subscribe/YOUR-BUTTONDOWN-USERNAME
         "
  method="post"
  class="embeddable-buttondown-form"
>
  <label for="email">Email</label>
  <input type="email" name="email" placeholder="you@example.com" />
  <input type="hidden" value="1" name="embed" />
  <input type="submit" value="Subscribe" />
  <p>
    <a href="https://buttondown.com" target="_blank">
      Powered by Buttondown.
    </a>
  </p>
</form>

You can also specify one or more tags to automatically apply to new subscribers by using the tag value in your form. The following example tags a new subscriber with foo:

<input type="hidden" name="tag" value="foo" />

If you want a seamless, pre-styled way to include a subscription option on your site, the iFrame may be the tool for you. Here's an example:

<iframe
  scrolling="no"
  style="
         width: 100% !important;
         height: 220px;
         border: 1px #ccc solid !important;
        "
  src="https://buttondown.com/YOUR-BUTTONDOWN-USERNAME?as_embed=true"
></iframe>

Using query parameters

If you're using the subscribe page available at your newsletter's URL, you can automatically add new tags to new subscribers by adding a query parameter to the URL. The example below automatically gives people who subscribe through the link a tag called python:

https://buttondown.com/jmduke?tag=python

If you want to apply multiple tags at once, you can add multiple such query parameters. Here's an example:

https://buttondown.com/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. If you want to, you can supply multiple inputs. Buttondown will apply all tags.

In the example below, the value associated with the tag being passed is the name of the tag, not the ID. You can in fact use either the name or the ID and Buttondown will do the right thing (including automatically creating a tag with the given name, if no such tag exists yet).

<form
  action="
          https://buttondown.com/api/emails/embed-subscribe/YOUR-BUTTONDOWN-USERNAME
         "
  method="post"
  class="embeddable-buttondown-form"
>
  <label for="email">Email</label>
  <input type="email" name="email" placeholder="you@example.com" />
  <br />
  <label for="email">Pokemon</label>
  <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.com" target="_blank">
      Powered by Buttondown.
    </a>
  </p>
</form>

You can read our docs to learn more about tags.

Using the API

If you're feeling clever, you can update the tags of your subscribers using Buttondown's API.

The API also enables you to automatically tag users by setting up an automation.

For example, if you wanted to immediately apply a tag to any reader who clicked a link in a certain email, the automation might look like this:

{
    "id": "13121cd6-0dfc-424c-bb12-988b0a32fcb4",
    "creation_date": "2000-01-01T00:00:00+00:00",
    "name": "Very important newsletter",
    "status": "active",
    "trigger": "subscriber.clicked",
    "timing": {
        "time": "immediate",
        "delay": null
    },
    "actions": [
        {
            "type": "apply_tags",
            "metadata": {
                "tag_id": "fg6817b9-427a-ge61-0d2f-43f318712cb3",
                "action": "add"
            }
        }
    ]
}

In the example above, we use the bulk action of apply_tags to tag the users. That requires two pieces of information to be passed as metadata: The ID of the desired tag, and the action we'd like to take (add or remove)

Here are some resources for creating your own tagging automation:

• Introduction to automations
• Bulk action types
• Listing tags

On your Buttondown subscribe form

Buttondown's subscription form doesn't ask for any metadata by default. All it needs is a subscriber's email address and, if you're running a paid newsletter, their payment information.

If you want to collect more information, though, you can add custom subscribe form inputs. You can find these at the bottom of your design settings page. Inputs have three attributes:

1. A key, which corresponds with the key that will be set in the metadata for your subscriber.
2. A label, which is the text that will be displayed to the user.
3. 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

Here's an example that uses HTML:

<!-- An example of a Buttondown subscription form with metadata support. -->

<form
  action="https://buttondown.com/api/emails/embed-subscribe/YOUR-BUTTONDOWN-USERNAME"
  method="post"
  class="p-4 antialiased"
>
  <div class="pb-3">
    <label for="email" class="block pb-2 text-gray-300 font-semibold text-sm"
    >Email Address</label
      >
      <input
        id="email"
        type="email"
        name="email"
        required
        placeholder="jane@example.com"
        class="w-64 mr-2 py-2 px-3 bg-gray-400 rounded focus:outline-none focus:bg-white"
      />
    </div>

    <div class="pb-2">
      <label for="message" class="block pb-2 text-gray-300 font-semibold text-sm"
      >First name</label
        >
        <input
          id="first-name"
          type="text"
          name="metadata__first-name"
          required
          placeholder="John"
          class="w-full mr-2 py-2 px-3 bg-gray-400 rounded focus:outline-none focus:bg-white"
        />
      </div>

      <div class="pb-2">
        <label for="message" class="block pb-2 text-gray-300 font-semibold text-sm"
        >Last name</label
          >
          <input
            id="last-name"
            type="text"
            name="metadata__last-name"
            required
            placeholder="Doe"
            class="w-full mr-2 py-2 px-3 bg-gray-400 rounded focus:outline-none focus:bg-white"
          />
        </div>
        <br />

        <button
          type="submit"
          class="py-2 px-6 bg-indigo-600 rounded text-white font-bold"
        >
          Send
        </button>
      </form>

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

These inputs can be freeform text, like above, or hidden inputs if you want to invisibly augment your subscription forms with metadata. For example, you can imagine setting metadata for everyone who accesses your newsletter from a particular tag or webpage.

Another example is below:

<form
  action="
          https://buttondown.com/api/emails/embed-subscribe/YOUR-BUTTONDOWN-USERNAME
         "
  method="post"
  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.com" target="_blank">
      Powered by Buttondown.
    </a>
  </p>
</form>

You can read our docs to learn more about metadata.

To learn how to create an automated email to send to new subscribers, read Automations.

If you need to change a subscriber's address, you can go into the Notes screen for that subscriber and tap their address to change it. To learn more, watch this video.

Captcha support

We're 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 it should work.

To embed your subscription widget in Medium, all you need to do is post your newsletter's URL in Medium. It should automatically embed, thanks to the powers of oEmbed.