2025-04-14

We've expanded the subscriber filtering capabilities by adding support for UTM parameters. You can now filter subscribers by:

• utm_campaign - Find subscribers who arrived via specific marketing promotions
• utm_medium - Filter by the channel that drove subscribers (social, email, etc.)
• utm_source - Filter by the specific source of subscribers

We've also added a new unsubscription_reason filter to help you understand why subscribers are leaving.

These parameters work just like existing filters - pass them as query parameters when listing subscribers:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
params = {
  "utm_campaign": "spring_promo",
  "utm_medium": "social"
}

response = requests.request("GET", url, headers=headers, params=params)
print(response.text)