Buttondown logo

Versioning

Whenever we make a backwards-incompatible change to the API, we release a new version of the API. (The current version is 2026-04-01.)

Buttondown determines the API version associated with a request in two ways:

  • If a request includes a header with the key X-API-Version, Buttondown will use that value as the API version.
  • If a request does not include a header with the key X-API-Version, Buttondown will use a pinned version associated with the newsletter. This pinned version can be found (and changed) in the "API" section of your settings page.
  • If a pinned version is not present on the newsletter, Buttondown will use the latest version of the API.

For example, to pin a single request to a specific version:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY",
  "X-API-Version": "2026-04-01"
}

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

Available versions

X-API-Version accepts any of the versions below; anything else is rejected with a 422 and an invalid_api_version code. Each row describes what changed in that version, so pinning to the version above a row opts out of it.

VersionWhat changed
2024-07-01The oldest version Buttondown still accepts.
2024-08-01On subscribers, subscriber_type became type and email became email_address.
2024-08-15On emails, included_tags and excluded_tags were replaced by the more expressive filters field.
2024-09-30DELETE /v1/subscribers/{id_or_email} deletes the subscriber outright instead of unsubscribing them.
2024-12-30Nothing on the wire: the last version before commenting_mode, kept so clients could pin to it.
2025-01-02On emails, is_comments_disabled was replaced by commenting_mode.
2025-05-19On bulk actions, metadata.tag became metadata.tag_id.
2025-06-01The date, last_open_date and last_click_date filters on subscribers split into __start/__end pairs, and GET /v1/emails stopped defaulting to sent and in-flight emails.
2026-01-01Responses return TypeIDs (sub_...) rather than bare UUIDs.
2026-04-01An automation's top-level timing moved inside each action. The current version.

What constitutes a backwards-incompatible change?

We consider a backwards-incompatible change to be any change that could potentially break existing code that uses the API. This includes (but is not limited to):

  • Renaming or removing fields from an object
  • Removing or renaming an endpoint
  • Changing the type of a field
  • Changing whether or not a field is required
  • Changing logic within an endpoint