Buttondown logo

Creating a segment

Segment names are unique within a newsletter: creating a segment whose name already exists returns a 400 with a name_already_exists code, and the existing segment's id in the response metadata.

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/segments"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
data = {
  "name": "Executives",
  "description": "Leadership at customer accounts"
}

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

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "id": "segment_2a7wp1t3fw896bp4mrhc535z5k",
    "creation_date": "2020-09-29T00:00:00+00:00",
    "name": "Executives",
    "description": "Leadership at customer accounts",
    "filters": {
        "filters": [
            {
                "field": "subscriber.metadata.role",
                "operator": "equals",
                "value": "executive"
            }
        ],
        "groups": [],
        "predicate": "and"
    }
}

Body parameters

All parameters are optional unless explicitly specified.

name

Type
string · required
Description

A human-readable name for the segment.

Example
"Executives"

description

Type
string
Description

An optional free-form description of the segment, shown alongside its name when picking an email's audience.

Example
"Leadership at customer accounts"

filters

Type
Description

The tag- and metadata-based filter rules defining which subscribers belong to this segment.