The Segments API from Buttondown — 5 operation(s) covering saved, reusable audiences built from tag and metadata filters.
openapi: 3.1.0
info:
title: Buttondown Segments API
version: 1.0.0
description: The Buttondown API lets you manage newsletters, subscribers, emails, and more. See [the documentation](https://docs.buttondown.com/api-introduction)
for guides and examples.
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.buttondown.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Segments
paths:
/segments:
post:
operationId: create_segment
summary: Create Segment
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Segment'
links:
retrieve_segment:
operationId: retrieve_segment
parameters:
path.id: $response.body#/id
update_segment:
operationId: update_segment
parameters:
path.id: $response.body#/id
delete_segment:
operationId: delete_segment
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_SegmentErrorCode_'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Create a new segment
tags:
- Segments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentInput'
required: true
security:
- ApiKeyAuth: []
get:
operationId: list_segments
summary: List Segments
parameters:
- in: query
name: page
required: false
description: The page number of the paginated response.
schema:
type: integer
title: Page
description: The page number of the paginated response.
default: 1
example: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentPage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: List all segments
tags:
- Segments
security:
- ApiKeyAuth: []
/segments/{id}:
get:
operationId: retrieve_segment
summary: Retrieve Segment
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Segment'
links:
update_segment:
operationId: update_segment
parameters:
path.id: $response.body#/id
delete_segment:
operationId: delete_segment
parameters:
path.id: $response.body#/id
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Retrieve a specific segment by its ID
tags:
- Segments
security:
- ApiKeyAuth: []
patch:
operationId: update_segment
summary: Update Segment
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Segment'
links:
retrieve_segment:
operationId: retrieve_segment
parameters:
path.id: $response.body#/id
delete_segment:
operationId: delete_segment
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_SegmentErrorCode_'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Update a segment's properties
tags:
- Segments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentUpdateInput'
required: true
security:
- ApiKeyAuth: []
delete:
operationId: delete_segment
summary: Delete Segment
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'204':
description: No Content
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Requests permitted per minute.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp at which the window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
description: Delete a segment
tags:
- Segments
security:
- ApiKeyAuth: []
components:
schemas:
EmailFilter:
properties:
field:
anyOf:
- enum:
- subscriber.churn_date
- subscriber.click_rate
- subscriber.last_click_date
- subscriber.last_open_date
- subscriber.open_rate
- subscriber.price
- subscriber.source
- subscriber.status
- subscriber.subscription_date
- subscriber.tags
- subscriber.upgrade_date
type: string
- pattern: ^subscriber\.metadata\..+$
type: string
description: The subscriber attribute to evaluate. Must be a recognized field or a `subscriber.metadata.*` path.
title: Field
operator:
$ref: '#/components/schemas/Operator'
value:
description: The value to compare the field against.
title: Value
type: string
required:
- field
- operator
- value
title: EmailFilter
type: object
EmailFilterGroup:
properties:
filters:
description: The leaf-level filters to apply to the audience.
items:
$ref: '#/components/schemas/EmailFilter'
title: Filters
type: array
groups:
description: The nested groups to apply to the audience.
items:
$ref: '#/components/schemas/EmailFilterGroup'
title: Groups
type: array
predicate:
description: The logical operator to use when combining filters.
enum:
- and
- or
title: Predicate
type: string
required:
- filters
- groups
- predicate
title: EmailFilterGroup
type: object
ErrorMessage:
properties:
code:
description: The error code.
title: Code
type: string
detail:
description: A human-readable description of the error.
title: Detail
type: string
metadata:
additionalProperties:
type: string
default: {}
description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
how to resolve it.
title: Metadata
type: object
required:
- detail
title: ErrorMessage
type: object
ErrorMessage_SegmentErrorCode_:
properties:
code:
allOf:
- $ref: '#/components/schemas/SegmentErrorCode'
description: The error code.
detail:
description: A human-readable description of the error.
title: Detail
type: string
metadata:
additionalProperties:
type: string
default: {}
description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
how to resolve it.
title: Metadata
type: object
required:
- detail
title: ErrorMessage[SegmentErrorCode]
type: object
Operator:
enum:
- equals
- not_equals
- contains
- not_contains
- is_empty
- is_not_empty
- greater_than
- less_than
title: Operator
type: string
description: An enumeration.
Segment:
description: 'A saved, reusable audience — a named set of subscriber filters that can
be applied as the audience of an email.'
properties:
id:
description: A unique TypeID associated with the object.
title: Id
type: string
creation_date:
description: The date and time at which the object was first created.
format: date-time
title: Creation Date
type: string
name:
description: A human-readable name for the segment.
title: Name
type: string
description:
description: An optional free-form description of the segment, shown alongside its name when picking an email's
audience.
title: Description
type: string
filters:
$ref: '#/components/schemas/EmailFilterGroup'
description: The tag- and metadata-based filter rules defining which subscribers belong to this segment.
required:
- id
- creation_date
- name
- description
- filters
title: Segment
type: object
SegmentErrorCode:
description: Error codes returned when creating or updating a segment fails.
enum:
- name_already_exists
title: SegmentErrorCode
type: string
SegmentInput:
additionalProperties: false
description: Input schema for creating a new segment.
properties:
name:
description: A human-readable name for the segment.
maxLength: 100
minLength: 1
title: Name
type: string
example: Executives
description:
default: ''
description: An optional free-form description of the segment, shown alongside its name when picking an email's
audience.
title: Description
type: string
example: Leadership at customer accounts
filters:
$ref: '#/components/schemas/EmailFilterGroup'
description: The tag- and metadata-based filter rules defining which subscribers belong to this segment.
required:
- name
- filters
title: SegmentInput
type: object
SegmentPage:
properties:
results:
description: The list of results for this page.
items:
$ref: '#/components/schemas/Segment'
title: Results
type: array
next:
anyOf:
- type: string
- type: 'null'
description: The URL to the next page of results, if any.
title: Next
previous:
anyOf:
- type: string
- type: 'null'
description: The URL to the previous page of results, if any.
title: Previous
count:
description: The total number of results across all pages.
title: Count
type: integer
required:
- results
- count
title: Page[Segment]
type: object
SegmentUpdateInput:
additionalProperties: false
description: Input schema for updating an existing segment. All fields are optional.
properties:
name:
anyOf:
- maxLength: 100
minLength: 1
type: string
- type: 'null'
description: A human-readable name for the segment.
title: Name
example: Executives
description:
anyOf:
- type: string
- type: 'null'
description: An optional free-form description of the segment, shown alongside its name when picking an email's
audience.
title: Description
example: Leadership at customer accounts
filters:
anyOf:
- $ref: '#/components/schemas/EmailFilterGroup'
- type: 'null'
description: The tag- and metadata-based filter rules defining which subscribers belong to this segment.
title: SegmentUpdateInput
type: object
ValidationErrorDetail:
properties:
type:
description: The type of validation error.
title: Type
type: string
loc:
description: The location of the error in the request.
items:
anyOf:
- type: string
- type: integer
title: Loc
type: array
msg:
description: A human-readable error message.
title: Msg
type: string
required:
- type
- loc
- msg
title: ValidationErrorDetail
type: object
ValidationErrorMessage:
properties:
detail:
description: A list of validation errors.
items:
$ref: '#/components/schemas/ValidationErrorDetail'
title: Detail
type: array
required:
- detail
title: ValidationErrorMessage
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key passed as 'Token <your-api-key>' in the Authorization header.