Buttondown logo

2025-07-13

We've added a new source parameter to the /v1/subscribers endpoint that allows you to filter subscribers by their origin source.

What's new

You can now filter subscribers based on their source (e.g. api, import, organic, user, stripe).

Examples

Get all subscribers added via API:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
params = {
  "source": "api"
}

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

Get subscribers from multiple sources (import and organic):

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
params = {
  "source": [
    "import",
    "organic"
  ]
}

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

Combine with other filters to create more specific queries:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
params = {
  "source": "api",
  "type": "regular",
  "tag": "newsletter"
}

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

This filter works alongside all existing filters, making it easy to create powerful queries to understand your subscriber base better.

Stay informed

You can subscribe to this changelog via RSS or browse the full list of API changes.