Collecting and using subscribers' data

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!

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.

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}"
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.

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.