Tagging your subscribers

Tags are a lightweight way to group subscribers together so you can send them tailored content, trigger automations, or just keep your audience organized. A subscriber can have any number of tags, and tags can be applied automatically (via your subscribe forms or automations) or by hand.

To get started with tags, go to Settings → General and click on "Tags" in the Features section.

There are five ways to attach tags to a subscriber:

1. Adding a tag query parameter to your newsletter's subscribe URL
2. Adding hidden tag inputs to an embedded form
3. Manually tagging subscribers in the Buttondown dashboard
4. Programmatically via the API
5. Automatically via automations

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

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

To apply multiple tags at once, add multiple tag parameters:

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

If you're embedding a subscribe form on your own site, augment it with one or more input elements named tag. You can use the name of an existing tag or its ID — Buttondown will do the right thing, including auto-creating a tag with the given name if no such tag exists yet.

<input type="hidden" name="tag" value="ebook-download" />

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

When a returning subscriber submits the form again, Buttondown appends the new tags to whatever tags the subscriber already has — it doesn't replace them. This way, embedding a tagged form on a landing page (e.g. an ebook download tagged ebook-download) won't wipe out tags the subscriber picked up from other forms or automations.

You can also tag subscribers by hand. To create a new tag, go to Tags and click the "New" button in the top right. Then go to your subscribers, select the records you want to tag, and click "Add tags" in the bottom-right action bar.

You can update the tags of your subscribers programmatically using Buttondown's API. To add a tag to an existing subscriber, send a PATCH to the subscriber endpoint with the desired tags.

By default, the API replaces the subscriber's tags with the ones you send. If you want to append instead, include the X-Buttondown-Collision-Behavior: add header — see the subscriber create reference for details.

Check out the examples repo for ready-to-use code samples, and the tags API reference for full route documentation.

You can also automatically tag subscribers using an automation. For example, you could apply a tag to anyone who clicks a link in a specific email by combining a subscriber.clicked trigger with an apply_tags action.

Here are some resources for building tagging automations:

• Introduction to automations
• Bulk action types
• Listing tags

Once your subscribers are tagged, you can send a newsletter to only the people with a particular tag. When sending your email, click the "Custom…" link in the audience section, choose "Tag", and pick the tag you want to target.

For a fuller walkthrough of the audience picker, see Segmenting your audience.

If you'd like subscribers to be able to add or remove tags themselves, send them to Portal. When creating or editing a tag, enable the "Subscriber editable" option to make it appear as a checkbox in the Portal.

There's no limit. Tag names are de-duplicated within a newsletter, but you can have as many distinct tags as you'd like.