Collecting and using subscriber metadata

When you can write a newsletter email using a subscriber’s first name, it can give a friendly, personal feeling to your words. If you’ve ever received an email that starts with “Dear [Your Name Here]” as opposed to “Dear Reader,” it’s likely that there was a mail merge or substitution string involved—and those mail merges and substitution strings rely on metadata to work properly.

Read on to learn about how you, too, can collect and use metadata to personalize your newsletter!

This is a great question! The short answer is “structured key-value data”. As of this writing, you can only apply metadata to subscribers, meaning that you can attach any sort of key-value pairs you’d like to your subscribers. This can be things like identifying information such as first and last names, so you can apply “mail merges” to your newsletter; or it could be for internal use only, such as customer IDs to tie subscribers back to your web application.

I’d recommend also reading up on Stripe’s explanation of metadata — Buttondown’s implementation and philosophy behind it is very similar.

Internally, metadata is stored as raw JSON, so you can be pretty liberal with what you place into it. (If you try and view or set metadata using the Buttondown interface, there will likely be some stringification issues — for complex use cases, it’s recommended to use the API or an integration like Zapier.)

Metadata can be nested — you can store objects and arrays within your metadata. For example:

{
  "first_name": "John",
  "address": {
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA"
  },
  "preferences": ["email", "sms"]
}

Note that while you can store metadata keys with hyphens (such as first-name), it is difficult to access that metadata when writing an email: {{ subscriber.metadata.first-name }} is a syntax error due to the templating language used by Buttondown. As a result, I recommend using underscores instead (such as first_name).

You can search for metadata in Buttondown by using the key:value notation:

At the moment, this does not work with more than one key-value pair; location:seattle industry:finance will not do what you would like it to. (It will eventually, though!)

By default, Buttondown’s subscription forms only collect subscribers’ email addresses. Without any adjustments, your subscription form will look something like this.

But with a few customizations, you can use Buttondown’s subscription forms to ask subscribers for their names, the names of the companies they work for, their interests, or any other facts that might be useful for your newsletter!

Prefer to go the manual route for updating your subscribers’ metadata? Go ahead and add your input key and value in the “Metadata” section of your subscriber’s “Notes” page. Here’s how:

1. Navigate to "Subscribers" and find the subscriber whose metadata you wish to view.
2. Click the three-dot overflow menu and choose Notes. The subscriber’s “Notes” page appears.
3. Scroll to the “Metadata” section and click Add. A key/value field opens.
4. Specify a key and value, such as “first_name” and “John”.
5. Click Add another to add more metadata, or click Save changes.

Instead of addressing emails one at a time, you can address them automatically using Buttondown’s {{ subscriber.metadata }} template variable. By plugging your “first_name” key into this template variable, you’ll direct Buttondown to retrieve each subscriber’s first name for you!

But wait! What if you don’t have first names for every subscriber? Then it’s time to break out our “If / Else” template. This lets Buttondown choose between using a first name, if one is available, and a placeholder name if not. Check out the example below.

Made a typo in a metadata key, or want to standardize your naming convention? You can rename metadata keys in bulk using the "Rename metadata" bulk action. This lets you change the key name (e.g. from name to first_name) across all of your subscribers at once, without losing any values.

To rename metadata keys:

1. Navigate to "Subscribers" and select the subscribers whose metadata you want to update (or select all).
2. In the popup tray that appears at the bottom of the screen, click the three dots at the far right and then choose "Rename metadata".
3. Enter the old key name and the new key name. You can add pairs of old and new key names to rename multiple keys at once.
4. Click Rename Metadata to apply the changes.

Want to add metadata to an existing subscriber using our API? Copy the code below and plug in your subscriber ID (which you can find in the subscriber’s “Notes”), as well as your personal API key (which you can find in the “API” section of your Buttondown settings). Then add your input key and its corresponding value.

import requests

url = "https://api.buttondown.com/v1/subscribers/{id_or_email}"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "metadata": {
    "first_name": "John"
  }
}

response = requests.request("PATCH", url, headers=headers, json=data)
print(response.text)

Run this code, and the metadata in your subscriber “Notes” should be updated and ready to go.