{ "openapi": "3.1.0", "info": { "title": "Buttondown 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" } }, "paths": { "/accounts/me": { "get": { "operationId": "get_account", "summary": "Get Account", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve the account associated with the current API key", "tags": [ "Accounts" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/advertising_units": { "get": { "operationId": "list_advertising_units", "summary": "List Advertising Units", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingUnitPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all advertising units", "tags": [ "Advertising Units" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "operationId": "create_advertising_unit", "summary": "Create Advertising Unit", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingUnit" } } }, "links": { "update_advertising_unit": { "operationId": "update_advertising_unit", "parameters": { "path.id": "$response.body#/id" } }, "delete_advertising_unit": { "operationId": "delete_advertising_unit", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new advertising unit", "tags": [ "Advertising Units" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingUnitInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/advertising_units/{id}": { "patch": { "operationId": "update_advertising_unit", "summary": "Update Advertising Unit", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingUnit" } } }, "links": { "delete_advertising_unit": { "operationId": "delete_advertising_unit", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an advertising unit's properties", "tags": [ "Advertising Units" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingUnitUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_advertising_unit", "summary": "Delete Advertising Unit", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an advertising unit", "tags": [ "Advertising Units" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/advertising_units/slots": { "get": { "operationId": "list_advertising_slots", "summary": "List Advertising Slots", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingSlotPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all advertising slots", "tags": [ "Advertising Units" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/advertising_units/slots/{id}": { "patch": { "operationId": "update_advertising_slot", "summary": "Update Advertising Slot", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingSlot" } } }, "links": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an advertising slot's sponsor content", "tags": [ "Advertising Units" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingSlotUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api_requests/{id}": { "get": { "operationId": "retrieve_api_request", "summary": "Retrieve Api Request", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIRequestDetail" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific API request by its ID", "tags": [ "API Requests" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api_requests": { "get": { "operationId": "list_api_requests", "summary": "List Api Requests", "parameters": [ { "in": "query", "name": "api_key_id", "schema": { "default": [], "description": "If provided, only return requests made with the given [API key](https://docs.buttondown.com/api-authentication) ID(s).", "items": { "type": "string" }, "title": "Api Key Id", "type": "array" }, "required": false, "description": "If provided, only return requests made with the given [API key](https://docs.buttondown.com/api-authentication) ID(s)." }, { "in": "query", "name": "creation_date__gt", "schema": { "description": "If provided, only return requests created after the given datetime.", "example": "2024-01-01T00:00:00Z", "title": "Creation Date Gt", "format": "date-time", "type": "string" }, "required": false, "description": "If provided, only return requests created after the given datetime.", "example": "2024-01-01T00:00:00Z" }, { "in": "query", "name": "creation_date__lt", "schema": { "description": "If provided, only return requests created before the given datetime.", "example": "2024-12-31T23:59:59Z", "title": "Creation Date Lt", "format": "date-time", "type": "string" }, "required": false, "description": "If provided, only return requests created before the given datetime.", "example": "2024-12-31T23:59:59Z" }, { "in": "query", "name": "date__end", "schema": { "description": "If provided, only return requests created on or before the given date.", "title": "Date End", "format": "date", "type": "string" }, "required": false, "description": "If provided, only return requests created on or before the given date." }, { "in": "query", "name": "date__start", "schema": { "description": "If provided, only return requests created on or after the given date.", "title": "Date Start", "format": "date", "type": "string" }, "required": false, "description": "If provided, only return requests created on or after the given date." }, { "in": "query", "name": "limit", "schema": { "description": "The maximum number of results to return per page.", "example": 100, "title": "Limit", "type": "integer" }, "required": false, "description": "The maximum number of results to return per page.", "example": 100 }, { "in": "query", "name": "method", "schema": { "description": "If provided, only return requests with the given HTTP method(s).", "example": [ "GET", "POST" ], "items": { "type": "string" }, "title": "Method", "type": "array" }, "required": false, "description": "If provided, only return requests with the given HTTP method(s).", "example": [ "GET", "POST" ] }, { "in": "query", "name": "path", "schema": { "default": [], "description": "If provided, only return requests matching the given API path(s).", "items": { "type": "string" }, "title": "Path", "type": "array" }, "required": false, "description": "If provided, only return requests matching the given API path(s)." }, { "in": "query", "name": "source", "schema": { "description": "If provided, only return requests from the given source(s).", "example": [ "api" ], "items": { "$ref": "#/components/schemas/APIRequestSource" }, "title": "Source", "type": "array" }, "required": false, "description": "If provided, only return requests from the given source(s).", "example": [ "api" ] }, { "in": "query", "name": "status_code", "schema": { "description": "If provided, only return requests with the given HTTP status code(s).", "example": [ "200", "404" ], "items": { "type": "string" }, "title": "Status Code", "type": "array" }, "required": false, "description": "If provided, only return requests with the given HTTP status code(s).", "example": [ "200", "404" ] }, { "in": "query", "name": "version", "schema": { "description": "If provided, only return requests made with the given [API version](https://docs.buttondown.com/api-versioning)(s).", "title": "Version", "items": { "enum": [ "2024-07-01", "2024-08-01", "2024-08-15", "2024-09-30", "2024-12-30", "2025-01-02", "2025-05-19", "2025-06-01", "2026-01-01", "2026-04-01" ], "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return requests made with the given [API version](https://docs.buttondown.com/api-versioning)(s)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIRequestList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all API requests", "tags": [ "API Requests" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/attachments": { "post": { "operationId": "create_attachment", "summary": "Create Attachment", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } }, "links": { "retrieve_attachment": { "operationId": "retrieve_attachment", "parameters": { "path.id": "$response.body#/id" } }, "delete_attachment": { "operationId": "delete_attachment", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Upload a new attachment", "tags": [ "Attachments" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "title": "File", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "required": [ "file" ], "title": "MultiPartBodyParams", "type": "object" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_attachments", "summary": "List Attachments", "parameters": [ { "in": "query", "name": "ids", "schema": { "description": "If provided, only return attachments matching the given IDs.", "example": [ "att_01h8xg4j3k2m1n0p9q8r7s6t5v" ], "title": "Ids", "items": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:att)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return attachments matching the given IDs.", "example": [ "att_01h8xg4j3k2m1n0p9q8r7s6t5v" ] }, { "in": "query", "name": "page_size", "schema": { "default": 100, "description": "The number of results per page.", "title": "Page Size", "maximum": 1000, "minimum": 1, "type": "integer" }, "required": false, "description": "The number of results per page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all attachments", "tags": [ "Attachments" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/attachments/{id}": { "get": { "operationId": "retrieve_attachment", "summary": "Retrieve Attachment", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } }, "links": { "delete_attachment": { "operationId": "delete_attachment", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve an attachment", "tags": [ "Attachments" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_attachment", "summary": "Delete Attachment", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an attachment", "tags": [ "Attachments" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/automations": { "get": { "operationId": "list_automations", "summary": "List Automations", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all automations", "tags": [ "Automations" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "operationId": "create_automation", "summary": "Create Automation", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } }, "links": { "retrieve_automation": { "operationId": "retrieve_automation", "parameters": { "path.id": "$response.body#/id" } }, "update_automation": { "operationId": "update_automation", "parameters": { "path.id": "$response.body#/id" } }, "delete_automation": { "operationId": "delete_automation", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_AutomationCreationErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new automation", "tags": [ "Automations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/automations/{id}": { "get": { "operationId": "retrieve_automation", "summary": "Retrieve Automation", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } }, "links": { "update_automation": { "operationId": "update_automation", "parameters": { "path.id": "$response.body#/id" } }, "delete_automation": { "operationId": "delete_automation", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific automation by its ID", "tags": [ "Automations" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_automation", "summary": "Update Automation", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } }, "links": { "retrieve_automation": { "operationId": "retrieve_automation", "parameters": { "path.id": "$response.body#/id" } }, "delete_automation": { "operationId": "delete_automation", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an automation's properties", "tags": [ "Automations" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_automation", "summary": "Delete Automation", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an automation", "tags": [ "Automations" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/automations/{id}/invoke": { "post": { "operationId": "invoke_automation", "summary": "Invoke Automation", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Manually trigger an automation", "tags": [ "Automations" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/automations/{id}/analytics": { "get": { "operationId": "retrieve_automation_analytics", "summary": "Retrieve Automation Analytics", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analytics" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve analytics data for an automation", "tags": [ "Automations" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/books": { "post": { "operationId": "create_book", "summary": "Create Book", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "links": { "retrieve_book": { "operationId": "retrieve_book", "parameters": { "path.id": "$response.body#/id" } }, "update_book": { "operationId": "update_book", "parameters": { "path.id": "$response.body#/id" } }, "delete_book": { "operationId": "delete_book", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "Create a new book", "tags": [ "Books" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_books", "summary": "List Books", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookPage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" } }, "description": "List all books for the authenticated newsletter", "tags": [ "Books" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/books/{id}": { "get": { "operationId": "retrieve_book", "summary": "Retrieve Book", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "links": { "update_book": { "operationId": "update_book", "parameters": { "path.id": "$response.body#/id" } }, "delete_book": { "operationId": "delete_book", "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" } } } }, "409": { "description": "Conflict" } }, "description": "Retrieve a specific book by its ID", "tags": [ "Books" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_book", "summary": "Update Book", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Book" } } }, "links": { "retrieve_book": { "operationId": "retrieve_book", "parameters": { "path.id": "$response.body#/id" } }, "delete_book": { "operationId": "delete_book", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "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" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "Update a book's properties", "tags": [ "Books" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_book", "summary": "Delete Book", "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" } } } }, "409": { "description": "Conflict" } }, "description": "Delete a book", "tags": [ "Books" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/bulk_actions": { "post": { "operationId": "create_bulk_action", "summary": "Create Bulk Action", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAction" } } }, "links": { "retrieve_bulk_action": { "operationId": "retrieve_bulk_action", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new bulk action", "tags": [ "Bulk Actions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bulk_actions/{id}": { "get": { "operationId": "retrieve_bulk_action", "summary": "Retrieve Bulk Action", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAction" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve the status of a bulk action", "tags": [ "Bulk Actions" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/comments": { "post": { "operationId": "create_comment", "summary": "Create Comment", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } }, "links": { "retrieve_comment": { "operationId": "retrieve_comment", "parameters": { "path.id": "$response.body#/id" } }, "update_comment": { "operationId": "update_comment", "parameters": { "path.id": "$response.body#/id" } }, "delete_comment": { "operationId": "delete_comment", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new comment or reply to an existing comment. If subscriber_id is provided, the comment is attributed to that subscriber; otherwise it is attributed to the newsletter author.", "tags": [ "Comments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_comments", "summary": "List Comments", "parameters": [ { "in": "query", "name": "email_id", "schema": { "description": "If provided, only return comments for the given [email](https://docs.buttondown.com/api-emails-introduction).", "example": [ "em_01h8xg4j3k2m1n0p9q8r7s6t5v" ], "title": "Email Id", "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "required": false, "description": "If provided, only return comments for the given [email](https://docs.buttondown.com/api-emails-introduction).", "example": [ "em_01h8xg4j3k2m1n0p9q8r7s6t5v" ] }, { "in": "query", "name": "subscriber_id", "schema": { "description": "If provided, only return comments for the given [subscriber](https://docs.buttondown.com/api-subscribers-introduction).", "example": [ "sub_01h8xg4j3k2m1n0p9q8r7s6t5v" ], "title": "Subscriber Id", "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "required": false, "description": "If provided, only return comments for the given [subscriber](https://docs.buttondown.com/api-subscribers-introduction).", "example": [ "sub_01h8xg4j3k2m1n0p9q8r7s6t5v" ] }, { "in": "query", "name": "parent_id", "schema": { "description": "If provided, only return comments that are replies to the given parent comment.", "example": [ "com_01h8xg4j3k2m1n0p9q8r7s6t5v" ], "title": "Parent Id", "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:com)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "required": false, "description": "If provided, only return comments that are replies to the given parent comment.", "example": [ "com_01h8xg4j3k2m1n0p9q8r7s6t5v" ] }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field. (Only supported fields: 'subscriber', 'email').", "items": { "enum": [ "subscriber", "email" ], "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field. (Only supported fields: 'subscriber', 'email')." }, { "in": "query", "name": "ordering", "schema": { "allOf": [ { "enum": [ "creation_date", "-creation_date", "email", "-email", "subscriber", "-subscriber" ], "title": "Ordering", "type": "string" } ], "default": "-creation_date", "description": "The ordering to apply to the results.", "example": "-creation_date" }, "required": false, "description": "The ordering to apply to the results.", "example": "-creation_date" }, { "in": "query", "name": "status", "schema": { "description": "If provided, only return comments with the given status. Only the newsletter owner can filter by status; subscribers always see active comments.", "$ref": "#/components/schemas/CommentStatus" }, "required": false, "description": "If provided, only return comments with the given status. Only the newsletter owner can filter by status; subscribers always see active comments." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all comments", "tags": [ "Comments" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/comments/{id}": { "get": { "operationId": "retrieve_comment", "summary": "Retrieve Comment", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } }, "links": { "update_comment": { "operationId": "update_comment", "parameters": { "path.id": "$response.body#/id" } }, "delete_comment": { "operationId": "delete_comment", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific comment by its ID", "tags": [ "Comments" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_comment", "summary": "Update Comment", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } }, "links": { "retrieve_comment": { "operationId": "retrieve_comment", "parameters": { "path.id": "$response.body#/id" } }, "delete_comment": { "operationId": "delete_comment", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a comment's status. Only the newsletter owner can call this.", "tags": [ "Comments" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_comment", "summary": "Delete Comment", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "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" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a comment. Only the comment owner (subscriber) or the newsletter author can delete a comment.", "tags": [ "Comments" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/coupons": { "get": { "operationId": "list_coupons", "summary": "List Coupons", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCouponPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all Stripe coupons", "tags": [ "Coupons" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails": { "post": { "operationId": "create_email", "summary": "Create Email", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "links": { "retrieve_email": { "operationId": "retrieve_email", "parameters": { "path.id": "$response.body#/id" } }, "update_email": { "operationId": "update_email", "parameters": { "path.id": "$response.body#/id" } }, "delete_email": { "operationId": "delete_email", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_EmailCreationErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new email", "tags": [ "Emails" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_emails", "summary": "List Emails", "parameters": [ { "in": "query", "name": "status", "schema": { "description": "If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) with the given status.", "items": { "$ref": "#/components/schemas/EmailStatus" }, "title": "Status", "type": "array" }, "required": false, "description": "If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) with the given status." }, { "in": "query", "name": "-status", "schema": { "description": "If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) without the given status.", "example": [ "draft" ], "items": { "$ref": "#/components/schemas/EmailStatus" }, "title": "-Status", "type": "array" }, "required": false, "description": "If provided, only return [emails](https://docs.buttondown.com/api-emails-introduction) without the given status.", "example": [ "draft" ] }, { "in": "query", "name": "ids", "schema": { "description": "If provided, only return emails with the given IDs.", "items": { "type": "string" }, "title": "Ids", "type": "array" }, "required": false, "description": "If provided, only return emails with the given IDs." }, { "in": "query", "name": "ordering", "schema": { "allOf": [ { "enum": [ "creation_date", "-creation_date", "status", "-status", "publish_date", "-publish_date", "subject", "-subject", "email_type", "-email_type", "modification_date", "-modification_date", "clicks", "-clicks", "opens", "-opens", "click_rate", "-click_rate", "open_rate", "-open_rate", "page_views_lifetime", "-page_views_lifetime", "page_views_30", "-page_views_30", "page_views_7", "-page_views_7", "webmentions", "-webmentions", "subscriptions", "-subscriptions", "paid_subscriptions", "-paid_subscriptions", "unsubscriptions", "-unsubscriptions", "replies", "-replies", "comments", "-comments", "social_mentions", "-social_mentions", "permanent_failure_rate", "-permanent_failure_rate", "complaint_rate", "-complaint_rate" ], "title": "Ordering", "type": "string" } ], "default": "creation_date", "description": "The ordering to apply to the results.", "example": "-publish_date" }, "required": false, "description": "The ordering to apply to the results.", "example": "-publish_date" }, { "in": "query", "name": "creation_date__start", "schema": { "description": "If provided, only return emails created after the given date.", "title": "Creation Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return emails created after the given date." }, { "in": "query", "name": "creation_date__end", "schema": { "description": "If provided, only return emails created before the given date.", "title": "Creation Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return emails created before the given date." }, { "in": "query", "name": "publish_date__start", "schema": { "description": "If provided, only return emails published after the given date.", "title": "Publish Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return emails published after the given date." }, { "in": "query", "name": "publish_date__end", "schema": { "description": "If provided, only return emails published before the given date.", "title": "Publish Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return emails published before the given date." }, { "in": "query", "name": "excluded_fields", "schema": { "description": "If provided, exclude the given field(s) from the response. This can improve performance for large responses.", "example": [ "body" ], "items": { "$ref": "#/components/schemas/EmailExcludableField" }, "title": "Excluded Fields", "type": "array" }, "required": false, "description": "If provided, exclude the given field(s) from the response. This can improve performance for large responses.", "example": [ "body" ] }, { "in": "query", "name": "source", "schema": { "description": "If provided, only return emails from the given source(s).", "example": [ "api" ], "items": { "$ref": "#/components/schemas/EmailSource" }, "title": "Source", "type": "array" }, "required": false, "description": "If provided, only return emails from the given source(s).", "example": [ "api" ] }, { "in": "query", "name": "archival_mode", "schema": { "description": "If provided, only return emails with the given archival mode.", "items": { "$ref": "#/components/schemas/ArchivalMode" }, "title": "Archival Mode", "type": "array" }, "required": false, "description": "If provided, only return emails with the given archival mode." }, { "in": "query", "name": "email_type", "schema": { "deprecated": true, "description": "The type of emails to return. Defaults to all types.", "items": { "$ref": "#/components/schemas/EmailType" }, "title": "Email Type", "type": "array" }, "required": false, "description": "The type of emails to return. Defaults to all types.", "deprecated": true }, { "in": "query", "name": "subject", "schema": { "description": "If provided, only return emails with a subject that contains the given string.", "title": "Subject", "type": "string" }, "required": false, "description": "If provided, only return emails with a subject that contains the given string." }, { "in": "query", "name": "attachments", "schema": { "description": "If provided, only return emails with the given attachments.", "items": { "type": "string" }, "title": "Attachments", "type": "array" }, "required": false, "description": "If provided, only return emails with the given attachments." }, { "in": "query", "name": "snippet_id", "schema": { "description": "If provided, only return emails that reference the given [snippets](https://docs.buttondown.com/api-snippets-introduction).", "items": { "type": "string" }, "title": "Snippet Id", "type": "array" }, "required": false, "description": "If provided, only return emails that reference the given [snippets](https://docs.buttondown.com/api-snippets-introduction)." }, { "in": "query", "name": "deliveries__start", "schema": { "description": "If provided, only return emails with at least this many deliveries.", "example": 100, "title": "Deliveries Start", "type": "integer" }, "required": false, "description": "If provided, only return emails with at least this many deliveries.", "example": 100 }, { "in": "query", "name": "deliveries__end", "schema": { "description": "If provided, only return emails with at most this many deliveries.", "example": 1000, "title": "Deliveries End", "type": "integer" }, "required": false, "description": "If provided, only return emails with at most this many deliveries.", "example": 1000 }, { "in": "query", "name": "click_rate__start", "schema": { "description": "If provided, only return emails with a click rate greater than or equal to the given value.", "example": 0.1, "title": "Click Rate Start", "type": "number" }, "required": false, "description": "If provided, only return emails with a click rate greater than or equal to the given value.", "example": 0.1 }, { "in": "query", "name": "click_rate__end", "schema": { "description": "If provided, only return emails with a click rate less than or equal to the given value.", "example": 0.5, "title": "Click Rate End", "type": "number" }, "required": false, "description": "If provided, only return emails with a click rate less than or equal to the given value.", "example": 0.5 }, { "in": "query", "name": "open_rate__start", "schema": { "description": "If provided, only return emails with an open rate greater than or equal to the given value.", "example": 0.2, "title": "Open Rate Start", "type": "number" }, "required": false, "description": "If provided, only return emails with an open rate greater than or equal to the given value.", "example": 0.2 }, { "in": "query", "name": "open_rate__end", "schema": { "description": "If provided, only return emails with an open rate less than or equal to the given value.", "example": 0.8, "title": "Open Rate End", "type": "number" }, "required": false, "description": "If provided, only return emails with an open rate less than or equal to the given value.", "example": 0.8 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_EmailListErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all emails", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails/{id}": { "patch": { "operationId": "update_email", "summary": "Update Email", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "links": { "retrieve_email": { "operationId": "retrieve_email", "parameters": { "path.id": "$response.body#/id" } }, "delete_email": { "operationId": "delete_email", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an email's properties", "tags": [ "Emails" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "retrieve_email", "summary": "Retrieve Email", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "links": { "update_email": { "operationId": "update_email", "parameters": { "path.id": "$response.body#/id" } }, "delete_email": { "operationId": "delete_email", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific email by its ID", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_email", "summary": "Delete Email", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an email", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails/{id}/history": { "get": { "operationId": "retrieve_email_history", "summary": "Retrieve Email History", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field.", "items": { "const": "user", "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." }, { "in": "query", "name": "field", "schema": { "description": "The field to retrieve history for.", "title": "Field", "type": "string" }, "required": true, "description": "The field to retrieve history for." }, { "in": "query", "name": "page", "schema": { "description": "The page number of the paginated response.", "example": 1, "title": "Page", "type": "integer" }, "required": false, "description": "The page number of the paginated response.", "example": 1 }, { "in": "query", "name": "ordering", "schema": { "default": "creation_date", "description": "The ordering to apply to the results.", "enum": [ "creation_date", "-creation_date" ], "title": "Ordering", "type": "string" }, "required": false, "description": "The ordering to apply to the results." }, { "in": "query", "name": "query", "schema": { "description": "If provided, only return history entries matching the given query.", "title": "Query", "type": "string" }, "required": false, "description": "If provided, only return history entries matching the given query." }, { "in": "query", "name": "page_size", "schema": { "default": 100, "description": "The number of results per page.", "title": "Page Size", "type": "integer" }, "required": false, "description": "The number of results per page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve the edit history for a specific email", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails/{id}/history/body/{history_id}": { "get": { "operationId": "retrieve_email_history_by_id", "summary": "Retrieve Email History By Id", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "path", "name": "history_id", "schema": { "title": "History Id", "type": "integer" }, "required": true }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field.", "items": { "const": "user", "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/History" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific historical version of an email's body", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails/{id}/analytics": { "get": { "operationId": "retrieve_email_analytics", "summary": "Retrieve Email Analytics", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analytics" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve analytics for a specific email", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails/{id}/renders": { "get": { "operationId": "retrieve_email_renders", "summary": "Retrieve Email Renders", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "query", "name": "target", "schema": { "description": "The target format for the rendered HTML. Use 'email' for rendered_html_for_email or 'html' for rendered_html_for_web.", "enum": [ "email", "html" ], "title": "Target", "type": "string" }, "required": true, "description": "The target format for the rendered HTML. Use 'email' for rendered_html_for_email or 'html' for rendered_html_for_web." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Render" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve rendered HTML for a specific email", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/emails/{id}/send-draft": { "post": { "operationId": "send_draft", "summary": "Send Draft", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Send a draft email to specific recipients", "tags": [ "Emails" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDraftInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/events": { "get": { "operationId": "list_events", "summary": "List Events", "parameters": [ { "in": "query", "name": "event_type", "schema": { "description": "If provided, only return events of the given type (e.g. `delivered`, `opened`, `clicked`).", "$ref": "#/components/schemas/EmailEventType" }, "required": false, "description": "If provided, only return events of the given type (e.g. `delivered`, `opened`, `clicked`)." }, { "in": "query", "name": "ordering", "schema": { "allOf": [ { "enum": [ "creation_date", "-creation_date" ], "title": "Ordering", "type": "string" } ], "default": "-creation_date", "description": "The ordering to apply to the results." }, "required": false, "description": "The ordering to apply to the results." }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field. (Only supported field: 'subscriber').", "items": { "enum": [ "automation", "subscriber", "email" ], "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field. (Only supported field: 'subscriber')." }, { "in": "query", "name": "email_id", "schema": { "description": "If provided, only return events for the given email.", "title": "Email Id", "type": "string" }, "required": false, "description": "If provided, only return events for the given email." }, { "in": "query", "name": "automation_id", "schema": { "description": "If provided, only return events for the given automation.", "title": "Automation Id", "type": "string" }, "required": false, "description": "If provided, only return events for the given automation." }, { "in": "query", "name": "subscriber_id", "schema": { "description": "If provided, only return events for the given subscriber.", "title": "Subscriber Id", "type": "string" }, "required": false, "description": "If provided, only return events for the given subscriber." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEventPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all events", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/events/{id}": { "get": { "operationId": "get_event", "summary": "Get Event", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field. (Only supported field: 'subscriber').", "items": { "enum": [ "automation", "subscriber", "email" ], "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field. (Only supported field: 'subscriber')." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEvent" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific event by its ID", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/exports": { "post": { "operationId": "create_export", "summary": "Create Export", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } }, "links": { "retrieve_export": { "operationId": "retrieve_export", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreateExportErrorCode_" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new data export", "tags": [ "Exports" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_exports", "summary": "List Exports", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all exports", "tags": [ "Exports" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/exports/{id}": { "get": { "operationId": "retrieve_export", "summary": "Retrieve Export", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } }, "links": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific export by its ID", "tags": [ "Exports" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/external_feeds": { "post": { "operationId": "create_external_feed", "summary": "Create External Feed", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeed" } } }, "links": { "retrieve_external_feed": { "operationId": "retrieve_external_feed", "parameters": { "path.id": "$response.body#/id" } }, "update_external_feed": { "operationId": "update_external_feed", "parameters": { "path.id": "$response.body#/id" } }, "delete_external_feed": { "operationId": "delete_external_feed", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new external feed", "tags": [ "External Feeds" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeedInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_external_feed", "summary": "List External Feed", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeedPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all external feeds", "tags": [ "External Feeds" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/external_feeds/{id}": { "patch": { "operationId": "update_external_feed", "summary": "Update External Feed", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeed" } } }, "links": { "retrieve_external_feed": { "operationId": "retrieve_external_feed", "parameters": { "path.id": "$response.body#/id" } }, "delete_external_feed": { "operationId": "delete_external_feed", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an external feed's properties", "tags": [ "External Feeds" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeedUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_external_feed", "summary": "Delete External Feed", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an external feed", "tags": [ "External Feeds" ], "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "retrieve_external_feed", "summary": "Retrieve External Feed", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeed" } } }, "links": { "update_external_feed": { "operationId": "update_external_feed", "parameters": { "path.id": "$response.body#/id" } }, "delete_external_feed": { "operationId": "delete_external_feed", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific external feed by its ID", "tags": [ "External Feeds" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/external_feeds/{id}/items": { "post": { "operationId": "poll_items", "summary": "Poll Items", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Poll for new items in an external feed", "tags": [ "External Feeds" ], "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "retrieve_items", "summary": "Retrieve Items", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field.", "items": { "const": "email", "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalFeedItemPage" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve items from an external feed", "tags": [ "External Feeds" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/forms": { "post": { "operationId": "create_form", "summary": "Create Form", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } }, "links": { "retrieve_form": { "operationId": "retrieve_form", "parameters": { "path.id": "$response.body#/id" } }, "update_form": { "operationId": "update_form", "parameters": { "path.id": "$response.body#/id" } }, "delete_form": { "operationId": "delete_form", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreateFormErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new form", "tags": [ "Forms" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_forms", "summary": "List Forms", "parameters": [ { "in": "query", "name": "status", "schema": { "description": "If provided, only return forms with the given status.", "example": [ "active" ], "items": { "$ref": "#/components/schemas/FormStatus" }, "title": "Status", "type": "array" }, "required": false, "description": "If provided, only return forms with the given status.", "example": [ "active" ] }, { "in": "query", "name": "-status", "schema": { "description": "If provided, only return forms without the given status.", "example": [ "disabled" ], "items": { "$ref": "#/components/schemas/FormStatus" }, "title": "-Status", "type": "array" }, "required": false, "description": "If provided, only return forms without the given status.", "example": [ "disabled" ] }, { "in": "query", "name": "admin", "schema": { "description": "If provided, filter by admin-only flag.", "title": "Admin", "type": "boolean" }, "required": false, "description": "If provided, filter by admin-only flag." }, { "in": "query", "name": "ordering", "schema": { "allOf": [ { "enum": [ "creation_date", "-creation_date", "title", "-title", "slug", "-slug", "status", "-status" ], "title": "Ordering", "type": "string" } ], "default": "-creation_date", "description": "The ordering to apply to the results.", "example": "-creation_date" }, "required": false, "description": "The ordering to apply to the results.", "example": "-creation_date" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all forms", "tags": [ "Forms" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/forms/{id}": { "get": { "operationId": "retrieve_form", "summary": "Retrieve Form", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } }, "links": { "update_form": { "operationId": "update_form", "parameters": { "path.id": "$response.body#/id" } }, "delete_form": { "operationId": "delete_form", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific form by its ID", "tags": [ "Forms" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_form", "summary": "Update Form", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } }, "links": { "retrieve_form": { "operationId": "retrieve_form", "parameters": { "path.id": "$response.body#/id" } }, "delete_form": { "operationId": "delete_form", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a form's properties", "tags": [ "Forms" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_form", "summary": "Delete Form", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a form", "tags": [ "Forms" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/images": { "post": { "operationId": "create_image", "summary": "Create Image", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Image" } } }, "links": { "update_image": { "operationId": "update_image", "parameters": { "path.id": "$response.body#/id" } }, "delete_image": { "operationId": "delete_image", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Upload an image", "tags": [ "Images" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "image": { "format": "binary", "title": "Image", "type": "string" }, "metadata": { "default": "{}", "title": "Metadata", "type": "string" } }, "required": [ "image" ], "title": "MultiPartBodyParams", "type": "object" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_images", "summary": "List Images", "parameters": [ { "in": "query", "name": "ids", "schema": { "description": "If provided, only return images matching the given IDs.", "title": "Ids", "example": [ "img_01h8xg4j3k2m1n0p9q8r7s6t5v" ], "items": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:img)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return images matching the given IDs.", "example": [ "img_01h8xg4j3k2m1n0p9q8r7s6t5v" ] }, { "in": "query", "name": "page_size", "schema": { "default": 100, "description": "The number of results per page.", "title": "Page Size", "maximum": 1000, "minimum": 1, "type": "integer" }, "required": false, "description": "The number of results per page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagePage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all uploaded images", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/images/{id}": { "patch": { "operationId": "update_image", "summary": "Update Image", "parameters": [ { "in": "path", "name": "id", "schema": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:img)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Image" } } }, "links": { "delete_image": { "operationId": "delete_image", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an image's metadata", "tags": [ "Images" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_image", "summary": "Delete Image", "parameters": [ { "in": "path", "name": "id", "schema": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:img)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an uploaded image", "tags": [ "Images" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/imports": { "get": { "operationId": "list_imports", "summary": "List Imports", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all imports", "tags": [ "Imports" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "operationId": "create_import", "summary": "Create Import", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } }, "links": { "retrieve_import": { "operationId": "retrieve_import", "parameters": { "path.id": "$response.body#/id" } }, "update_import": { "operationId": "update_import", "parameters": { "path.id": "$response.body#/id" } }, "delete_import": { "operationId": "delete_import", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreateImportErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new import by uploading a file", "tags": [ "Imports" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "title": "File", "type": "string" }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metadata" } }, "required": [ "file" ], "title": "MultiPartBodyParams", "type": "object" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/imports/{id}": { "get": { "operationId": "retrieve_import", "summary": "Retrieve Import", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } }, "links": { "update_import": { "operationId": "update_import", "parameters": { "path.id": "$response.body#/id" } }, "delete_import": { "operationId": "delete_import", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific import by its ID", "tags": [ "Imports" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_import", "summary": "Update Import", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } }, "links": { "retrieve_import": { "operationId": "retrieve_import", "parameters": { "path.id": "$response.body#/id" } }, "delete_import": { "operationId": "delete_import", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update an import's properties", "tags": [ "Imports" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImportInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_import", "summary": "Delete Import", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete an import", "tags": [ "Imports" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/newsletters": { "get": { "operationId": "list_newsletters", "summary": "List Newsletters", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all newsletters", "tags": [ "Newsletters" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "operationId": "create_newsletter", "summary": "Create Newsletter", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Newsletter" } } }, "links": { "update_newsletter": { "operationId": "update_newsletter", "parameters": { "path.id": "$response.body#/id" } }, "delete_newsletter": { "operationId": "delete_newsletter", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreateNewsletterErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new newsletter", "tags": [ "Newsletters" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/newsletters/{id}": { "patch": { "operationId": "update_newsletter", "summary": "Update Newsletter", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Newsletter" } } }, "links": { "delete_newsletter": { "operationId": "delete_newsletter", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a newsletter's settings", "tags": [ "Newsletters" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_newsletter", "summary": "Delete Newsletter", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a newsletter", "tags": [ "Newsletters" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/notes": { "post": { "operationId": "create_note_endpoint", "summary": "Create Note Endpoint", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } }, "links": { "delete_note_endpoint": { "operationId": "delete_note_endpoint", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "409": { "description": "Conflict" } }, "description": "Create a new note", "tags": [ "Notes" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_notes", "summary": "List Notes", "parameters": [ { "in": "query", "name": "model_type", "schema": { "description": "Filter notes by the type of object they are attached to.", "title": "Model Type", "enum": [ "automation", "comment", "conversation", "email", "external_feed", "invitation", "socialmention", "stripe_customer", "subscriber", "survey", "tag", "webmention" ], "type": "string" }, "required": false, "description": "Filter notes by the type of object they are attached to." }, { "in": "query", "name": "model_id", "schema": { "description": "Filter notes by the UUID or TypeID of the object they are attached to.", "title": "Model Id", "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:permission|unsub_req|auth_tok|rec_code|webauthn|api_req|aut_att|ext_evt|str_cus|str_sub|sub_imp|sub_tag|adslot|em_dom|em_evt|em_imp|le_evt|str_pd|adsku|socmn|webmn|book|bulk|cnvs|form|hook|inbx|news|note|resp|rssi|snip|snpr|acc|att|aut|com|exp|img|inv|mes|rss|smp|srv|sub|dr|em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "required": false, "description": "Filter notes by the UUID or TypeID of the object they are attached to." }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field.", "items": { "const": "user", "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotePage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "List all notes", "tags": [ "Notes" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/notes/{id}": { "delete": { "operationId": "delete_note_endpoint", "summary": "Delete Note Endpoint", "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" } } } }, "409": { "description": "Conflict" } }, "description": "Delete a note", "tags": [ "Notes" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/ping": { "get": { "operationId": "ping", "summary": "Ping", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "409": { "description": "Conflict" } }, "description": "Check if the API is reachable and your credentials are valid", "tags": [ "Ping" ], "security": [] } }, "/prices": { "get": { "operationId": "list_prices", "summary": "List Prices", "parameters": [ { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field.", "items": { "const": "product", "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricePage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_ListPricesErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all prices", "tags": [ "Prices" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "operationId": "create_price", "summary": "Create Price", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreatePriceErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new price", "tags": [ "Prices" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/public/emails/{username}": { "get": { "operationId": "list_public_emails", "summary": "Search public emails", "parameters": [ { "in": "path", "name": "username", "schema": { "title": "Username", "type": "string" }, "required": true }, { "in": "query", "name": "q", "schema": { "description": "If provided, only return emails matching the given query.", "title": "Q", "type": "string" }, "required": false, "description": "If provided, only return emails matching the given query." }, { "in": "query", "name": "page", "schema": { "default": 1, "description": "The page number to return.", "title": "Page", "type": "integer" }, "required": false, "description": "The page number to return." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEmailPage" } } } }, "404": { "description": "Not Found" } }, "description": "Search and list public emails for a newsletter. No authentication required.", "tags": [ "public" ], "security": [] } }, "/snippets": { "post": { "operationId": "create_snippet", "summary": "Create Snippet", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snippet" } } }, "links": { "retrieve_snippet": { "operationId": "retrieve_snippet", "parameters": { "path.id": "$response.body#/id" } }, "update_snippet": { "operationId": "update_snippet", "parameters": { "path.id": "$response.body#/id" } }, "delete_snippet": { "operationId": "delete_snippet", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new snippet", "tags": [ "Snippets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_snippets", "summary": "List Snippets", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all snippets", "tags": [ "Snippets" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/snippets/{id}": { "get": { "operationId": "retrieve_snippet", "summary": "Retrieve Snippet", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snippet" } } }, "links": { "update_snippet": { "operationId": "update_snippet", "parameters": { "path.id": "$response.body#/id" } }, "delete_snippet": { "operationId": "delete_snippet", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a single snippet.", "tags": [ "Snippets" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_snippet", "summary": "Update Snippet", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snippet" } } }, "links": { "retrieve_snippet": { "operationId": "retrieve_snippet", "parameters": { "path.id": "$response.body#/id" } }, "delete_snippet": { "operationId": "delete_snippet", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a snippet.", "tags": [ "Snippets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnippetUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_snippet", "summary": "Delete Snippet", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a snippet.", "tags": [ "Snippets" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers": { "post": { "operationId": "create_subscriber", "summary": "Create Subscriber", "parameters": [ { "in": "header", "name": "X-Buttondown-Collision-Behavior", "schema": { "default": "no_op", "description": "The behavior to apply when a subscriber with the same email address already exists.\nDefaults to \"no_op\", which will return a 400 error if a subscriber with the same email address already exists. Other values include:\n\n- \"overwrite\", which will overwrite the existing subscriber's data with the new one.\n- \"add\", which will add the new subscriber data to the existing one.\n ", "$ref": "#/components/schemas/CollisionBehavior" }, "required": false, "description": "The behavior to apply when a subscriber with the same email address already exists.\nDefaults to \"no_op\", which will return a 400 error if a subscriber with the same email address already exists. Other values include:\n\n- \"overwrite\", which will overwrite the existing subscriber's data with the new one.\n- \"add\", which will add the new subscriber data to the existing one.\n " }, { "in": "header", "name": "X-Buttondown-Bypass-Firewall", "schema": { "default": false, "description": "Bypass the firewall for this subscriber creation. Subject to aggressive rate limiting (5 per hour per newsletter).", "title": "X-Buttondown-Bypass-Firewall", "type": "boolean" }, "required": false, "description": "Bypass the firewall for this subscriber creation. Subject to aggressive rate limiting (5 per hour per newsletter)." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_ValidationErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new subscriber", "tags": [ "Subscribers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_subscribers", "summary": "List Subscribers", "parameters": [ { "in": "query", "name": "bounce_date__end", "schema": { "description": "If provided, only return subscribers who last bounced on or before the given date.", "title": "Bounce Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who last bounced on or before the given date." }, { "in": "query", "name": "bounce_date__start", "schema": { "description": "If provided, only return subscribers who last bounced on or after the given date.", "title": "Bounce Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who last bounced on or after the given date." }, { "in": "query", "name": "bounce_reason", "schema": { "description": "If provided, only return subscribers with the given bounce reason(s).", "title": "Bounce Reason", "items": { "$ref": "#/components/schemas/SubscriberUndeliverabilityReason" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given bounce reason(s)." }, { "in": "query", "name": "churn_date__end", "schema": { "description": "If provided, only return subscribers who churned on or before the given date.", "title": "Churn Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who churned on or before the given date." }, { "in": "query", "name": "churn_date__start", "schema": { "description": "If provided, only return subscribers who churned on or after the given date.", "title": "Churn Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who churned on or after the given date." }, { "in": "query", "name": "coupon", "schema": { "description": "If provided, only return subscribers with the given coupon ID(s).", "title": "Coupon", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given coupon ID(s)." }, { "in": "query", "name": "current_price", "schema": { "description": "If provided, only return subscribers who are currently subscribed to the given price ID(s).", "title": "Current Price", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers who are currently subscribed to the given price ID(s)." }, { "in": "query", "name": "date__end", "schema": { "description": "If provided, only return subscribers created before the given date.", "title": "Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers created before the given date." }, { "in": "query", "name": "date__start", "schema": { "description": "If provided, only return subscribers created on or after the given date.", "title": "Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers created on or after the given date." }, { "in": "query", "name": "domain", "schema": { "description": "If provided, only return subscribers whose email domain matches the given domain(s).", "example": [ "gmail.com" ], "title": "Domain", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers whose email domain matches the given domain(s).", "example": [ "gmail.com" ] }, { "in": "query", "name": "email_address", "schema": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "description": "If provided, only return subscribers whose email address contains the given string.", "title": "Email Address" }, "required": false, "description": "If provided, only return subscribers whose email address contains the given string." }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field. (Supported: 'stripe_customer', 'stripe_subscription'.)", "items": { "enum": [ "stripe_customer", "stripe_subscription" ], "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field. (Supported: 'stripe_customer', 'stripe_subscription'.)" }, { "in": "query", "name": "form", "schema": { "description": "If provided, only return subscribers that came through the given [form(s)](https://docs.buttondown.com/registration-forms).", "example": [ "form_abc123" ], "title": "Form", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers that came through the given [form(s)](https://docs.buttondown.com/registration-forms).", "example": [ "form_abc123" ] }, { "in": "query", "name": "ids", "schema": { "description": "If provided, only return subscribers with the given IDs.", "title": "Ids", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given IDs." }, { "in": "query", "name": "ip_address", "schema": { "description": "If provided, only return subscribers with the given IP address(es).", "title": "Ip Address", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given IP address(es)." }, { "in": "query", "name": "last_click_date__end", "schema": { "description": "If provided, only return subscribers whose last click was on or before the given date.", "title": "Last Click Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers whose last click was on or before the given date." }, { "in": "query", "name": "last_click_date__start", "schema": { "description": "If provided, only return subscribers whose last click was on or after the given date.", "title": "Last Click Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers whose last click was on or after the given date." }, { "in": "query", "name": "last_open_date__end", "schema": { "description": "If provided, only return subscribers whose last open was on or before the given date.", "title": "Last Open Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers whose last open was on or before the given date." }, { "in": "query", "name": "last_open_date__start", "schema": { "description": "If provided, only return subscribers whose last open was on or after the given date.", "title": "Last Open Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers whose last open was on or after the given date." }, { "in": "query", "name": "-domain", "schema": { "description": "If provided, only return subscribers whose email domain does not match the given domain(s).", "example": [ "gmail.com" ], "title": "-Domain", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers whose email domain does not match the given domain(s).", "example": [ "gmail.com" ] }, { "in": "query", "name": "-tag", "schema": { "description": "If provided, only return subscribers without the given [tag](https://docs.buttondown.com/api-tags-introduction).", "example": "vip", "title": "-Tag", "type": "string" }, "required": false, "description": "If provided, only return subscribers without the given [tag](https://docs.buttondown.com/api-tags-introduction).", "example": "vip" }, { "in": "query", "name": "-type", "schema": { "description": "If provided, only return subscribers without the given type.", "title": "-Type", "items": { "$ref": "#/components/schemas/SubscriberType" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers without the given type." }, { "in": "query", "name": "ordering", "schema": { "default": "-creation_date", "description": "The ordering to apply to the results.", "example": "-creation_date", "title": "Ordering", "type": "string" }, "required": false, "description": "The ordering to apply to the results.", "example": "-creation_date" }, { "in": "query", "name": "price", "schema": { "description": "If provided, only return subscribers who have at one point subscribed to the given price ID(s).", "title": "Price", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers who have at one point subscribed to the given price ID(s)." }, { "in": "query", "name": "referral_code", "schema": { "description": "If provided, only return subscribers with the given referral code(s).", "title": "Referral Code", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given referral code(s)." }, { "in": "query", "name": "referrer_url", "schema": { "description": "If provided, only return subscribers whose referrer URL(s) contain the given string.", "title": "Referrer Url", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers whose referrer URL(s) contain the given string." }, { "in": "query", "name": "open_rate__end", "schema": { "description": "If provided, only return subscribers with an open rate less than or equal to the given value.", "title": "Open Rate End", "type": "number" }, "required": false, "description": "If provided, only return subscribers with an open rate less than or equal to the given value." }, { "in": "query", "name": "open_rate__start", "schema": { "description": "If provided, only return subscribers with an open rate greater than or equal to the given value.", "title": "Open Rate Start", "type": "number" }, "required": false, "description": "If provided, only return subscribers with an open rate greater than or equal to the given value." }, { "in": "query", "name": "click_rate__end", "schema": { "description": "If provided, only return subscribers with a click rate less than or equal to the given value.", "title": "Click Rate End", "type": "number" }, "required": false, "description": "If provided, only return subscribers with a click rate less than or equal to the given value." }, { "in": "query", "name": "click_rate__start", "schema": { "description": "If provided, only return subscribers with a click rate greater than or equal to the given value.", "title": "Click Rate Start", "type": "number" }, "required": false, "description": "If provided, only return subscribers with a click rate greater than or equal to the given value." }, { "in": "query", "name": "risk_score__end", "schema": { "description": "If provided, only return subscribers with a [risk score](https://docs.buttondown.com/firewall) less than or equal to the given value.", "title": "Risk Score End", "type": "number" }, "required": false, "description": "If provided, only return subscribers with a [risk score](https://docs.buttondown.com/firewall) less than or equal to the given value." }, { "in": "query", "name": "risk_score__start", "schema": { "description": "If provided, only return subscribers with a [risk score](https://docs.buttondown.com/firewall) greater than or equal to the given value.", "title": "Risk Score Start", "type": "number" }, "required": false, "description": "If provided, only return subscribers with a [risk score](https://docs.buttondown.com/firewall) greater than or equal to the given value." }, { "in": "query", "name": "source", "schema": { "description": "If provided, only return subscribers with the given source(s).", "example": [ "api" ], "title": "Source", "items": { "$ref": "#/components/schemas/SubscriberSource" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given source(s).", "example": [ "api" ] }, { "in": "query", "name": "subscriber_import", "schema": { "description": "If provided, only return subscribers that were imported by the given subscriber import.", "example": [ "import_abc123" ], "title": "Subscriber Import", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers that were imported by the given subscriber import.", "example": [ "import_abc123" ] }, { "in": "query", "name": "tag", "schema": { "description": "If provided, only return subscribers with the given [tag(s)](https://docs.buttondown.com/api-tags-introduction).", "title": "Tag", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given [tag(s)](https://docs.buttondown.com/api-tags-introduction)." }, { "in": "query", "name": "type", "schema": { "description": "If provided, only return subscribers with the given type.", "title": "Type", "example": [ "regular" ], "items": { "$ref": "#/components/schemas/SubscriberType" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given type.", "example": [ "regular" ] }, { "in": "query", "name": "undeliverability_date__end", "schema": { "description": "If provided, only return subscribers who became undeliverable on or before the given date.", "title": "Undeliverability Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who became undeliverable on or before the given date." }, { "in": "query", "name": "undeliverability_date__start", "schema": { "description": "If provided, only return subscribers who became undeliverable on or after the given date.", "title": "Undeliverability Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who became undeliverable on or after the given date." }, { "in": "query", "name": "undeliverability_reason", "schema": { "description": "If provided, only return subscribers with the given undeliverability reason(s).", "title": "Undeliverability Reason", "items": { "$ref": "#/components/schemas/SubscriberUndeliverabilityReason" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given undeliverability reason(s)." }, { "in": "query", "name": "unsubscription_date__end", "schema": { "description": "If provided, only return subscribers who unsubscribed on or before the given date.", "title": "Unsubscription Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who unsubscribed on or before the given date." }, { "in": "query", "name": "unsubscription_date__start", "schema": { "description": "If provided, only return subscribers who unsubscribed on or after the given date.", "title": "Unsubscription Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who unsubscribed on or after the given date." }, { "in": "query", "name": "unsubscription_reason", "schema": { "description": "If provided, only return subscribers with the given unsubscription reason(s).", "example": [ "no longer interested" ], "title": "Unsubscription Reason", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given unsubscription reason(s).", "example": [ "no longer interested" ] }, { "in": "query", "name": "upgrade_date__end", "schema": { "description": "If provided, only return subscribers who upgraded on or before the given date.", "title": "Upgrade Date End", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who upgraded on or before the given date." }, { "in": "query", "name": "upgrade_date__start", "schema": { "description": "If provided, only return subscribers who upgraded on or after the given date.", "title": "Upgrade Date Start", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "required": false, "description": "If provided, only return subscribers who upgraded on or after the given date." }, { "in": "query", "name": "utm_campaign", "schema": { "description": "If provided, only return subscribers with the given UTM campaign(s).", "example": [ "paid_campaign_2024" ], "title": "Utm Campaign", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given UTM campaign(s).", "example": [ "paid_campaign_2024" ] }, { "in": "query", "name": "utm_medium", "schema": { "description": "If provided, only return subscribers with the given UTM medium(s).", "example": [ "paid_campaign_2024" ], "title": "Utm Medium", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given UTM medium(s).", "example": [ "paid_campaign_2024" ] }, { "in": "query", "name": "utm_source", "schema": { "description": "If provided, only return subscribers with the given UTM source(s).", "example": [ "paid_campaign_2024" ], "title": "Utm Source", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return subscribers with the given UTM source(s).", "example": [ "paid_campaign_2024" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_ListSubscribersErrorCode_" } } } }, "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/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all subscribers", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}": { "get": { "operationId": "retrieve_subscriber", "summary": "Retrieve Subscriber", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true }, { "in": "query", "name": "expand", "schema": { "default": [], "description": "If provided, expand the given field.", "items": { "enum": [ "stripe_customer", "stripe_subscription" ], "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific subscriber by their ID or email address", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_subscriber", "summary": "Delete Subscriber", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_subscriber", "summary": "Update Subscriber", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_UpdateSubscriberErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a subscriber's properties", "tags": [ "Subscribers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/send-reminder": { "post": { "operationId": "send_reminder", "summary": "Send Reminder", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Send a confirmation reminder email to an unactivated subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/send-magic-link": { "post": { "operationId": "send_magic_link_to_subscriber", "summary": "Send Magic Link To Subscriber", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Send a magic link email to a subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/emails/{email_id}": { "post": { "operationId": "send_email_to", "summary": "Send Email To", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true }, { "in": "path", "name": "email_id", "schema": { "title": "Email Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Send a specific email to a specific subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/referrals": { "get": { "operationId": "get_referrals", "summary": "Get Referrals", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List subscribers referred by a specific subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/automations": { "get": { "operationId": "get_automations", "summary": "Get Automations", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationForSubscriberPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List automation attempts for a specific subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/automations/{automation_attempt_id}": { "patch": { "operationId": "update_automation_attempt", "summary": "Update Automation Attempt", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true }, { "in": "path", "name": "automation_attempt_id", "schema": { "title": "Automation Attempt Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationForSubscriber" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_UpdateAutomationAttemptErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update the status of an automation attempt for a subscriber", "tags": [ "Subscribers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationAttemptUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/subscribers/{id_or_email}/stripe-subscriptions": { "get": { "operationId": "get_stripe_subscriptions", "summary": "Get Stripe Subscriptions", "parameters": [ { "in": "path", "name": "id_or_email", "schema": { "title": "Id Or Email", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeSubscriptionPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List Stripe subscriptions for a specific subscriber", "tags": [ "Subscribers" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/survey_responses": { "get": { "operationId": "retrieve_survey_responses", "summary": "Retrieve Survey Responses", "parameters": [ { "in": "query", "name": "email_id", "schema": { "description": "If provided, only return responses submitted from the given email ID(s).", "example": [ "em_01jv2m9q8r7s6t5w4x3y2z1abc" ], "title": "Email Id", "items": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return responses submitted from the given email ID(s).", "example": [ "em_01jv2m9q8r7s6t5w4x3y2z1abc" ] }, { "in": "query", "name": "automation_id", "schema": { "description": "If provided, only return responses submitted from the given automation ID(s).", "example": [ "aut_01jv2m9q8r7s6t5w4x3y2z1abc" ], "title": "Automation Id", "items": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:aut)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return responses submitted from the given automation ID(s).", "example": [ "aut_01jv2m9q8r7s6t5w4x3y2z1abc" ] }, { "in": "query", "name": "subscriber_id", "schema": { "description": "If provided, only return responses made by the given [subscriber(s)](https://docs.buttondown.com/api-subscribers-introduction).", "example": [ "sub_01jv2m9q8r7s6t5w4x3y2z1abc" ], "title": "Subscriber Id", "items": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return responses made by the given [subscriber(s)](https://docs.buttondown.com/api-subscribers-introduction).", "example": [ "sub_01jv2m9q8r7s6t5w4x3y2z1abc" ] }, { "in": "query", "name": "source", "schema": { "description": "If provided, only return responses submitted from the given arbitrary source string(s).", "example": [ "landing-page" ], "title": "Source", "items": { "maxLength": 100, "minLength": 1, "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return responses submitted from the given arbitrary source string(s).", "example": [ "landing-page" ] }, { "in": "query", "name": "survey_id", "schema": { "description": "If provided, only return responses made to the given [survey(s)](https://docs.buttondown.com/api-surveys-introduction).", "example": [ "srv_01jv2m9q8r7s6t5w4x3y2z1abc" ], "title": "Survey Id", "items": { "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:srv)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return responses made to the given [survey(s)](https://docs.buttondown.com/api-surveys-introduction).", "example": [ "srv_01jv2m9q8r7s6t5w4x3y2z1abc" ] }, { "in": "query", "name": "creation_date__start", "schema": { "description": "If provided, only return responses made after the given date.", "title": "Creation Date Start", "format": "date", "type": "string" }, "required": false, "description": "If provided, only return responses made after the given date." }, { "in": "query", "name": "creation_date__end", "schema": { "description": "If provided, only return responses made before the given date.", "title": "Creation Date End", "format": "date", "type": "string" }, "required": false, "description": "If provided, only return responses made before the given date." }, { "in": "query", "name": "expand", "schema": { "description": "If provided, expand the given field.", "items": { "enum": [ "email", "subscriber", "survey", "automation" ], "type": "string" }, "title": "Expand", "type": "array" }, "required": false, "description": "If provided, expand the given field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsePage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all survey responses", "tags": [ "Survey Responses" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "operationId": "create_survey_response", "summary": "Create Survey Response", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } }, "links": { "update_survey_response": { "operationId": "update_survey_response", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreateSurveyResponseErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new survey response", "tags": [ "Survey Responses" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/survey_responses/{id}": { "patch": { "operationId": "update_survey_response", "summary": "Update Survey Response", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } }, "links": {} }, "400": { "description": "Bad Request", "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" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a survey response's text. Only the response owner (subscriber) can update their response.", "tags": [ "Survey Responses" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/surveys": { "post": { "operationId": "create_survey", "summary": "Create Survey", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" } } }, "links": { "retrieve_survey": { "operationId": "retrieve_survey", "parameters": { "path.id": "$response.body#/id" } }, "update_survey": { "operationId": "update_survey", "parameters": { "path.id": "$response.body#/id" } }, "delete_survey": { "operationId": "delete_survey", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_CreateSurveyErrorCode_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new survey", "tags": [ "Surveys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_surveys", "summary": "List Surveys", "parameters": [ { "in": "query", "name": "status", "schema": { "description": "If provided, only return surveys with the given status.", "example": [ "active" ], "items": { "$ref": "#/components/schemas/SurveyStatus" }, "title": "Status", "type": "array" }, "required": false, "description": "If provided, only return surveys with the given status.", "example": [ "active" ] }, { "in": "query", "name": "-status", "schema": { "description": "If provided, only return surveys without the given status.", "example": [ "inactive" ], "items": { "$ref": "#/components/schemas/SurveyStatus" }, "title": "-Status", "type": "array" }, "required": false, "description": "If provided, only return surveys without the given status.", "example": [ "inactive" ] }, { "in": "query", "name": "ordering", "schema": { "allOf": [ { "enum": [ "creation_date", "-creation_date", "question", "-question", "identifier", "-identifier", "status", "-status", "response_count", "-response_count" ], "title": "Ordering", "type": "string" } ], "default": "-creation_date", "description": "The ordering to apply to the results.", "example": "-creation_date" }, "required": false, "description": "The ordering to apply to the results.", "example": "-creation_date" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all surveys", "tags": [ "Surveys" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/surveys/{id}": { "get": { "operationId": "retrieve_survey", "summary": "Retrieve Survey", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" } } }, "links": { "update_survey": { "operationId": "update_survey", "parameters": { "path.id": "$response.body#/id" } }, "delete_survey": { "operationId": "delete_survey", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific survey by its ID", "tags": [ "Surveys" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_survey", "summary": "Update Survey", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" } } }, "links": { "retrieve_survey": { "operationId": "retrieve_survey", "parameters": { "path.id": "$response.body#/id" } }, "delete_survey": { "operationId": "delete_survey", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_UpdateSurveyErrorCode_" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a survey's properties", "tags": [ "Surveys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_survey", "summary": "Delete Survey", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a survey", "tags": [ "Surveys" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/tags": { "post": { "operationId": "create_tag", "summary": "Create Tag", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "links": { "retrieve_tag": { "operationId": "retrieve_tag", "parameters": { "path.id": "$response.body#/id" } }, "update_tag": { "operationId": "update_tag", "parameters": { "path.id": "$response.body#/id" } }, "delete_tag": { "operationId": "delete_tag", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_TagErrorCode_" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "Create a new tag", "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_tags", "summary": "List Tags", "parameters": [ { "in": "query", "name": "ids", "schema": { "description": "If provided, only return tags matching the given IDs.", "example": [ "tag_abc123" ], "title": "Ids", "items": { "type": "string" }, "type": "array" }, "required": false, "description": "If provided, only return tags matching the given IDs.", "example": [ "tag_abc123" ] }, { "in": "query", "name": "page_size", "schema": { "default": 100, "description": "The number of results per page.", "title": "Page Size", "maximum": 1000, "minimum": 1, "type": "integer" }, "required": false, "description": "The number of results per page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagPage" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "List all tags", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/tags/{id}": { "get": { "operationId": "retrieve_tag", "summary": "Retrieve Tag", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "links": { "update_tag": { "operationId": "update_tag", "parameters": { "path.id": "$response.body#/id" } }, "delete_tag": { "operationId": "delete_tag", "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" } } } }, "409": { "description": "Conflict" } }, "description": "Retrieve a specific tag by its ID", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_tag", "summary": "Update Tag", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } }, "links": { "retrieve_tag": { "operationId": "retrieve_tag", "parameters": { "path.id": "$response.body#/id" } }, "delete_tag": { "operationId": "delete_tag", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_TagErrorCode_" } } } }, "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" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "Update a tag's properties", "tags": [ "Tags" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_tag", "summary": "Delete Tag", "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" } } } }, "409": { "description": "Conflict" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorMessage" } } } } }, "description": "Delete a tag", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/tags/{id}/analytics": { "get": { "operationId": "retrieve_tag_analytics", "summary": "Retrieve Tag Analytics", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagAnalytics" } } } }, "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" } } } }, "409": { "description": "Conflict" }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve analytics for a specific tag", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/users": { "post": { "operationId": "create_user", "summary": "Create User", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "links": { "retrieve_user": { "operationId": "retrieve_user", "parameters": { "path.id": "$response.body#/id" } }, "update_user": { "operationId": "update_user", "parameters": { "path.id": "$response.body#/id" } }, "delete_user": { "operationId": "delete_user", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage_Failure_" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Invite a new user to the newsletter", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_users", "summary": "List Users", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all users", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/users/{id}": { "get": { "operationId": "retrieve_user", "summary": "Retrieve User", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "links": { "update_user": { "operationId": "update_user", "parameters": { "path.id": "$response.body#/id" } }, "delete_user": { "operationId": "delete_user", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific user by its ID", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_user", "summary": "Delete User", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a user", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_user", "summary": "Update User", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "links": { "retrieve_user": { "operationId": "retrieve_user", "parameters": { "path.id": "$response.body#/id" } }, "delete_user": { "operationId": "delete_user", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "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" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a user's properties", "tags": [ "Users" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] } }, "/webhooks": { "post": { "operationId": "create_webhook", "summary": "Create Webhook", "parameters": [], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "links": { "retrieve_webhook": { "operationId": "retrieve_webhook", "parameters": { "path.id": "$response.body#/id" } }, "update_webhook": { "operationId": "update_webhook", "parameters": { "path.id": "$response.body#/id" } }, "delete_webhook": { "operationId": "delete_webhook", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Create a new webhook", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "operationId": "list_webhooks", "summary": "List Webhooks", "parameters": [ { "in": "query", "name": "status", "schema": { "description": "If provided, only return webhooks with the given status.", "$ref": "#/components/schemas/WebhookStatus" }, "required": false, "description": "If provided, only return webhooks with the given status." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "List all webhooks", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/webhooks/{id}": { "get": { "operationId": "retrieve_webhook", "summary": "Retrieve Webhook", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "links": { "update_webhook": { "operationId": "update_webhook", "parameters": { "path.id": "$response.body#/id" } }, "delete_webhook": { "operationId": "delete_webhook", "parameters": { "path.id": "$response.body#/id" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve a specific webhook by its ID", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "operationId": "update_webhook", "summary": "Update Webhook", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "links": { "retrieve_webhook": { "operationId": "retrieve_webhook", "parameters": { "path.id": "$response.body#/id" } }, "delete_webhook": { "operationId": "delete_webhook", "parameters": { "path.id": "$response.body#/id" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Update a webhook's properties", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "operationId": "delete_webhook", "summary": "Delete Webhook", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Delete a webhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/webhooks/{id}/attempts": { "get": { "operationId": "retrieve_webhook_attempts", "summary": "Retrieve Webhook Attempts", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "query", "name": "status", "schema": { "description": "If provided, only return webhook attempts with the given status.", "$ref": "#/components/schemas/WebhookAttemptStatus" }, "required": false, "description": "If provided, only return webhook attempts with the given status." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAttemptOutputPage" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Retrieve webhook attempts for a specific webhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/webhooks/{id}/test": { "post": { "operationId": "test_webhook", "summary": "Test Webhook", "parameters": [ { "in": "path", "name": "id", "schema": { "title": "Id", "type": "string" }, "required": true }, { "in": "query", "name": "event_type", "schema": { "description": "The event type to send. Defaults to the webhook's first configured event type.", "$ref": "#/components/schemas/ExternalEventType" }, "required": false, "description": "The event type to send. Defaults to the webhook's first configured event type." } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "409": { "description": "Conflict" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "description": "Send a test event to a webhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "Account": { "properties": { "username": { "description": "The username associated with the account.", "title": "Username", "type": "string" }, "email_address": { "description": "The email address associated with the account.", "title": "Email Address", "type": "string" } }, "required": [ "username", "email_address" ], "title": "Account", "type": "object" }, "AdvertisingSlot": { "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" }, "date": { "description": "The date this advertising slot is scheduled for.", "format": "date", "title": "Date", "type": "string" }, "status": { "$ref": "#/components/schemas/AdvertisingSlotStatus", "description": "The current status of the advertising slot." }, "invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to the Stripe invoice PDF for this slot, if available.", "title": "Invoice Url" }, "sku_id": { "description": "The ID of the advertising unit this slot belongs to.", "title": "Sku Id", "type": "string" }, "submission_url": { "description": "URL where the sponsor can submit their ad content.", "title": "Submission Url", "type": "string" }, "sponsor_company": { "description": "The name of the sponsoring company.", "title": "Sponsor Company", "type": "string" }, "sponsor_email": { "description": "The email address of the sponsor contact.", "title": "Sponsor Email", "type": "string" }, "sponsor_name": { "description": "The name of the sponsor contact.", "title": "Sponsor Name", "type": "string" }, "content": { "description": "The ad content text.", "title": "Content", "type": "string" }, "content_image_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the image attached to this ad, if any.", "title": "Content Image Id" }, "content_url": { "description": "The URL the ad links to.", "title": "Content Url", "type": "string" }, "content_approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the ad content was approved, if applicable.", "title": "Content Approved At" }, "content_rejected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the ad content was rejected, if applicable.", "title": "Content Rejected At" }, "content_rejection_reason": { "description": "The reason the ad content was rejected, if applicable.", "title": "Content Rejection Reason", "type": "string" }, "content_submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the ad content was submitted for review.", "title": "Content Submitted At" }, "inquiry_message": { "description": "Optional message from the sponsor inquiry.", "title": "Inquiry Message", "type": "string" } }, "required": [ "id", "creation_date", "date", "status", "sku_id", "submission_url", "sponsor_company", "sponsor_email", "sponsor_name", "content", "content_url", "content_rejection_reason", "inquiry_message" ], "title": "AdvertisingSlot", "type": "object" }, "AdvertisingUnit": { "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" }, "status": { "$ref": "#/components/schemas/AdvertisingSKUStatus", "description": "The current status of the advertising unit." }, "slots": { "description": "The list of advertising slots for this unit.", "items": { "$ref": "#/components/schemas/AdvertisingSlot" }, "title": "Slots", "type": "array" }, "title": { "description": "The title of the advertising unit.", "title": "Title", "type": "string" }, "description": { "description": "A description of the advertising unit.", "title": "Description", "type": "string" }, "behavior": { "description": "The behavior type of the advertising unit.", "title": "Behavior", "type": "string" }, "url": { "description": "The URL for the advertising unit's landing page.", "title": "Url", "type": "string" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The price in the smallest currency unit, or null if not set.", "title": "Price" }, "allows_html": { "description": "Whether the advertising unit accepts HTML content.", "title": "Allows Html", "type": "boolean" }, "allows_image": { "description": "Whether the advertising unit accepts an image.", "title": "Allows Image", "type": "boolean" }, "max_characters": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of characters allowed for the ad content.", "title": "Max Characters" }, "submission_deadline_days": { "description": "Number of days before the slot date that content must be submitted.", "title": "Submission Deadline Days", "type": "integer" } }, "required": [ "id", "creation_date", "status", "slots", "title", "description", "behavior", "url", "allows_html", "allows_image", "submission_deadline_days" ], "title": "AdvertisingUnit", "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" }, "AdvertisingUnitInput": { "properties": { "title": { "description": "The title of the advertising unit.", "maxLength": 100, "title": "Title", "type": "string" }, "description": { "default": "", "description": "A description of the advertising unit.", "title": "Description", "type": "string" }, "behavior": { "default": "", "description": "The behavior type of the advertising unit.", "title": "Behavior", "type": "string" }, "url": { "default": "", "description": "The URL for the advertising unit's landing page.", "title": "Url", "type": "string" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The price in the smallest currency unit.", "title": "Price" }, "allows_html": { "default": false, "description": "Whether the advertising unit accepts HTML content.", "title": "Allows Html", "type": "boolean" }, "allows_image": { "default": false, "description": "Whether the advertising unit accepts an image.", "title": "Allows Image", "type": "boolean" }, "max_characters": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of characters allowed for the ad content.", "title": "Max Characters" }, "submission_deadline_days": { "default": 3, "description": "Number of days before the slot date that content must be submitted.", "title": "Submission Deadline Days", "type": "integer" } }, "required": [ "title" ], "title": "AdvertisingUnitInput", "type": "object" }, "AdvertisingUnitUpdateInput": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The title of the advertising unit.", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A description of the advertising unit.", "title": "Description" }, "dates": { "description": "The dates for this advertising unit's slots.", "items": { "type": "string" }, "title": "Dates", "type": "array" }, "behavior": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The behavior type of the advertising unit.", "title": "Behavior" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL for the advertising unit's landing page.", "title": "Url" }, "price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The price in the smallest currency unit.", "title": "Price" }, "allows_html": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the advertising unit accepts HTML content.", "title": "Allows Html" }, "allows_image": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the advertising unit accepts an image.", "title": "Allows Image" }, "max_characters": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of characters allowed for the ad content.", "title": "Max Characters" }, "submission_deadline_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of days before the slot date that content must be submitted.", "title": "Submission Deadline Days" } }, "required": [ "dates" ], "title": "AdvertisingUnitUpdateInput", "type": "object" }, "AdvertisingSlotUpdateInput": { "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ad content text.", "title": "Content" }, "content_approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the ad content was approved.", "title": "Content Approved At" }, "content_image_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the image attached to this ad.", "title": "Content Image Id" }, "content_rejection_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The reason the ad content was rejected.", "title": "Content Rejection Reason" }, "content_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL the ad links to.", "title": "Content Url" }, "sponsor_company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the sponsoring company.", "title": "Sponsor Company" }, "sponsor_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email address of the sponsor contact.", "title": "Sponsor Email" }, "sponsor_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the sponsor contact.", "title": "Sponsor Name" }, "status": { "anyOf": [ { "enum": [ "approve", "hold_accept", "hold_decline", "reject" ], "type": "string" }, { "type": "null" } ], "description": "Set to 'approve', 'reject', 'hold_accept', or 'hold_decline' to update the slot status.", "title": "Status" } }, "title": "AdvertisingSlotUpdateInput", "type": "object" }, "APIRequestDetail": { "description": "Represents a request to the API (api.buttondown.com).", "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" }, "status_code": { "description": "The HTTP status code the API returned.", "title": "Status Code", "type": "integer" }, "path": { "description": "The request path (e.g. `/v1/subscribers`).", "title": "Path", "type": "string" }, "method": { "description": "The HTTP method used (e.g. `GET`, `POST`).", "title": "Method", "type": "string" }, "source": { "$ref": "#/components/schemas/APIRequestSource", "description": "Where the request originated (e.g. `api`, `dashboard`)." }, "version": { "description": "The API version the request was made against.", "enum": [ "2024-07-01", "2024-08-01", "2024-08-15", "2024-09-30", "2024-12-30", "2025-01-02", "2025-05-19", "2025-06-01", "2026-01-01", "2026-04-01" ], "title": "Version", "type": "string" }, "ip_address": { "description": "The IP address the request was made from.", "title": "Ip Address", "type": "string" }, "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the API key used, if authenticated via API key.", "title": "Api Key Id" }, "api_key_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The human-readable label of the API key used, if any.", "title": "Api Key Label" }, "request_data": { "description": "The raw request body, JSON-encoded as a string.", "title": "Request Data", "type": "string" }, "response_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The raw response body, JSON-encoded as a string, if retained.", "title": "Response Data" }, "headers": { "additionalProperties": { "type": "string" }, "description": "The request headers. UUIDs within header values are redacted.", "title": "Headers", "type": "object" } }, "required": [ "id", "creation_date", "status_code", "path", "method", "source", "version", "ip_address", "request_data", "headers" ], "title": "APIRequestDetail", "type": "object" }, "APIRequest": { "description": "Represents a request to the API (api.buttondown.com).", "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" }, "status_code": { "description": "The HTTP status code the API returned.", "title": "Status Code", "type": "integer" }, "path": { "description": "The request path (e.g. `/v1/subscribers`).", "title": "Path", "type": "string" }, "method": { "description": "The HTTP method used (e.g. `GET`, `POST`).", "title": "Method", "type": "string" }, "source": { "$ref": "#/components/schemas/APIRequestSource", "description": "Where the request originated (e.g. `api`, `dashboard`)." }, "version": { "description": "The API version the request was made against.", "enum": [ "2024-07-01", "2024-08-01", "2024-08-15", "2024-09-30", "2024-12-30", "2025-01-02", "2025-05-19", "2025-06-01", "2026-01-01", "2026-04-01" ], "title": "Version", "type": "string" }, "ip_address": { "description": "The IP address the request was made from.", "title": "Ip Address", "type": "string" }, "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the API key used, if authenticated via API key.", "title": "Api Key Id" }, "api_key_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The human-readable label of the API key used, if any.", "title": "Api Key Label" } }, "required": [ "id", "creation_date", "status_code", "path", "method", "source", "version", "ip_address" ], "title": "APIRequest", "type": "object" }, "APIRequestList": { "properties": { "results": { "description": "The list of API requests on this page.", "items": { "$ref": "#/components/schemas/APIRequest" }, "title": "Results", "type": "array" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An opaque cursor to pass back to fetch the next page, or null if this is the last page.", "title": "Cursor" } }, "required": [ "results" ], "title": "APIRequestList", "type": "object" }, "Attachment": { "description": "Attachments are files that can be included with your emails. Buttondown allows\nyou to upload attachments to its secure S3 bucket and attach them to your emails.\nSupported file types include documents, images, audio files, and more.", "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": "The name of the attachment.", "example": "newsletter-guide.pdf", "maxLength": 255, "title": "Name", "type": "string" }, "file": { "description": "The URL of the attachment file.", "example": "https://buttondown.s3.amazonaws.com/attachments/newsletter-guide.pdf", "title": "File", "type": "string" }, "size": { "description": "The size of the attachment in bytes.", "example": 1000, "minimum": 0, "title": "Size", "type": "integer" } }, "required": [ "id", "creation_date", "name", "file", "size" ], "title": "Attachment", "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" }, "Action": { "description": "An action to perform when the automation's trigger fires.", "properties": { "type": { "$ref": "#/components/schemas/AutomationActionType", "description": "The type of action to perform." }, "metadata": { "additionalProperties": true, "description": "Configuration specific to the action type.", "title": "Metadata", "type": "object" }, "timing": { "anyOf": [ { "$ref": "#/components/schemas/Timing" }, { "type": "null" } ], "description": "When to execute this action. Defaults to immediate if not specified." } }, "required": [ "type", "metadata" ], "title": "Action", "type": "object" }, "Automation": { "description": "A rule that automatically performs actions in response to events.", "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": "The name of the automation.", "title": "Name", "type": "string" }, "status": { "$ref": "#/components/schemas/AutomationStatus", "description": "Whether the automation is enabled or disabled." }, "trigger": { "$ref": "#/components/schemas/ExternalEventType", "description": "The event that causes this automation to run." }, "actions": { "description": "The actions to perform when the trigger fires.", "items": { "$ref": "#/components/schemas/Action" }, "title": "Actions", "type": "array" }, "filters": { "$ref": "#/components/schemas/FilterGroup", "description": "Conditions that must be met for the automation to run." }, "metadata": { "additionalProperties": true, "description": "Additional metadata for the automation.", "title": "Metadata", "type": "object" }, "should_evaluate_filter_after_delay": { "description": "If true, filters are re-evaluated after the delay has passed.", "title": "Should Evaluate Filter After Delay", "type": "boolean" } }, "required": [ "id", "creation_date", "name", "status", "trigger", "actions", "filters", "metadata", "should_evaluate_filter_after_delay" ], "title": "Automation", "type": "object" }, "Delay": { "description": "Configuration for how long to wait before executing the automation's action.", "properties": { "value": { "description": "The number of time units to delay.", "title": "Value", "type": "string" }, "unit": { "description": "The unit of time for the delay.", "enum": [ "minutes", "hours", "days", "weeks" ], "title": "Unit", "type": "string" }, "time_of_day": { "anyOf": [ { "enum": [ "morning", "evening", "" ], "type": "string" }, { "type": "null" } ], "description": "If set, the action will be executed at this time of day after the delay has passed.", "title": "Time Of Day" } }, "required": [ "value", "unit" ], "title": "Delay", "type": "object" }, "Filter": { "description": "A filter is a single condition that can be evaluated against a [Subscriber](/api-subscribers-retrieve). It has a field, an operator, and a value:\n\n```json\n{\n \"field\": \"subscriber.tags\",\n \"operator\": \"contains\",\n \"value\": \"executive\"\n}\n```\n\nThe field is the path to the field on the subscriber to evaluate. The operator is the operator to use when evaluating the filter. The value is the value to compare the field to.", "properties": { "field": { "title": "Field", "type": "string" }, "operator": { "$ref": "#/components/schemas/Operator" }, "value": { "title": "Value", "type": "string" } }, "required": [ "field", "operator", "value" ], "title": "Filter", "type": "object" }, "FilterGroup": { "description": "Buttondown's filtering schema can be used for multiple things:\n\n- Filtering [the audience of an email](/api-emails-create) to a specific subset\n- Creating [finely-tuned automations](/api-automation-introduction)\n\nFilters are fractal; they can be nested in groups, and groups can be nested in other groups. This is accomplished through a tree-like structure. Every \"FilterGroup\" has a \"predicate\" field, which is either \"and\" or \"or\", which determines how the filters and groups within the group are combined, a \"groups\" field, which is a list of \"FilterGroup\" objects (that's that recursive bit!), and a \"filters\" field, which are the leaf-level filters themselves.\n\nLet's say you want a simple filter: all subscribers who have a tag called \"executive\". You can do that like this:\n\n```json\n{\n \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"executive\"}],\n \"groups\": [],\n \"predicate\": \"and\"\n}\n```\n\nNow, let's say you want to filter for subscribers who have a tag called \"executive\" and a tag called \"general-electric\". You can do that like this:\n\n```json\n{\n \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"executive\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"general-electric\"}],\n \"groups\": [],\n \"predicate\": \"and\"\n}\n```\n\nIf you wanted to change that `and` to an `or`, you can do that like this:\n\n```json\n{\n \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"executive\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"general-electric\"}],\n \"groups\": [],\n \"predicate\": \"or\"\n}\n```\n\nNow, let's say you want to filter for subscribers who have a tag called \"executive\" _or_ a tag called \"general-electric\" and a tag called \"admin\". This is where the whole nested thing comes in handy. You can do that like this:\n\n```json\n{\n \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"executive\"}],\n \"groups\": [\n {\n \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"admin\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"general-electric\"}],\n \"groups\": [],\n \"predicate\": \"and\"\n }\n ],\n \"predicate\": \"or\"\n}\n```\n\nYou can read more about the specific filter construction in the [Filter documentation](/api-emails-filter).", "properties": { "filters": { "description": "The leaf-level filters to apply to the audience.", "items": { "$ref": "#/components/schemas/Filter" }, "title": "Filters", "type": "array" }, "groups": { "description": "The nested groups to apply to the audience.", "items": { "$ref": "#/components/schemas/FilterGroup" }, "title": "Groups", "type": "array" }, "predicate": { "description": "The logical operator to use when combining filters (either 'and' or 'or').", "enum": [ "and", "or" ], "title": "Predicate", "type": "string" } }, "required": [ "filters", "groups", "predicate" ], "title": "FilterGroup", "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." }, "Timing": { "description": "Controls when an automation's action executes after the trigger fires.", "properties": { "time": { "description": "Whether the action should execute immediately or after a delay.", "enum": [ "immediate", "delay" ], "title": "Time", "type": "string" }, "delay": { "anyOf": [ { "$ref": "#/components/schemas/Delay" }, { "type": "null" } ], "description": "The delay configuration. Required when `time` is `delay`; null when `time` is `immediate`." } }, "required": [ "time" ], "title": "Timing", "type": "object" }, "AutomationCreationErrorCode": { "description": "Represents the type of error that occurred when creating an automation.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "delay_invalid", "filter_invalid__tag", "filter_invalid", "action_invalid", "filter_invalid__field", "invalid_newsletter_id", "trigger_action_invalid", "action_invalid__missing_body_or_subject" ], "title": "AutomationCreationErrorCode", "type": "string" }, "ErrorMessage_AutomationCreationErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/AutomationCreationErrorCode" } ], "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[AutomationCreationErrorCode]", "type": "object" }, "ActionInput": { "additionalProperties": false, "description": "Request payload for an action to perform when the automation's trigger fires.", "properties": { "type": { "$ref": "#/components/schemas/AutomationActionType", "description": "The type of action to perform." }, "metadata": { "additionalProperties": true, "description": "Configuration specific to the action type.", "maxProperties": 100, "title": "Metadata", "type": "object" }, "timing": { "anyOf": [ { "$ref": "#/components/schemas/TimingInput" }, { "type": "null" } ], "description": "When to execute this action. Defaults to immediate if not specified." } }, "required": [ "type" ], "title": "ActionInput", "type": "object" }, "AutomationInput": { "additionalProperties": false, "properties": { "name": { "description": "The name of the automation.", "maxLength": 100, "minLength": 1, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "title": "Name", "type": "string" }, "trigger": { "$ref": "#/components/schemas/ExternalEventType", "description": "The event that causes this automation to run." }, "actions": { "description": "The actions to perform when the trigger fires.", "items": { "$ref": "#/components/schemas/ActionInput" }, "maxItems": 25, "title": "Actions", "type": "array" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/FilterGroup" }, { "type": "null" } ], "description": "Conditions that must be met for the automation to run. Omit or pass null for no filter." }, "metadata": { "additionalProperties": true, "description": "Additional metadata for the automation.", "maxProperties": 100, "propertyNames": { "maxLength": 100 }, "title": "Metadata", "type": "object" }, "should_evaluate_filter_after_delay": { "default": false, "description": "If true, filters are re-evaluated after the delay has passed.", "title": "Should Evaluate Filter After Delay", "type": "boolean" } }, "required": [ "name", "trigger", "actions" ], "title": "AutomationInput", "type": "object" }, "DelayInput": { "additionalProperties": false, "description": "Request payload configuration for delaying an automation action.", "properties": { "value": { "description": "The number of time units to delay.", "maxLength": 16, "minLength": 1, "title": "Value", "type": "string" }, "unit": { "description": "The unit of time for the delay.", "enum": [ "minutes", "hours", "days", "weeks" ], "title": "Unit", "type": "string" }, "time_of_day": { "anyOf": [ { "enum": [ "morning", "evening", "" ], "type": "string" }, { "type": "null" } ], "description": "If set, the action will be executed at this time of day after the delay has passed.", "title": "Time Of Day" } }, "required": [ "value", "unit" ], "title": "DelayInput", "type": "object" }, "TimingInput": { "additionalProperties": false, "description": "Request payload controls for when an automation action executes.", "properties": { "time": { "description": "Whether the action should execute immediately or after a delay.", "enum": [ "immediate", "delay" ], "title": "Time", "type": "string" }, "delay": { "anyOf": [ { "$ref": "#/components/schemas/DelayInput" }, { "type": "null" } ], "description": "The delay configuration. Required when `time` is `delay`; null when `time` is `immediate`." } }, "required": [ "time" ], "title": "TimingInput", "type": "object" }, "AutomationUpdateInput": { "additionalProperties": false, "properties": { "name": { "anyOf": [ { "maxLength": 100, "minLength": 1, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "type": "string" }, { "type": "null" } ], "description": "The name of the automation.", "title": "Name" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AutomationStatus" }, { "type": "null" } ], "description": "Whether the automation is enabled or disabled." }, "trigger": { "anyOf": [ { "$ref": "#/components/schemas/ExternalEventType" }, { "type": "null" } ], "description": "The event that causes this automation to run." }, "timing": { "anyOf": [ { "$ref": "#/components/schemas/TimingInput" }, { "type": "null" } ], "description": "When to execute the automation's actions." }, "actions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ActionInput" }, "maxItems": 25, "type": "array" }, { "type": "null" } ], "description": "The actions to perform when the trigger fires.", "title": "Actions" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/FilterGroup" }, { "type": "null" } ], "description": "Conditions that must be met for the automation to run." }, "metadata": { "anyOf": [ { "additionalProperties": true, "maxProperties": 100, "propertyNames": { "maxLength": 100 }, "type": "object" }, { "type": "null" } ], "description": "Additional metadata for the automation.", "title": "Metadata" }, "should_evaluate_filter_after_delay": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "If true, filters are re-evaluated after the delay has passed.", "title": "Should Evaluate Filter After Delay" } }, "title": "AutomationUpdateInput", "type": "object" }, "Analytics": { "properties": { "recipients": { "default": 0, "description": "The number of subscribers the email was dispatched to.", "title": "Recipients", "type": "integer" }, "deliveries": { "default": 0, "description": "The number of successful deliveries (recipients minus failures).", "title": "Deliveries", "type": "integer" }, "opens": { "default": 0, "description": "The number of unique opens recorded.", "title": "Opens", "type": "integer" }, "clicks": { "default": 0, "description": "The number of unique link clicks recorded.", "title": "Clicks", "type": "integer" }, "temporary_failures": { "default": 0, "description": "The number of temporary delivery failures (e.g. soft bounces).", "title": "Temporary Failures", "type": "integer" }, "permanent_failures": { "default": 0, "description": "The number of permanent delivery failures (e.g. hard bounces).", "title": "Permanent Failures", "type": "integer" }, "unsubscriptions": { "default": 0, "description": "The number of subscribers who unsubscribed after receiving this email.", "title": "Unsubscriptions", "type": "integer" }, "complaints": { "default": 0, "description": "The number of spam complaints recorded against this email.", "title": "Complaints", "type": "integer" }, "survey_responses": { "default": 0, "description": "The number of survey responses submitted from this email.", "title": "Survey Responses", "type": "integer" }, "webmentions": { "default": 0, "description": "The number of inbound webmentions received for this email.", "title": "Webmentions", "type": "integer" }, "page_views_lifetime": { "default": 0, "description": "The total number of archive page views for this email since publication.", "title": "Page Views Lifetime", "type": "integer" }, "page_views_30": { "default": 0, "description": "The number of archive page views in the last 30 days.", "title": "Page Views 30", "type": "integer" }, "page_views_7": { "default": 0, "description": "The number of archive page views in the last 7 days.", "title": "Page Views 7", "type": "integer" }, "subscriptions": { "default": 0, "description": "The number of new subscribers attributed to this email.", "title": "Subscriptions", "type": "integer" }, "paid_subscriptions": { "default": 0, "description": "The number of new paid subscribers attributed to this email.", "title": "Paid Subscriptions", "type": "integer" }, "replies": { "default": 0, "description": "The number of reply emails received from subscribers.", "title": "Replies", "type": "integer" }, "comments": { "default": 0, "description": "The number of comments posted on this email.", "title": "Comments", "type": "integer" }, "social_mentions": { "default": 0, "description": "The number of social media mentions of this email.", "title": "Social Mentions", "type": "integer" }, "temporary_failure_breakdown": { "description": "Breakdown of temporary failures by reason code, sorted by count descending.", "items": { "$ref": "#/components/schemas/FailureBreakdownItem" }, "title": "Temporary Failure Breakdown", "type": "array" }, "permanent_failure_breakdown": { "description": "Breakdown of permanent failures by reason code, sorted by count descending.", "items": { "$ref": "#/components/schemas/FailureBreakdownItem" }, "title": "Permanent Failure Breakdown", "type": "array" } }, "title": "Analytics", "type": "object" }, "FailureBreakdownItem": { "description": "A single failure reason with its count.", "properties": { "code": { "description": "The failure reason code (e.g. 'hard_bounce', 'spam')", "title": "Code", "type": "string" }, "count": { "description": "Number of failures with this reason", "title": "Count", "type": "integer" } }, "required": [ "code", "count" ], "title": "FailureBreakdownItem", "type": "object" }, "Book": { "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" }, "title": { "description": "The title of the book.", "maxLength": 500, "title": "Title", "type": "string" }, "url": { "default": "", "description": "The URL where the book can be purchased or viewed.", "maxLength": 2000, "title": "Url", "type": "string" }, "image_url": { "default": "", "description": "The URL of the book's cover image.", "maxLength": 2000, "title": "Image Url", "type": "string" }, "description": { "default": "", "description": "A description of the book.", "title": "Description", "type": "string" }, "year": { "anyOf": [ { "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, { "type": "null" } ], "description": "The year the book was published.", "title": "Year" }, "isbn": { "default": "", "description": "The ISBN of the book.", "maxLength": 20, "title": "Isbn", "type": "string" }, "shared": { "default": true, "description": "Whether the book is displayed publicly on the archive.", "title": "Shared", "type": "boolean" } }, "required": [ "id", "creation_date", "title" ], "title": "Book", "type": "object" }, "BookInput": { "additionalProperties": false, "properties": { "title": { "description": "The title of the book.", "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "url": { "default": "", "description": "The URL where the book can be purchased or viewed.", "maxLength": 2000, "title": "Url", "type": "string" }, "image_url": { "default": "", "description": "The URL of the book's cover image.", "maxLength": 2000, "title": "Image Url", "type": "string" }, "description": { "default": "", "description": "A description of the book.", "title": "Description", "type": "string" }, "year": { "anyOf": [ { "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, { "type": "null" } ], "description": "The year the book was published.", "title": "Year" }, "isbn": { "default": "", "description": "The ISBN of the book.", "maxLength": 20, "title": "Isbn", "type": "string" }, "shared": { "default": true, "description": "Whether the book is displayed publicly on the archive.", "title": "Shared", "type": "boolean" } }, "required": [ "title" ], "title": "BookInput", "type": "object" }, "BookUpdateInput": { "additionalProperties": false, "properties": { "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "The title of the book.", "title": "Title" }, "url": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The URL where the book can be purchased or viewed.", "title": "Url" }, "image_url": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The URL of the book's cover image.", "title": "Image Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A description of the book.", "title": "Description" }, "year": { "anyOf": [ { "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, { "type": "null" } ], "description": "The year the book was published.", "title": "Year" }, "isbn": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "description": "The ISBN of the book.", "title": "Isbn" }, "shared": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the book is displayed publicly on the archive.", "title": "Shared" } }, "title": "BookUpdateInput", "type": "object" }, "BulkAction": { "description": "A bulk action represents, well, a bulk action. It is used to perform\nactions on a large number of objects at once. For example, you can\nuse it to delete a large number of emails, or to unsubscribe a large\nnumber of subscribers. The actions within a bulk action are processed\nserially by Buttondown; this should be considered an ergonomic way to\nbatch API calls across the network rather than a net-new piece of functionality\nin of itself.", "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" }, "type": { "$ref": "#/components/schemas/BulkActionType", "description": "The type of bulk action to perform.", "example": "delete_emails" }, "metadata": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": true, "type": "object" } ] }, "description": "Parameters for the bulk action. The exact shape depends on `type` \u2014 typically an `ids` list of object IDs to act on.", "example": { "ids": [ "611c8825-6f21-4544-bb47-9f50453e9cb0", "418c701a-efe3-4e3d-a404-e635a2f28775" ] }, "minProperties": 1, "title": "Metadata", "type": "object" }, "status": { "$ref": "#/components/schemas/BulkActionStatus", "description": "The current processing status of the bulk action." }, "completion_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time at which the bulk action was completed.", "title": "Completion Date" } }, "required": [ "id", "creation_date", "type", "metadata", "status" ], "title": "BulkAction", "type": "object" }, "BulkActionInput": { "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/BulkActionType", "description": "The type of bulk action to perform.", "example": "delete_emails" }, "metadata": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": true, "type": "object" } ] }, "description": "Parameters for the bulk action. The exact shape depends on `type` \u2014 typically an `ids` list of object IDs to act on.", "example": { "ids": [ "611c8825-6f21-4544-bb47-9f50453e9cb0", "418c701a-efe3-4e3d-a404-e635a2f28775" ] }, "minProperties": 1, "title": "Metadata", "type": "object" } }, "required": [ "type", "metadata" ], "title": "BulkActionInput", "type": "object" }, "ArchivalMode": { "description": "Governs who can view this email in the archive.", "enum": [ "disabled", "enabled", "enabled_for_paid_subscribers", "enabled_for_subscribers" ], "title": "ArchivalMode", "type": "string" }, "Callout": { "description": "Surfacing-time flags about an email that the UI uses to render contextual\ncallouts (e.g. in the analytics panel). Computed on read; not persisted.", "enum": [ "first_send_on_sending_domain" ], "title": "Callout", "type": "string" }, "Comment": { "description": "Comments are a way for subscribers to interact with newsletters. They're a way to\nprovide feedback, ask questions, and generally engage with the content of an email.\nComments exist in a tree structure; comments that reply to other comments are\nconsidered \"children\" of the parent comment.", "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" }, "email_id": { "description": "The ID of the email this comment is attached to.", "title": "Email Id", "type": "string" }, "subscriber_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the subscriber who posted the comment, or null if posted by the newsletter author.", "title": "Subscriber Id" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the parent comment, if this comment is a reply to another comment.", "title": "Parent Id" }, "text": { "description": "The text content of the comment.", "title": "Text", "type": "string" }, "status": { "$ref": "#/components/schemas/CommentStatus", "description": "The moderation status of the comment (e.g. `active`, `spammy`)." }, "subscriber": { "anyOf": [ { "$ref": "#/components/schemas/Subscriber" }, { "type": "null" } ] }, "email": { "anyOf": [ { "$ref": "#/components/schemas/Email" }, { "type": "null" } ] } }, "required": [ "id", "creation_date", "email_id", "text", "status" ], "title": "Comment", "type": "object" }, "Email": { "description": "Emails are why you're here on Buttondown, right?\nCreating an email via the API is just like creating one in the interface;\nit will instantly trigger sending actual emails,\nbased on the tags and email type you provide.\n\nRelevant changes to the schema:\n\n- [2024-08-15](https://docs.buttondown.com/api-changelog-2024-08-15): unshipped the `included_tags` and `excluded_tags` fields.\n- [2024-12-30](https://docs.buttondown.com/api-changelog-2024-12-30): unshipped the `is_comments_disabled` field, and replaced it with a more flexible `commenting_mode` field.\n- [2025-09-23](https://docs.buttondown.com/api-changelog-2025-09-23): increased the maximum length of the `subject` field from 1000 to 2000 characters.", "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" }, "absolute_url": { "description": "The canonical web URL of the email on the newsletter's archive.", "title": "Absolute Url", "type": "string" }, "analytics": { "anyOf": [ { "$ref": "#/components/schemas/Analytics" }, { "type": "null" } ], "description": "Aggregate analytics for the email. Null until the email has been sent." }, "callouts": { "description": "A list of callouts that apply to this email \u2014 surfaced in the UI alongside analytics to flag context the reader should know about (e.g., first send on a custom sending domain).", "items": { "$ref": "#/components/schemas/Callout" }, "title": "Callouts", "type": "array" }, "attachments": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "A list of attachment IDs present on the email. (See [Attachments](https://docs.buttondown.com/api-attachments-introduction) for more information.)", "title": "Attachments" }, "body": { "description": "The body of the email, in either HTML or markdown format. Buttondown attempts to intelligently detect the format of the body automatically, but you can also specify the format explicitly by prepending the text with the `buttondown-editor-mode` comment: `` or ``.", "title": "Body", "type": "string" }, "canonical_url": { "description": "The URL of the original source of the content.", "title": "Canonical Url", "type": "string" }, "commenting_mode": { "$ref": "#/components/schemas/EmailCommentingMode", "description": "Controls whether subscribers can comment on this email." }, "description": { "description": "A human-readable description of the email, used for archives and SEO.", "title": "Description", "type": "string" }, "archival_mode": { "$ref": "#/components/schemas/ArchivalMode", "description": "Controls who can view this email in the archive." }, "email_type": { "allOf": [ { "$ref": "#/components/schemas/EmailType" } ], "default": "public", "deprecated": true, "description": "The type of email. Defaults to `PUBLIC`." }, "featured": { "description": "Designated whether or not this email should be highlighted within the archives.", "title": "Featured", "type": "boolean" }, "filters": { "$ref": "#/components/schemas/FilterGroup", "description": "Tag-based filter rules determining which subscribers receive this email." }, "image": { "description": "A primary image URL used when previewing the email on the web or in other contexts.", "title": "Image", "type": "string" }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" }, "modification_date": { "description": "The date and time at which the object was last modified.", "format": "date-time", "title": "Modification Date", "type": "string" }, "publish_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time at which the email should be published in the future (for scheduled emails), or the date and time at which the email was published (for sent emails).", "title": "Publish Date" }, "related_email_ids": { "description": "A list of email IDs that are related to this email. Related emails are shown at the bottom of the email and archive pages.", "items": { "type": "string" }, "title": "Related Email Ids", "type": "array" }, "secondary_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "An informal 'number' for the email, used in some templates ('This was issue #123').", "title": "Secondary Id" }, "should_trigger_pay_per_email_billing": { "description": "Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate between free updates and premium newsletters.", "title": "Should Trigger Pay Per Email Billing", "type": "boolean" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A short, human-readable identifier for the email, used in the archive URL.", "example": "welcome-to-the-newsletter", "title": "Slug" }, "source": { "$ref": "#/components/schemas/EmailSource", "description": "The source of the email.", "example": "app" }, "status": { "$ref": "#/components/schemas/EmailStatus", "description": "The current status of the email.", "example": "draft" }, "subject": { "description": "The subject line for the email.", "maxLength": 2000, "title": "Subject", "type": "string" }, "suppression_reason": { "anyOf": [ { "$ref": "#/components/schemas/EmailSuppressionReason" }, { "type": "null" } ], "description": "If the email has been suppressed from sending, the reason why." }, "template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "If present, this template overrides your newsletter's default email template." } }, "required": [ "id", "creation_date", "absolute_url", "body", "canonical_url", "commenting_mode", "description", "archival_mode", "featured", "filters", "image", "modification_date", "related_email_ids", "should_trigger_pay_per_email_billing", "source", "status", "subject" ], "title": "Email", "type": "object" }, "EmailTransition": { "properties": { "date": { "description": "When the email address change took effect.", "format": "date-time", "title": "Date", "type": "string" }, "old_email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscriber's previous email address, or null for the initial address.", "title": "Old Email Address" }, "new_email_address": { "description": "The subscriber's email address after the transition.", "title": "New Email Address", "type": "string" } }, "required": [ "date", "new_email_address" ], "title": "EmailTransition", "type": "object" }, "FirewallReason": { "properties": { "code": { "$ref": "#/components/schemas/FirewallReasonCode", "description": "The code of the firewall facet that flagged this subscriber." }, "reason": { "description": "Human-readable explanation for why we flagged the subscriber.", "title": "Reason", "type": "string" } }, "required": [ "code", "reason" ], "title": "FirewallReason", "type": "object" }, "FirewallReasonCode": { "enum": [ "email_address_capital_letters", "email_address_cleantalk_score", "email_address_contains_prohibited_string", "email_address_esp_suppression", "email_address_extant_subscriber_count", "email_address_gmail_word_numbers", "email_address_has_gravatar", "email_address_is_honeypot", "email_address_length", "email_address_local_part_has_many_periods", "email_address_many_consonants_in_a_row", "email_address_mx_record_is_valid", "email_address_noreply_local_part", "email_address_null_characters", "email_address_peaceful_domain", "email_address_plus_single_number", "email_address_previous_evaluation", "email_address_prohibited_via_domain", "email_address_regex", "email_address_sandbox_test", "email_address_shannon_entropy", "email_address_stopforumspam_score", "email_address_tied_to_account", "email_address_typo", "embedded_form_honeypot", "fingerprint_missing", "ip_address_cleantalk_score", "ip_address_country_risk", "ip_address_extant_subscriber_count", "ip_address_peaceful", "ip_address_previous_evaluation", "ip_address_prohibited", "metadata_has_garbage", "newsletter_age", "newsletter_has_customized_transactional_email", "newsletter_has_prohibited_string", "newsletter_status", "project_honeypot", "referrer_url_prohibited", "subscriber_import_provenance", "subscriber_import_source", "text_contains_malicious_url", "text_contains_prohibited_string", "turnstile_response_token_is_valid", "user_agent_known" ], "title": "FirewallReasonCode", "type": "string", "description": "An enumeration." }, "StripeCoupon": { "description": "Coupons let you offer discounts to subscribers who pay for your newsletter.\nButtondown's coupons are backed by Stripe, so each coupon maps to a coupon\non your connected Stripe account. Use them to run promotions\u2014for example, a\npercentage off a paid subscription.", "properties": { "coupon_id": { "description": "The Stripe coupon ID (e.g. `coupon_...`).", "title": "Coupon Id", "type": "string" }, "percent_off": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The percentage discount applied by the coupon, if any.", "title": "Percent Off" }, "amount_off": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The fixed amount discount applied by the coupon, in the smallest currency unit (e.g. cents), if any.", "title": "Amount Off" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the coupon.", "title": "Name" } }, "required": [ "coupon_id" ], "title": "StripeCoupon", "type": "object" }, "Subscriber": { "description": "Subscribers are the main way you collect email addresses and\nrecipients on Buttondown. They're what you see on your\n[subscribers page](https://buttondown.com/subscribers).\n\nRelevant changes to the schema:\n\n- [2024-08-01](https://docs.buttondown.com/api-changelog-2024-08-01): renamed `subscriber_type` and `email` to `type` and `email_address` respectively.\n- [2024-07-13](https://docs.buttondown.com/api-changelog-2024-08-01): removed `external_url` in favor of `absolute_url`.", "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" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the subscriber's avatar image (e.g. a Gravatar URL), if available.", "title": "Avatar Url" }, "bounce_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable.", "title": "Bounce Date" }, "bounce_reason": { "anyOf": [ { "$ref": "#/components/schemas/SubscriberUndeliverabilityReason" }, { "type": "null" } ], "description": "The reason of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable." }, "churn_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber cancelled their paid subscription, if applicable.", "title": "Churn Date" }, "commenting_disabled": { "default": false, "description": "Whether this subscriber is prevented from commenting.", "title": "Commenting Disabled", "type": "boolean" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ISO 3166-1 alpha-2 country code inferred from the subscriber's IP address at signup, if available.", "example": "US", "title": "Country" }, "email_address": { "description": "The email address of the subscriber.", "example": "telemachus@buttondown.email", "title": "Email Address", "type": "string" }, "gift_subscription_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber's gift subscription expires, if applicable.", "title": "Gift Subscription End Date" }, "gift_subscription_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A custom message that was sent to the subscriber when the gift subscription was created.", "title": "Gift Subscription Message" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The IP address recorded when the subscriber signed up, if available.", "title": "Ip Address" }, "last_click_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber most recently clicked a link in an email.", "title": "Last Click Date" }, "last_open_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber most recently opened an email.", "title": "Last Open Date" }, "delivered_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of distinct emails \u2014 both broadcasts and automation sends \u2014 delivered to this subscriber. Cached and refreshed periodically, so it may lag recent activity.", "example": 12, "title": "Delivered Count" }, "open_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The subscriber's open count.", "example": 7, "title": "Open Count" }, "clicked_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The subscriber's clicked count.", "example": 3, "title": "Clicked Count" }, "open_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The subscriber's open rate, computed from engagement counts. Null if delivered_count is 0 or null.", "example": 0.5833, "title": "Open Rate" }, "click_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The subscriber's click rate, computed from engagement counts. Null if delivered_count is 0 or null.", "example": 0.25, "title": "Click Rate" }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" }, "notes": { "default": "", "description": "Any notes you want to attach to the subscriber. These are not publicly visible.", "title": "Notes", "type": "string" }, "purchased_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email address of the individual who purchased this subscription on behalf of the subscriber.", "title": "Purchased By" }, "purchased_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A custom message that was sent to the subscriber when the subscription was purchased on behalf of the subscriber.", "title": "Purchased Message" }, "referral_code": { "description": "The subscriber's unique referral code, used to attribute referred signups.", "title": "Referral Code", "type": "string" }, "referrer_url": { "default": "", "description": "The URL the subscriber was referred from (e.g. where they submitted the subscription form).", "title": "Referrer Url", "type": "string" }, "risk_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The risk score of the subscriber. Positive numbers represent a higher risk; negative numbers represent a lower risk.", "title": "Risk Score" }, "secondary_id": { "description": "A human-readable sequential identifier, unique within the newsletter.", "title": "Secondary Id", "type": "integer" }, "source": { "$ref": "#/components/schemas/SubscriberSource", "description": "Where the subscriber signed up from (e.g. `api`, `import`, `form`)." }, "stripe_coupon": { "anyOf": [ { "$ref": "#/components/schemas/StripeCoupon" }, { "type": "null" } ], "description": "The Stripe coupon applied to the subscriber's paid subscription, if any." }, "stripe_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Stripe customer ID associated with the subscriber, if any.", "title": "Stripe Customer Id" }, "subscriber_import_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the [subscriber import](https://docs.buttondown.com/importing-subscribers) that created this subscriber, if any.", "title": "Subscriber Import Id" }, "tags": { "description": "A list of [tag](https://docs.buttondown.com/api-tags-introduction) names applied to the subscriber. Tags that don't already exist will be created.", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "transitions": { "default": [], "description": "The history of subscriber type transitions (e.g. `regular` \u2192 `premium`).", "items": { "$ref": "#/components/schemas/Transition" }, "title": "Transitions", "type": "array" }, "email_transitions": { "default": [], "description": "The history of email address changes for this subscriber.", "items": { "$ref": "#/components/schemas/EmailTransition" }, "title": "Email Transitions", "type": "array" }, "form_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the [registration form](https://docs.buttondown.com/registration-forms) the subscriber signed up through, if any.", "title": "Form Id" }, "firewall_reasons": { "description": "Information collected by Buttondown's firewall about this subscriber. See [the firewall](https://docs.buttondown.com/firewall) for more information.", "items": { "$ref": "#/components/schemas/FirewallReason" }, "title": "Firewall Reasons", "type": "array" }, "type": { "$ref": "#/components/schemas/SubscriberType", "description": "The subscriber's lifecycle state \u2014 e.g. `regular` (active), `premium` (paid), `unactivated` (pending confirmation), `unsubscribed`, `removed`." }, "undeliverability_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber was marked as undeliverable, if applicable.", "title": "Undeliverability Date" }, "undeliverability_reason": { "anyOf": [ { "$ref": "#/components/schemas/SubscriberUndeliverabilityReason" }, { "type": "null" } ], "description": "The reason the subscriber is undeliverable. (Only populated for undeliverable subscribers.)" }, "unsubscription_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber unsubscribed, if applicable.", "title": "Unsubscription Date" }, "unsubscription_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text reason the subscriber unsubscribed, if provided.", "title": "Unsubscription Reason" }, "upgrade_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscriber upgraded to a paid subscription, if applicable.", "title": "Upgrade Date" }, "utm_campaign": { "description": "The UTM campaign the subscriber was attributed to at signup.", "title": "Utm Campaign", "type": "string" }, "utm_medium": { "description": "The UTM medium the subscriber was attributed to at signup.", "title": "Utm Medium", "type": "string" }, "utm_source": { "description": "The UTM source the subscriber was attributed to at signup.", "title": "Utm Source", "type": "string" }, "stripe_customer": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "If expanded, the Stripe customer associated with this subscriber.", "title": "Stripe Customer" }, "stripe_subscription": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "If expanded, the Stripe subscription backing this subscriber's paid subscription.", "title": "Stripe Subscription" } }, "required": [ "id", "creation_date", "email_address", "referral_code", "secondary_id", "source", "tags", "type", "utm_campaign", "utm_medium", "utm_source" ], "title": "Subscriber", "type": "object" }, "Transition": { "properties": { "date": { "description": "When the subscriber transitioned to `type`.", "format": "date-time", "title": "Date", "type": "string" }, "type": { "$ref": "#/components/schemas/SubscriberType", "description": "The subscriber type the subscriber transitioned to at `date`." } }, "required": [ "date", "type" ], "title": "Transition", "type": "object" }, "CommentInput": { "additionalProperties": false, "properties": { "text": { "description": "The text content of the comment.", "minLength": 1, "pattern": "[\\s\\S]*\\S[\\s\\S]*", "title": "Text", "type": "string" }, "parent_id": { "anyOf": [ { "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:com)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, { "type": "null" } ], "description": "The ID of the parent comment, if this comment is a reply to another comment.", "title": "Parent Id" }, "email_id": { "anyOf": [ { "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, { "type": "null" } ], "description": "The ID of the email this comment is for. Required if parent_id is not provided.", "title": "Email Id" }, "subscriber_id": { "anyOf": [ { "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "type": "string" }, { "type": "null" } ], "description": "The ID of the subscriber to attribute the comment to. If not provided, the comment is attributed to the newsletter author.", "title": "Subscriber Id" } }, "required": [ "text" ], "title": "CommentInput", "type": "object" }, "CommentUpdateInput": { "additionalProperties": false, "properties": { "status": { "description": "The new status for the comment. Use 'active' to approve or 'spammy' to mark as spam.", "enum": [ "active", "spammy" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "CommentUpdateInput", "type": "object" }, "EmailCreationErrorCode": { "description": "Represents the type of error that occurred when creating an email.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "body_contains_frontmatter", "email_duplicate", "email_not_confirmed", "body_invalid", "canonical_url_invalid", "email_invalid", "slug_invalid", "subject_invalid", "pay_per_email_billing_locked", "publish_date_invalid", "publish_date_missing", "sending_requires_confirmation", "status_invalid", "tag_invalid" ], "title": "EmailCreationErrorCode", "type": "string" }, "ErrorMessage_EmailCreationErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/EmailCreationErrorCode" } ], "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[EmailCreationErrorCode]", "type": "object" }, "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" }, "EmailInput": { "properties": { "attachments": { "default": [], "description": "A list of attachment IDs present on the email. (See [Attachments](https://docs.buttondown.com/api-attachments-introduction) for more information.)", "items": { "type": "string" }, "title": "Attachments", "type": "array" }, "publish_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time at which the email should be published in the future (for scheduled emails), or the date and time at which the email was published (for sent emails).", "title": "Publish Date" }, "subject": { "description": "The subject line for the email.", "example": "The subject line for the email", "maxLength": 2000, "title": "Subject", "type": "string" }, "slug": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "A short, human-readable identifier for the email, used in the archive URL.", "title": "Slug" }, "description": { "default": "", "description": "A human-readable description of the email, used for archives and SEO.", "title": "Description", "type": "string" }, "canonical_url": { "default": "", "description": "The URL of the original source of the content.", "maxLength": 2000, "title": "Canonical Url", "type": "string" }, "image": { "default": "", "description": "A primary image URL used when previewing the email on the web or in other contexts.", "title": "Image", "type": "string" }, "body": { "default": "", "description": "The body of the email, in either HTML or markdown format. Buttondown attempts to intelligently detect the format of the body automatically, but you can also specify the format explicitly by prepending the text with the `buttondown-editor-mode` comment: `` or ``.", "example": "This is an example of the body of an email.", "title": "Body", "type": "string" }, "archival_mode": { "allOf": [ { "$ref": "#/components/schemas/ArchivalMode" } ], "default": "enabled", "description": "Controls who can view this email in the archive." }, "email_type": { "allOf": [ { "$ref": "#/components/schemas/EmailType" } ], "default": "public", "deprecated": true, "description": "The type of email. Defaults to `PUBLIC`." }, "status": { "allOf": [ { "$ref": "#/components/schemas/EmailStatus" } ], "default": "about_to_send", "description": "The status of the email (e.g. `draft`, `about_to_send`, `sent`, `scheduled`)." }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" }, "secondary_id": { "anyOf": [ { "maximum": 1000000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "An informal 'number' for the email, used in some templates (e.g. 'This was issue #123').", "title": "Secondary Id" }, "filters": { "allOf": [ { "$ref": "#/components/schemas/EmailFilterGroup" } ], "default": { "filters": [], "groups": [], "predicate": "and" }, "description": "Tag-based filter rules determining which subscribers receive this email." }, "commenting_mode": { "allOf": [ { "$ref": "#/components/schemas/EmailCommentingMode" } ], "default": "enabled", "description": "Controls whether subscribers can comment on this email." }, "related_email_ids": { "description": "IDs of emails related to this one. Shown at the bottom of the email and archive pages.", "items": { "type": "string" }, "title": "Related Email Ids", "type": "array" }, "featured": { "default": false, "description": "Designated whether or not this email should be highlighted within the archives.", "title": "Featured", "type": "boolean" }, "should_trigger_pay_per_email_billing": { "default": false, "description": "Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate between free updates and premium newsletters.", "title": "Should Trigger Pay Per Email Billing", "type": "boolean" } }, "required": [ "subject" ], "title": "EmailInput", "type": "object" }, "EmailListErrorCode": { "description": "Represents the type of error that occurred when listing emails.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "creation_date_invalid", "publish_date_invalid" ], "title": "EmailListErrorCode", "type": "string" }, "ErrorMessage_EmailListErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/EmailListErrorCode" } ], "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[EmailListErrorCode]", "type": "object" }, "EmailUpdateInput": { "properties": { "attachments": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "A list of attachment IDs present on the email. (See [Attachments](https://docs.buttondown.com/api-attachments-introduction) for more information.)", "title": "Attachments" }, "publish_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "const": "none", "type": "string" }, { "type": "null" } ], "description": "The date and time at which the email should be published in the future (for scheduled emails), or the date and time at which the email was published (for sent emails). Pass `\"none\"` to clear a scheduled date.", "title": "Publish Date" }, "subject": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The subject line for the email.", "example": "The subject line for the email", "title": "Subject" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A human-readable description of the email, used for archives and SEO.", "title": "Description" }, "canonical_url": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "The URL of the original source of the content.", "example": "https://sheinhardtwig.com/2025/01/17/our-nbc-partnership", "title": "Canonical Url" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body of the email, in either HTML or markdown format. Buttondown attempts to intelligently detect the format of the body automatically, but you can also specify the format explicitly by prepending the text with the `buttondown-editor-mode` comment: `` or ``.", "example": "This is an example of the body of an email.", "title": "Body" }, "archival_mode": { "anyOf": [ { "$ref": "#/components/schemas/ArchivalMode" }, { "type": "null" } ], "description": "Controls who can view this email in the archive." }, "email_type": { "anyOf": [ { "$ref": "#/components/schemas/EmailType" }, { "type": "null" } ], "deprecated": true, "description": "The type of email. Defaults to `PUBLIC`." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/EmailStatus" }, { "type": "null" } ], "description": "The status of the email (e.g. `draft`, `about_to_send`, `sent`, `scheduled`)." }, "suppression_reason": { "anyOf": [ { "$ref": "#/components/schemas/EmailSuppressionReason" }, { "type": "null" } ], "description": "If the email has been suppressed from sending, the reason why." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata" }, "image": { "default": "", "description": "A primary image URL used when previewing the email on the web or in other contexts.", "title": "Image", "type": "string" }, "slug": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "A short, human-readable identifier for the email, used in the archive URL.", "example": "hello-world", "title": "Slug" }, "secondary_id": { "anyOf": [ { "maximum": 1000000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "An informal 'number' for the email, used in some templates (e.g. 'This was issue #123').", "title": "Secondary Id" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/EmailFilterGroup" }, { "type": "null" } ], "description": "Tag-based filter rules determining which subscribers receive this email." }, "template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "const": "none", "type": "string" }, { "type": "null" } ], "description": "If present, this template overrides your newsletter's default email template. Pass `\"none\"` to clear an override.", "title": "Template" }, "commenting_mode": { "anyOf": [ { "$ref": "#/components/schemas/EmailCommentingMode" }, { "type": "null" } ], "description": "Controls whether subscribers can comment on this email." }, "related_email_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "IDs of emails related to this one. Shown at the bottom of the email and archive pages.", "title": "Related Email Ids" }, "featured": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Designated whether or not this email should be highlighted within the archives.", "title": "Featured" }, "should_trigger_pay_per_email_billing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether this email should trigger pay-per-email billing for paid subscribers. Use this to differentiate between free updates and premium newsletters.", "title": "Should Trigger Pay Per Email Billing" } }, "title": "EmailUpdateInput", "type": "object" }, "AccessLevel": { "enum": [ "none", "read", "write" ], "title": "AccessLevel", "type": "string", "description": "An enumeration." }, "History": { "properties": { "history_id": { "description": "A monotonically increasing history entry ID.", "title": "History Id", "type": "integer" }, "creation_date": { "description": "The date and time at which the object was first created.", "format": "date-time", "title": "Creation Date", "type": "string" }, "value": { "description": "The field's value at the time of this history entry.", "title": "Value", "type": "string" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the user who made this change, if attributable.", "title": "User Id" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ], "description": "If expanded, the user who made this change." } }, "required": [ "history_id", "creation_date", "value" ], "title": "History", "type": "object" }, "Permissions": { "properties": { "subscriber": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for subscriber management." }, "email": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for email management." }, "sending": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for sending emails." }, "styling": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for newsletter styling." }, "administrivia": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for account administration." }, "automations": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for automation management." }, "surveys": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for survey management." }, "forms": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "default": "none", "description": "Access level for form management." } }, "title": "Permissions", "type": "object" }, "User": { "properties": { "permissions": { "$ref": "#/components/schemas/Permissions" }, "email_address": { "description": "The email address of the user.", "title": "Email Address", "type": "string" }, "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" }, "status": { "$ref": "#/components/schemas/InvitationStatus", "description": "The status of the user's invitation (e.g. `pending`, `accepted`)." }, "last_logged_in": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the user last logged in, or null if they haven't accepted the invitation.", "title": "Last Logged In" } }, "required": [ "permissions", "email_address", "id", "creation_date", "status" ], "title": "User", "type": "object" }, "Render": { "properties": { "content": { "description": "The rendered HTML for the specified target format.", "title": "Content", "type": "string" } }, "required": [ "content" ], "title": "Render", "type": "object" }, "SendDraftInput": { "properties": { "subscribers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "A list of subscriber ids to which to send the email.", "example": [ "bc5601f4-b180-4e02-8501-c18080662376", "24ee3338-daaf-42b0-bf7b-0cab38972fe5" ], "title": "Subscribers" }, "recipients": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "A list of email addresses to send the email to.", "example": [ "telemachus@buttondown.email" ], "title": "Recipients" } }, "title": "SendDraftInput", "type": "object" }, "EmailEventType": { "enum": [ "activation_bounced", "activation_clicked", "activation_complained", "activation_deferred", "activation_delivered", "activation_opened", "activation_rejected", "activation_reminder_bounced", "activation_reminder_clicked", "activation_reminder_complained", "activation_reminder_deferred", "activation_reminder_delivered", "activation_reminder_opened", "activation_reminder_rejected", "subscription_confirmed_clicked", "subscription_confirmed_bounced", "subscription_confirmed_complained", "subscription_confirmed_deferred", "subscription_confirmed_delivered", "subscription_confirmed_opened", "subscription_confirmed_rejected", "attempted", "bounced", "clicked", "complained", "deferred", "delivered", "opened", "rejected", "replied", "sent", "unsubscribed" ], "title": "EmailEventType", "type": "string", "description": "An enumeration." }, "EmailEvent": { "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" }, "subscriber_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the subscriber the event is attributed to, if any.", "title": "Subscriber Id" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the email the event is attributed to, if any.", "title": "Email Id" }, "automation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the automation that sent the email, if any.", "title": "Automation Id" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Event-type-specific metadata (e.g. clicked URL, bounce reason).", "title": "Metadata", "type": "object" }, "event_type": { "$ref": "#/components/schemas/EmailEventType", "description": "The type of event (e.g. `delivered`, `opened`, `clicked`, `unsubscribed`)." }, "subscriber": { "anyOf": [ { "$ref": "#/components/schemas/Subscriber" }, { "type": "null" } ] }, "email": { "anyOf": [ { "$ref": "#/components/schemas/Email" }, { "type": "null" } ] }, "automation": { "anyOf": [ { "$ref": "#/components/schemas/Automation" }, { "type": "null" } ] } }, "required": [ "id", "creation_date", "metadata", "event_type" ], "title": "EmailEvent", "type": "object" }, "Export": { "description": "Some software applications may want programmatic access to their newsletter exports.\nThis assists with a few niche use cases, such as regular backups or data ingestion\n(into a data warehouse), or post-publishing processes that hinge on email events.\n\nIn general, you probably won't _need_ to use this endpoint unless you\n_absolutely_ need to use this endpoint.\n\nTo browse the contents of a given export collection, refer to the [Data exports](https://docs.buttondown.com/data-exports-subscriber) section\nof the documentation.", "properties": { "collections": { "description": "The [collections](https://docs.buttondown.com/api-exports-collections) of objects to export.", "items": { "$ref": "#/components/schemas/ExportCollection" }, "title": "Collections", "type": "array" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Parameters to pass to the exporter. These are specific to the collection and format, and constrain the export.", "title": "Parameters" }, "format": { "allOf": [ { "$ref": "#/components/schemas/ExportFormat" } ], "default": "csv", "description": "The [format](https://docs.buttondown.com/api-exports-format) of the export files." }, "columns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "If provided, the export will only include these columns.", "title": "Columns" }, "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" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The URL of the export file. This is only available after the export has completed.", "title": "Url" }, "completion_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The date and time the export completed.", "title": "Completion Date" }, "status": { "$ref": "#/components/schemas/ExportStatus", "description": "The status of the export." } }, "required": [ "collections", "id", "creation_date", "status" ], "title": "Export", "type": "object" }, "CreateExportErrorCode": { "enum": [ "collection_empty_invalid", "columns_empty_invalid", "columns_invalid" ], "title": "CreateExportErrorCode", "type": "string", "description": "An enumeration." }, "ErrorMessage_CreateExportErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreateExportErrorCode" } ], "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[CreateExportErrorCode]", "type": "object" }, "ExportInput": { "properties": { "collections": { "description": "The [collections](https://docs.buttondown.com/api-exports-collections) of objects to export.", "items": { "$ref": "#/components/schemas/ExportCollection" }, "title": "Collections", "type": "array" }, "parameters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Parameters to pass to the exporter. These are specific to the collection and format, and constrain the export.", "title": "Parameters" }, "format": { "allOf": [ { "$ref": "#/components/schemas/ExportFormat" } ], "default": "csv", "description": "The [format](https://docs.buttondown.com/api-exports-format) of the export files." }, "columns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "If provided, the export will only include these columns.", "title": "Columns" } }, "required": [ "collections" ], "title": "ExportInput", "type": "object" }, "ExternalFeed": { "description": "An automation is a one-to-one mapping between an external RSS feed and an action\nto be performed when new items are detected in that feed. Right now, Buttondown offers\ntwo actions:\n\n- Send an email\n- Create an email but save it as a draft to be sent out manually\n\nThe automation is configured with a cadence, which is the frequency at which the\nautomation will be run. The cadence can be one of the following:\n\n- Run the automation every time a new item is detected in the feed\n- Run the automation once per week\n- Run the automation once per month", "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" }, "last_checked_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The most recent date and time this feed was checked for new items.", "title": "Last Checked Date" }, "status": { "$ref": "#/components/schemas/ExternalFeedAutomationStatus", "description": "The current status of the external feed automation." }, "behavior": { "$ref": "#/components/schemas/ExternalFeedAutomationBehavior", "description": "Whether feed items are sent immediately or drafted for manual review." }, "cadence": { "$ref": "#/components/schemas/ExternalFeedAutomationCadence", "description": "How frequently this feed should create or draft emails." }, "cadence_metadata": { "additionalProperties": { "type": "string" }, "description": "Additional scheduling details for the selected cadence. `time` is required for `daily`/`weekly`/`monthly` cadences; `weekday` is required for `weekly`; `monthday` is required for `monthly`. See the [cadence metadata reference](https://docs.buttondown.com/api-external-feed-cadence-metadata) for allowed values.", "title": "Cadence Metadata", "type": "object" }, "filters": { "$ref": "#/components/schemas/FilterGroup", "description": "Tag-based filtering rules used to decide which subscribers receive feed-generated emails." }, "url": { "description": "The URL of the RSS feed to poll for new items.", "title": "Url", "type": "string" }, "subject": { "description": "The subject line template for emails generated from this feed.", "title": "Subject", "type": "string" }, "body": { "description": "The body template for emails generated from this feed.", "title": "Body", "type": "string" }, "label": { "description": "An optional internal label for this feed.", "title": "Label", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Metadata to be passed to emails rendered by this RSS feed.", "example": { "foo": "bar" }, "title": "Metadata", "type": "object" }, "skip_old_items": { "description": "Skip items with publish date older than one day from when they're discovered", "title": "Skip Old Items", "type": "boolean" } }, "required": [ "id", "creation_date", "status", "behavior", "cadence", "cadence_metadata", "filters", "url", "subject", "body", "label", "skip_old_items" ], "title": "ExternalFeed", "type": "object" }, "CadenceMetadata": { "properties": { "time": { "anyOf": [ { "pattern": "^([01]?[0-9]|2[0-3])$", "type": "string" }, { "type": "null" } ], "description": "Hour of the day (0-23, as a string) when emails should be generated.", "example": "9", "title": "Time" }, "weekday": { "anyOf": [ { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, { "type": "null" } ], "description": "Day of the week when emails should be generated. Required when cadence is `weekly`.", "title": "Weekday" }, "monthday": { "anyOf": [ { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday", "firstday", "lastday" ], "type": "string" }, { "type": "null" } ], "description": "Day of the month when emails should be generated. Accepts a weekday name (first such day of the month), `firstday`, or `lastday`. Required when cadence is `monthly`.", "title": "Monthday" } }, "title": "CadenceMetadata", "type": "object" }, "ExternalFeedInput": { "properties": { "url": { "description": "The URL of the RSS feed to poll for new items.", "example": "http://lorem-rss.herokuapp.com/feed", "maxLength": 2000, "title": "Url", "type": "string" }, "behavior": { "$ref": "#/components/schemas/ExternalFeedAutomationBehavior", "description": "The [behavior](https://docs.buttondown.com/api-external-feed-behavior) of the external feed.", "example": "draft" }, "cadence": { "$ref": "#/components/schemas/ExternalFeedAutomationCadence", "description": "How frequently this feed should create or draft emails.", "example": "daily" }, "cadence_metadata": { "allOf": [ { "$ref": "#/components/schemas/CadenceMetadata" } ], "description": "Additional scheduling details for the selected cadence. `time` is required for `daily`/`weekly`/`monthly` cadences; `weekday` is required for `weekly`; `monthday` is required for `monthly`. See the [cadence metadata reference](https://docs.buttondown.com/api-external-feed-cadence-metadata) for allowed values." }, "filters": { "$ref": "#/components/schemas/FilterGroup", "description": "Tag-based filtering rules used to decide which subscribers receive feed-generated emails." }, "subject": { "description": "The subject line template for emails generated from this feed.", "maxLength": 255, "title": "Subject", "type": "string" }, "body": { "description": "The body template for emails generated from this feed.", "title": "Body", "type": "string" }, "label": { "default": "", "description": "An optional internal label for this feed.", "maxLength": 255, "title": "Label", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Metadata to be passed to emails rendered by this RSS feed.", "example": { "foo": "bar" }, "title": "Metadata", "type": "object" }, "skip_old_items": { "default": false, "description": "Skip items with publish date older than one day from when they're discovered", "title": "Skip Old Items", "type": "boolean" } }, "required": [ "url", "behavior", "cadence", "filters", "subject", "body" ], "title": "ExternalFeedInput", "type": "object" }, "ExternalFeedUpdateInput": { "properties": { "behavior": { "anyOf": [ { "$ref": "#/components/schemas/ExternalFeedAutomationBehavior" }, { "type": "null" } ], "description": "The [behavior](https://docs.buttondown.com/api-external-feed-behavior) of the external feed.", "example": "draft" }, "cadence": { "anyOf": [ { "$ref": "#/components/schemas/ExternalFeedAutomationCadence" }, { "type": "null" } ], "description": "How frequently this feed should create or draft emails.", "example": "daily" }, "cadence_metadata": { "anyOf": [ { "$ref": "#/components/schemas/CadenceMetadata" }, { "type": "null" } ], "description": "Additional scheduling details for the selected cadence. `time` is required for `daily`/`weekly`/`monthly` cadences; `weekday` is required for `weekly`; `monthday` is required for `monthly`. See the [cadence metadata reference](https://docs.buttondown.com/api-external-feed-cadence-metadata) for allowed values." }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/FilterGroup" }, { "type": "null" } ], "description": "Tag-based filtering rules used to decide which subscribers receive feed-generated emails." }, "subject": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "The subject line template for emails generated from this feed.", "title": "Subject" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body template for emails generated from this feed.", "title": "Body" }, "label": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "An optional internal label for this feed.", "title": "Label" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/ExternalFeedAutomationStatus" }, { "type": "null" } ], "description": "The current status of the external feed automation." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Metadata to be passed to emails rendered by this RSS feed.", "example": { "foo": "bar" }, "title": "Metadata" }, "skip_old_items": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Skip items with publish date older than one day from when they're discovered", "title": "Skip Old Items" } }, "title": "ExternalFeedUpdateInput", "type": "object" }, "Empty": { "properties": {}, "title": "Empty", "type": "object" }, "ExternalFeedItem": { "description": "An external feed item is a single item in an external RSS feed. It is created\nautomatically by Buttondown when a new item is detected in an external feed. External feed\nitems are immutable and cannot be modified or deleted.", "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" }, "status": { "$ref": "#/components/schemas/ExternalFeedItemStatus", "description": "The processing status of this feed item." }, "url": { "description": "The canonical URL of the feed item.", "title": "Url", "type": "string" }, "publish_date": { "description": "The publication date parsed from the feed item.", "format": "date-time", "title": "Publish Date", "type": "string" }, "title": { "description": "The title of the feed item.", "title": "Title", "type": "string" }, "description": { "description": "The description excerpt parsed from the feed item.", "title": "Description", "type": "string" }, "content": { "description": "The full content parsed from the feed item.", "title": "Content", "type": "string" }, "author": { "description": "The author name parsed from the feed item.", "title": "Author", "type": "string" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the generated email for this feed item, if one exists.", "title": "Email Id" }, "email": { "anyOf": [ { "$ref": "#/components/schemas/Email" }, { "type": "null" } ], "description": "If expanded, the email generated from this feed item." } }, "required": [ "id", "creation_date", "status", "url", "publish_date", "title", "description", "content", "author" ], "title": "ExternalFeedItem", "type": "object" }, "Form": { "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" }, "title": { "description": "The human-readable title of the form, shown in the UI and on the hosted form page.", "title": "Title", "type": "string" }, "slug": { "description": "A URL-safe identifier used in the form's hosted URL (e.g. `/forms/{slug}`). Must be unique per newsletter.", "title": "Slug", "type": "string" }, "body": { "description": "Markdown body rendered above the subscribe fields on the hosted form page.", "title": "Body", "type": "string" }, "css": { "description": "Custom CSS applied to the hosted form page.", "title": "Css", "type": "string" }, "success_body": { "description": "Markdown shown to the subscriber after a successful submission.", "title": "Success Body", "type": "string" }, "surveys": { "description": "IDs of surveys to attach to this form. Responses are associated with the submitting subscriber.", "items": { "type": "string" }, "title": "Surveys", "type": "array" }, "admin": { "description": "If true, the form acts as an admin-only signup form \u2014 it skips confirmation and can accept additional subscriber fields.", "title": "Admin", "type": "boolean" }, "status": { "$ref": "#/components/schemas/FormStatus", "description": "The status of the form. Only `active` forms accept submissions." }, "subscriber_count": { "description": "The number of subscribers who signed up through this form.", "title": "Subscriber Count", "type": "integer" }, "confirmed_subscriber_count": { "description": "The number of confirmed subscribers who signed up through this form.", "title": "Confirmed Subscriber Count", "type": "integer" }, "page_view_count": { "description": "The number of page views for this form.", "title": "Page View Count", "type": "integer" } }, "required": [ "id", "creation_date", "title", "slug", "body", "css", "success_body", "surveys", "admin", "status", "subscriber_count", "confirmed_subscriber_count", "page_view_count" ], "title": "Form", "type": "object" }, "CreateFormErrorCode": { "description": "Represents the type of error that occurred when creating a form.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "slug_already_exists" ], "title": "CreateFormErrorCode", "type": "string" }, "ErrorMessage_CreateFormErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreateFormErrorCode" } ], "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[CreateFormErrorCode]", "type": "object" }, "FormInput": { "properties": { "title": { "description": "The human-readable title of the form, shown in the UI and on the hosted form page.", "maxLength": 255, "title": "Title", "type": "string", "example": "Contact Form" }, "slug": { "description": "A URL-safe identifier used in the form's hosted URL (e.g. `/forms/{slug}`). Must be unique per newsletter.", "maxLength": 100, "title": "Slug", "type": "string", "example": "contact" }, "body": { "default": "", "description": "Markdown body rendered above the subscribe fields on the hosted form page.", "title": "Body", "type": "string", "example": "" }, "css": { "default": "", "description": "Custom CSS applied to the hosted form page.", "title": "Css", "type": "string", "example": "" }, "success_body": { "default": "", "description": "Markdown shown to the subscriber after a successful submission.", "title": "Success Body", "type": "string", "example": "Thank you for your submission!" }, "surveys": { "description": "IDs of surveys to attach to this form. Responses are associated with the submitting subscriber.", "items": { "type": "string" }, "title": "Surveys", "type": "array", "example": [] }, "admin": { "default": false, "description": "If true, the form acts as an admin-only signup form \u2014 it skips confirmation and can accept additional subscriber fields.", "title": "Admin", "type": "boolean", "example": false }, "status": { "allOf": [ { "$ref": "#/components/schemas/FormStatus" } ], "default": "active", "description": "The status of the form. Only `active` forms accept submissions.", "example": "active" } }, "required": [ "title", "slug" ], "title": "FormInput", "type": "object" }, "FormUpdateInput": { "properties": { "title": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "The human-readable title of the form, shown in the UI and on the hosted form page.", "title": "Title" }, "slug": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "A URL-safe identifier used in the form's hosted URL (e.g. `/forms/{slug}`). Must be unique per newsletter.", "title": "Slug" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Markdown body rendered above the subscribe fields on the hosted form page.", "title": "Body" }, "css": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom CSS applied to the hosted form page.", "title": "Css" }, "success_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Markdown shown to the subscriber after a successful submission.", "title": "Success Body" }, "surveys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "IDs of surveys to attach to this form. Responses are associated with the submitting subscriber.", "title": "Surveys" }, "admin": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "If true, the form acts as an admin-only signup form \u2014 it skips confirmation and can accept additional subscriber fields.", "title": "Admin" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/FormStatus" }, { "type": "null" } ], "description": "The status of the form. Only `active` forms accept submissions." } }, "title": "FormUpdateInput", "type": "object" }, "Image": { "description": "Images are, well, images! Buttondown allows you to upload images to its secure\nS3 bucket and do with them what you will. This is sort of an odd duck of an\nAPI, to be sure, but if you want to be able to do things like draft\nand send emails completely on your iPad you need a surefire way of creating images.", "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" }, "image": { "description": "The URL of the image.", "title": "Image", "type": "string", "example": "https://placecats.com/408/287" }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" } }, "required": [ "id", "creation_date", "image" ], "title": "Image", "type": "object" }, "ImageUpdateInput": { "additionalProperties": false, "properties": { "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" } }, "title": "ImageUpdateInput", "type": "object" }, "Import": { "description": "Imports let you bring data into Buttondown in bulk by uploading a file.\nCurrently, subscriber imports are supported.", "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" }, "type": { "$ref": "#/components/schemas/ImportType", "description": "The type of import." }, "status": { "$ref": "#/components/schemas/ImportStatus", "description": "The current status of the import." }, "source": { "$ref": "#/components/schemas/ImportSource", "description": "The detected source of the import file." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional label for the import.", "title": "Label" }, "metadata": { "additionalProperties": true, "description": "Metadata about the import, such as detected column mappings.", "title": "Metadata", "type": "object" }, "results": { "anyOf": [ { "$ref": "#/components/schemas/ImportResult" }, { "type": "null" } ], "description": "The results of the import, available after completion." } }, "required": [ "id", "creation_date", "type", "status", "source" ], "title": "Import", "type": "object" }, "ImportResult": { "properties": { "new_subscribers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of new subscribers created by the import.", "title": "New Subscribers" }, "updated_subscribers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of existing subscribers updated by the import.", "title": "Updated Subscribers" }, "existing_subscribers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of subscribers that already existed and were skipped.", "title": "Existing Subscribers" }, "reason_to_bad_subscribers": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "A mapping of error reasons to the list of email addresses that failed for that reason.", "title": "Reason To Bad Subscribers", "type": "object" }, "new_tags": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of new tags created by the import.", "title": "New Tags" } }, "title": "ImportResult", "type": "object" }, "ImportSource": { "enum": [ "bare", "buttondown", "custom", "flodesk", "ghost", "google", "mailchimp", "mailerlite", "memberful", "sender_dot_net", "sendy", "shopify", "sparkloop", "squarespace", "standard", "substack", "tinyletter" ], "title": "ImportSource", "type": "string", "description": "An enumeration." }, "ImportStatus": { "enum": [ "not_started", "in_progress", "validating", "failed", "succeeded" ], "title": "ImportStatus", "type": "string", "description": "An enumeration." }, "ImportType": { "enum": [ "subscriber_import" ], "title": "ImportType", "type": "string", "description": "An enumeration." }, "CreateImportErrorCode": { "enum": [ "import_failure", "invalid_file_type", "malformed_csv" ], "title": "CreateImportErrorCode", "type": "string", "description": "An enumeration." }, "ErrorMessage_CreateImportErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreateImportErrorCode" } ], "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[CreateImportErrorCode]", "type": "object" }, "UpdateImportInput": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional label for the import.", "title": "Label" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Metadata about the import, such as detected column mappings.", "title": "Metadata" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/ImportStatus" }, { "type": "null" } ], "description": "The status of the import. Set to 'in_progress' to begin executing the import." } }, "title": "UpdateImportInput", "type": "object" }, "Newsletter": { "description": "You will likely not need to interact with your newsletter settings\nprogrammatically, but if you do, this is the endpoint for you. You can\ncreate, update, and list newsletters via the API; this is ideal for\nintegrating with Buttondown as a headless email or newsletter provider\n(e.g. for a SaaS product.)", "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" }, "announcement_bar_background_color": { "default": "", "description": "The background color for the announcement bar on your archive page. Must be a valid hex color code.", "title": "Announcement Bar Background Color", "type": "string" }, "announcement_bar_text": { "default": "", "description": "Text displayed in the announcement bar on your archive page. Useful for promotions, updates, or calls to action.", "title": "Announcement Bar Text", "type": "string" }, "announcement_bar_visibility": { "allOf": [ { "$ref": "#/components/schemas/NewsletterAnnouncementBarVisibility" } ], "default": "disabled", "description": "Controls who sees the announcement bar on your archive page.", "enum": [ "disabled", "everyone", "free_only", "logged_out_only", "paid_only" ] }, "api_key": { "description": "The API key for this newsletter, used for authenticating API requests.", "format": "uuid", "title": "Api Key", "type": "string" }, "archive_theme": { "allOf": [ { "$ref": "#/components/schemas/NewsletterArchiveTheme" } ], "default": "modern", "description": "The visual theme for your newsletter's archive page. See [archive themes](https://docs.buttondown.com/customizing-web-design) for previews.", "enum": [ "classic", "modern", "arbus", "lovelace", "myrna" ] }, "auditing_mode": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterAuditingMode" }, { "type": "null" } ], "description": "The auditing mode for your newsletter, which controls spam and abuse protection. See [the Firewall](https://docs.buttondown.com/firewall) for more information.", "enum": [ "disabled", "enabled", "aggressive" ] }, "css": { "default": "", "description": "Custom CSS styling applied to your newsletter emails. See [CSS customization](https://docs.buttondown.com/customizing-email-design#adding-custom-css) for more information.", "title": "Css", "type": "string" }, "custom_churn_email_body": { "default": "", "description": "Custom body content for the email sent when a paid subscriber cancels. Supports template tags like `{{ subscriber.email }}` and `{{ newsletter.name }}`.", "title": "Custom Churn Email Body", "type": "string" }, "custom_churn_email_subject": { "default": "", "description": "Custom subject line for the email sent when a paid subscriber cancels. Supports template tags like `{{ newsletter.name }}`.", "title": "Custom Churn Email Subject", "type": "string" }, "custom_churn_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for churn emails. If not set, uses the newsletter's default template." }, "custom_email_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The identifier for a custom email template. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options.", "title": "Custom Email Template" }, "custom_expired_trial_notification_body": { "default": "", "description": "Custom body content for the email sent when a subscriber's free trial expires. Supports template tags.", "title": "Custom Expired Trial Notification Body", "type": "string" }, "custom_expired_trial_notification_subject": { "default": "", "description": "Custom subject line for the email sent when a subscriber's free trial expires. Supports template tags.", "title": "Custom Expired Trial Notification Subject", "type": "string" }, "custom_expired_trial_notification_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for expired trial notification emails. If not set, uses the newsletter's default template." }, "custom_gift_subscription_email_body": { "default": "", "description": "Custom body content for the email sent when someone receives a gift subscription. Supports template tags.", "title": "Custom Gift Subscription Email Body", "type": "string" }, "custom_gift_subscription_email_subject": { "default": "", "description": "Custom subject line for the email sent when someone receives a gift subscription. Supports template tags.", "title": "Custom Gift Subscription Email Subject", "type": "string" }, "custom_gift_subscription_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for gift subscription emails. If not set, uses the newsletter's default template." }, "custom_gift_unsubscription_email_body": { "default": "", "description": "Custom body content for the email sent when a gift subscription ends. Supports template tags.", "title": "Custom Gift Unsubscription Email Body", "type": "string" }, "custom_gift_unsubscription_email_subject": { "default": "", "description": "Custom subject line for the email sent when a gift subscription ends. Supports template tags.", "title": "Custom Gift Unsubscription Email Subject", "type": "string" }, "custom_gift_unsubscription_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for gift unsubscription emails. If not set, uses the newsletter's default template." }, "custom_premium_confirmation_email_body": { "default": "", "description": "Custom body content for the email sent when a subscriber upgrades to a paid plan. Supports template tags.", "title": "Custom Premium Confirmation Email Body", "type": "string" }, "custom_premium_confirmation_email_subject": { "default": "", "description": "Custom subject line for the email sent when a subscriber upgrades to a paid plan. Supports template tags.", "title": "Custom Premium Confirmation Email Subject", "type": "string" }, "custom_premium_confirmation_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for premium confirmation emails. If not set, uses the newsletter's default template." }, "custom_subscription_confirmation_email_subject": { "default": "", "description": "Custom subject line for the double opt-in confirmation email sent to new subscribers. Supports template tags.", "title": "Custom Subscription Confirmation Email Subject", "type": "string" }, "custom_subscription_confirmation_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for subscription confirmation emails. If not set, uses the newsletter's default template." }, "custom_subscription_confirmation_email_text": { "default": "", "description": "Custom body content for the double opt-in confirmation email. Must contain `{{ confirmation_url }}` as an HTML or Markdown link.", "title": "Custom Subscription Confirmation Email Text", "type": "string" }, "custom_subscription_confirmation_reminder_email_subject": { "default": "", "description": "Custom subject line for the reminder email sent to subscribers who haven't confirmed. Supports template tags.", "title": "Custom Subscription Confirmation Reminder Email Subject", "type": "string" }, "custom_subscription_confirmation_reminder_email_text": { "default": "", "description": "Custom body content for the reminder email sent to subscribers who haven't confirmed. Supports template tags.", "title": "Custom Subscription Confirmation Reminder Email Text", "type": "string" }, "custom_subscription_confirmed_email_subject": { "default": "", "description": "Custom subject line for the email sent after a subscriber confirms their subscription. Supports template tags.", "title": "Custom Subscription Confirmed Email Subject", "type": "string" }, "custom_subscription_confirmed_email_text": { "default": "", "description": "Custom body content for the email sent after a subscriber confirms their subscription. Supports template tags.", "title": "Custom Subscription Confirmed Email Text", "type": "string" }, "description": { "description": "A brief description of your newsletter, displayed on your public archive page and used for SEO.", "title": "Description", "type": "string" }, "domain": { "default": "", "description": "The custom domain where your newsletter archives are hosted (e.g., 'newsletter.example.com'). See [custom domains](https://docs.buttondown.com/hosting-on-a-custom-domain) for setup instructions.", "title": "Domain", "type": "string" }, "email_address": { "default": "", "description": "The 'From' email address used when sending your newsletter. Must be verified before use.", "title": "Email Address", "type": "string" }, "email_domain": { "default": "", "description": "The custom domain from which your newsletter emails are sent (e.g., 'mail.example.com'). See [sending domains](https://docs.buttondown.com/sending-from-a-custom-domain) for setup instructions.", "title": "Email Domain", "type": "string" }, "email_theme_configuration": { "additionalProperties": { "type": "string" }, "default": {}, "description": "A dictionary of CSS token overrides for the email theme.", "title": "Email Theme Configuration", "type": "object" }, "enabled_features": { "default": [], "description": "A list of features enabled for your newsletter. Common values include 'archives', 'portal', 'surveys', 'comments', 'paid_subscriptions', 'automations', 'webhooks', 'tracking', and 'referrals'.", "items": { "type": "string" }, "title": "Enabled Features", "type": "array" }, "footer": { "default": "", "description": "HTML content displayed at the bottom of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags).", "title": "Footer", "type": "string" }, "from_name": { "default": "", "description": "The display name shown in the 'From' field of your emails (e.g., 'Jane from Acme Newsletter').", "title": "From Name", "type": "string" }, "header": { "default": "", "description": "HTML content displayed at the top of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags).", "title": "Header", "type": "string" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to your newsletter's icon image, used as a favicon and in various UI contexts.", "title": "Icon" }, "icon_alt_text": { "default": "", "description": "Alt text for the newsletter icon, used by screen readers and shown when the image cannot load.", "title": "Icon Alt Text", "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to your newsletter's header or branding image, displayed on archive pages and in social previews.", "title": "Image" }, "locale": { "allOf": [ { "$ref": "#/components/schemas/NewsletterLocale" } ], "default": "en", "description": "The language/locale for your newsletter's UI elements (confirmation emails, unsubscribe pages, etc.). See [localization](https://docs.buttondown.com/localization) for supported locales." }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" }, "name": { "description": "The display name of your newsletter, shown to subscribers and on your archive page.", "title": "Name", "type": "string" }, "reply_to_address": { "default": "", "description": "An alternative email address that receives replies to your newsletter emails, instead of the sending address.", "title": "Reply To Address", "type": "string" }, "sharing_networks": { "default": [], "description": "A list of social networks to show share buttons for on your archive pages.", "items": { "type": "string" }, "title": "Sharing Networks", "type": "array" }, "socials": { "default": [], "description": "A list of social media accounts linked to your newsletter, displayed on your archive page. Each entry has a `type`, `url`, and optional `label`.", "items": { "$ref": "#/components/schemas/SocialAccountSchema" }, "title": "Socials", "type": "array" }, "sort": { "default": "creation_date", "description": "The default sorting method for listing subscribers or messages. Example values: 'creation_date', '-creation_date', 'email_address'.", "title": "Sort", "type": "string" }, "subscription_confirmation_redirect_url": { "default": "", "description": "A URL to redirect subscribers to after they confirm their subscription via double opt-in.", "title": "Subscription Confirmation Redirect Url", "type": "string" }, "subscription_redirect_url": { "default": "", "description": "A URL to redirect subscribers to immediately after they submit the subscription form (before confirmation).", "title": "Subscription Redirect Url", "type": "string" }, "template": { "allOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" } ], "default": "modern", "description": "The default email template for your newsletter. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options." }, "test_mode": { "default": false, "description": "Whether test mode is enabled. When enabled, emails are not actually sent to subscribers, useful for testing automations and workflows.", "title": "Test Mode", "type": "boolean" }, "theme_configuration": { "additionalProperties": { "type": "string" }, "default": {}, "description": "Custom theme configuration (variables) for your newsletter. These can be referenced in your CSS and templates to maintain consistent styling.", "title": "Theme Configuration", "type": "object" }, "timezone": { "default": "Etc/UTC", "description": "The timezone used for scheduling and displaying dates in your newsletter (e.g., 'America/New_York', 'Europe/London').", "title": "Timezone", "type": "string" }, "tint_color": { "default": "#0069FF", "description": "The accent color for your newsletter, used in emails and on your archive page. Must be a valid hex color code.", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "title": "Tint Color", "type": "string" }, "username": { "description": "The unique URL-safe identifier for your newsletter, used in your archive URL (e.g., 'buttondown.com/username').", "title": "Username", "type": "string" }, "web_css": { "default": "", "description": "Custom CSS styling applied to your newsletter's web presence (archive pages, subscription forms, etc.).", "title": "Web Css", "type": "string" } }, "required": [ "id", "creation_date", "api_key", "description", "name", "username" ], "title": "Newsletter", "type": "object" }, "SocialAccountSchema": { "properties": { "type": { "$ref": "#/components/schemas/SocialAccountType", "description": "The type of social media account." }, "url": { "description": "The URL of the social media profile.", "title": "Url", "type": "string" }, "label": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "description": "An optional display label for the social media account.", "title": "Label" } }, "required": [ "type", "url" ], "title": "SocialAccountSchema", "type": "object" }, "SocialAccountType": { "enum": [ "generic", "bluesky", "bookbub", "bookshop", "facebook", "github", "goodreads", "instagram", "kofi", "letterboxd", "linkedin", "linktree", "mastodon", "patreon", "pinterest", "threads", "tiktok", "twitch", "twitter", "youtube" ], "title": "SocialAccountType", "type": "string", "description": "An enumeration." }, "CreateNewsletterErrorCode": { "description": "Represents the type of error that occurred when creating a newsletter.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "username_already_exists", "username_malformed" ], "title": "CreateNewsletterErrorCode", "type": "string" }, "ErrorMessage_CreateNewsletterErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreateNewsletterErrorCode" } ], "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[CreateNewsletterErrorCode]", "type": "object" }, "NewsletterInput": { "properties": { "announcement_bar_background_color": { "default": "", "description": "The background color for the announcement bar on your archive page. Must be a valid hex color code.", "example": "#FF6600", "maxLength": 7, "title": "Announcement Bar Background Color", "type": "string" }, "announcement_bar_text": { "default": "", "description": "Text displayed in the announcement bar on your archive page. Useful for promotions, updates, or calls to action.", "example": "Subscribe to get 20% off your first order!", "title": "Announcement Bar Text", "type": "string" }, "announcement_bar_visibility": { "allOf": [ { "$ref": "#/components/schemas/NewsletterAnnouncementBarVisibility" } ], "default": "disabled", "description": "Controls who sees the announcement bar on your archive page.", "enum": [ "disabled", "everyone", "free_only", "logged_out_only", "paid_only" ], "example": "everyone" }, "archive_theme": { "allOf": [ { "$ref": "#/components/schemas/NewsletterArchiveTheme" } ], "default": "modern", "description": "The visual theme for your newsletter's archive page. See [archive themes](https://docs.buttondown.com/customizing-web-design) for previews.", "example": "modern" }, "auditing_mode": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterAuditingMode" }, { "type": "null" } ], "description": "The auditing mode for your newsletter, which controls spam and abuse protection. See [the Firewall](https://docs.buttondown.com/firewall) for more information.", "example": "enabled" }, "css": { "default": "", "description": "Custom CSS styling applied to your newsletter emails. See [CSS customization](https://docs.buttondown.com/customizing-email-design#adding-custom-css) for more information.", "example": ".header { color: #000; }", "title": "Css", "type": "string" }, "custom_email_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The identifier for a custom email template. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options.", "example": "modern", "title": "Custom Email Template" }, "description": { "description": "A brief description of your newsletter, displayed on your public archive page and used for SEO.", "example": "Stay up to date with the latest trends in wigs and hairpieces", "title": "Description", "type": "string" }, "domain": { "default": "", "description": "The custom domain where your newsletter archives are hosted (e.g., 'newsletter.example.com'). See [custom domains](https://docs.buttondown.com/hosting-on-a-custom-domain) for setup instructions.", "example": "sheinhardt.com", "maxLength": 500, "title": "Domain", "type": "string" }, "email_address": { "anyOf": [ { "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$", "type": "string" }, { "type": "null" } ], "description": "The 'From' email address used when sending your newsletter. Must be verified before use.", "example": "newsletter@sheinhardt.com", "title": "Email Address" }, "email_domain": { "default": "", "description": "The custom domain from which your newsletter emails are sent (e.g., 'mail.example.com'). See [sending domains](https://docs.buttondown.com/sending-from-a-custom-domain) for setup instructions.", "example": "mail.sheinhardt.com", "maxLength": 500, "title": "Email Domain", "type": "string" }, "email_theme_configuration": { "additionalProperties": { "type": "string" }, "default": {}, "description": "A dictionary of CSS token overrides for the email theme.", "example": { "primary-color": "#0069FF" }, "title": "Email Theme Configuration", "type": "object" }, "enabled_features": { "default": [], "description": "A list of features enabled for your newsletter. Common values include 'archives', 'portal', 'surveys', 'comments', 'paid_subscriptions', 'automations', 'webhooks', 'tracking', and 'referrals'.", "example": [ "archives", "portal", "surveys" ], "items": { "type": "string" }, "title": "Enabled Features", "type": "array" }, "footer": { "default": "", "description": "HTML content displayed at the bottom of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags).", "example": "

Thanks for reading!

", "title": "Footer", "type": "string" }, "from_name": { "default": "", "description": "The display name shown in the 'From' field of your emails (e.g., 'Jane from Acme Newsletter').", "example": "Sheinhardt Wig Company", "title": "From Name", "type": "string" }, "header": { "default": "", "description": "HTML content displayed at the top of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags).", "example": "

Welcome to our newsletter!

", "title": "Header", "type": "string" }, "icon": { "default": "", "description": "URL to your newsletter's icon image, used as a favicon and in various UI contexts.", "example": "https://example.com/icon.png", "title": "Icon", "type": "string" }, "icon_alt_text": { "default": "", "description": "Alt text for the newsletter icon, used by screen readers and shown when the image cannot load.", "title": "Icon Alt Text", "type": "string" }, "image": { "default": "", "description": "URL to your newsletter's header or branding image, displayed on archive pages and in social previews.", "example": "https://example.com/header.jpg", "title": "Image", "type": "string" }, "locale": { "allOf": [ { "$ref": "#/components/schemas/NewsletterLocale" } ], "default": "en", "description": "The language/locale for your newsletter's UI elements (confirmation emails, unsubscribe pages, etc.). See [localization](https://docs.buttondown.com/localization) for supported locales.", "example": "en" }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" }, "name": { "description": "The display name of your newsletter, shown to subscribers and on your archive page.", "example": "Sheinhardt Wig Company", "title": "Name", "type": "string" }, "reply_to_address": { "anyOf": [ { "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$", "type": "string" }, { "type": "null" } ], "description": "An alternative email address that receives replies to your newsletter emails, instead of the sending address.", "example": "newsletter@sheinhardt.com", "title": "Reply To Address" }, "socials": { "default": [], "description": "A list of social media accounts linked to your newsletter, displayed on your archive page. Each entry has a `type`, `url`, and optional `label`.", "example": [ { "label": null, "type": "twitter", "url": "https://x.com/sheinhardt" } ], "items": { "$ref": "#/components/schemas/SocialAccountSchema" }, "title": "Socials", "type": "array" }, "subscription_confirmation_redirect_url": { "default": "", "description": "A URL to redirect subscribers to after they confirm their subscription via double opt-in.", "example": "https://example.com/confirmed", "title": "Subscription Confirmation Redirect Url", "type": "string" }, "subscription_redirect_url": { "default": "", "description": "A URL to redirect subscribers to immediately after they submit the subscription form (before confirmation).", "example": "https://example.com/thanks", "title": "Subscription Redirect Url", "type": "string" }, "template": { "allOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" } ], "default": "modern", "description": "The default email template for your newsletter. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options.", "example": "modern" }, "test_mode": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether test mode is enabled. When enabled, emails are not actually sent to subscribers, useful for testing automations and workflows.", "title": "Test Mode" }, "theme_configuration": { "additionalProperties": { "type": "string" }, "default": {}, "description": "Custom theme configuration (variables) for your newsletter. These can be referenced in your CSS and templates to maintain consistent styling.", "example": { "primary-color": "#0069FF" }, "title": "Theme Configuration", "type": "object" }, "timezone": { "default": "Etc/UTC", "description": "The timezone used for scheduling and displaying dates in your newsletter (e.g., 'America/New_York', 'Europe/London').", "example": "America/New_York", "title": "Timezone", "type": "string" }, "tint_color": { "default": "#0069FF", "description": "The accent color for your newsletter, used in emails and on your archive page. Must be a valid hex color code.", "example": "#0069FF", "maxLength": 7, "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "title": "Tint Color", "type": "string" }, "username": { "description": "The unique URL-safe identifier for your newsletter, used in your archive URL (e.g., 'buttondown.com/username').", "example": "sheinhardt", "title": "Username", "type": "string" }, "web_css": { "default": "", "description": "Custom CSS styling applied to your newsletter's web presence (archive pages, subscription forms, etc.).", "example": ".container { max-width: 800px; }", "title": "Web Css", "type": "string" } }, "required": [ "description", "name", "username" ], "title": "NewsletterInput", "type": "object" }, "NewsletterUpdateInput": { "properties": { "announcement_bar_background_color": { "anyOf": [ { "maxLength": 7, "type": "string" }, { "type": "null" } ], "description": "The background color for the announcement bar on your archive page. Must be a valid hex color code.", "example": "#FF6600", "title": "Announcement Bar Background Color" }, "announcement_bar_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text displayed in the announcement bar on your archive page. Useful for promotions, updates, or calls to action.", "example": "Subscribe to get 20% off your first order!", "title": "Announcement Bar Text" }, "announcement_bar_visibility": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterAnnouncementBarVisibility" }, { "type": "null" } ], "description": "Controls who sees the announcement bar on your archive page.", "enum": [ "disabled", "everyone", "free_only", "logged_out_only", "paid_only" ], "example": "everyone" }, "archive_theme": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterArchiveTheme" }, { "type": "null" } ], "description": "The visual theme for your newsletter's archive page. See [archive themes](https://docs.buttondown.com/customizing-web-design) for previews.", "example": "modern" }, "auditing_mode": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterAuditingMode" }, { "type": "null" } ], "description": "The auditing mode for your newsletter, which controls spam and abuse protection. See [the Firewall](https://docs.buttondown.com/firewall) for more information.", "example": "enabled" }, "css": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom CSS styling applied to your newsletter emails. See [CSS customization](https://docs.buttondown.com/customizing-email-design#adding-custom-css) for more information.", "example": ".header { color: #000; }", "title": "Css" }, "custom_churn_email_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the email sent when a paid subscriber cancels. Supports template tags like `{{ subscriber.email }}` and `{{ newsletter.name }}`.", "example": "Hi {{ subscriber.email }},\n\nWe're sorry to see you go!", "title": "Custom Churn Email Body" }, "custom_churn_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the email sent when a paid subscriber cancels. Supports template tags like `{{ newsletter.name }}`.", "example": "You've canceled your premium subscription to {{ newsletter.name }}", "title": "Custom Churn Email Subject" }, "custom_churn_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for churn emails. If not set, uses the newsletter's default template.", "example": "modern" }, "custom_email_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The identifier for a custom email template. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options.", "example": "modern", "title": "Custom Email Template" }, "custom_expired_trial_notification_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the email sent when a subscriber's free trial expires. Supports template tags.", "title": "Custom Expired Trial Notification Body" }, "custom_expired_trial_notification_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the email sent when a subscriber's free trial expires. Supports template tags.", "title": "Custom Expired Trial Notification Subject" }, "custom_expired_trial_notification_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for expired trial notification emails. If not set, uses the newsletter's default template.", "example": "modern" }, "custom_gift_subscription_email_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the email sent when someone receives a gift subscription. Supports template tags.", "title": "Custom Gift Subscription Email Body" }, "custom_gift_subscription_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the email sent when someone receives a gift subscription. Supports template tags.", "title": "Custom Gift Subscription Email Subject" }, "custom_gift_subscription_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for gift subscription emails. If not set, uses the newsletter's default template.", "example": "modern" }, "custom_gift_unsubscription_email_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the email sent when a gift subscription ends. Supports template tags.", "title": "Custom Gift Unsubscription Email Body" }, "custom_gift_unsubscription_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the email sent when a gift subscription ends. Supports template tags.", "title": "Custom Gift Unsubscription Email Subject" }, "custom_gift_unsubscription_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for gift unsubscription emails. If not set, uses the newsletter's default template.", "example": "modern" }, "custom_premium_confirmation_email_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the email sent when a subscriber upgrades to a paid plan. Supports template tags.", "title": "Custom Premium Confirmation Email Body" }, "custom_premium_confirmation_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the email sent when a subscriber upgrades to a paid plan. Supports template tags.", "title": "Custom Premium Confirmation Email Subject" }, "custom_premium_confirmation_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for premium confirmation emails. If not set, uses the newsletter's default template.", "example": "modern" }, "custom_subscription_confirmation_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the double opt-in confirmation email sent to new subscribers. Supports template tags.", "title": "Custom Subscription Confirmation Email Subject" }, "custom_subscription_confirmation_email_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the double opt-in confirmation email. Must contain `{{ confirmation_url }}` as an HTML or Markdown link.", "title": "Custom Subscription Confirmation Email Text" }, "custom_subscription_confirmation_email_template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The email template to use for subscription confirmation emails. If not set, uses the newsletter's default template.", "example": "modern" }, "custom_subscription_confirmation_reminder_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the reminder email sent to subscribers who haven't confirmed. Supports template tags.", "title": "Custom Subscription Confirmation Reminder Email Subject" }, "custom_subscription_confirmation_reminder_email_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the reminder email sent to subscribers who haven't confirmed. Supports template tags.", "title": "Custom Subscription Confirmation Reminder Email Text" }, "custom_subscription_confirmed_email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom subject line for the email sent after a subscriber confirms their subscription. Supports template tags.", "title": "Custom Subscription Confirmed Email Subject" }, "custom_subscription_confirmed_email_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom body content for the email sent after a subscriber confirms their subscription. Supports template tags.", "title": "Custom Subscription Confirmed Email Text" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A brief description of your newsletter, displayed on your public archive page and used for SEO.", "example": "Stay up to date with the latest trends in wigs and hairpieces", "title": "Description" }, "domain": { "anyOf": [ { "maxLength": 500, "pattern": "^(([a-zA-Z]{1})|([a-zA-Z]{1}[a-zA-Z]{1})|([a-zA-Z]{1}[0-9]{1})|([0-9]{1}[a-zA-Z]{1})|([a-zA-Z0-9][-_.a-zA-Z0-9]{0,61}[a-zA-Z0-9]))\\.([a-zA-Z]{2,13}|[a-zA-Z0-9-]{2,30}.[a-zA-Z]{2,3})$|^$", "type": "string" }, { "type": "null" } ], "description": "The custom domain where your newsletter archives are hosted (e.g., 'newsletter.example.com'). See [custom domains](https://docs.buttondown.com/hosting-on-a-custom-domain) for setup instructions.", "example": "sheinhardt.com", "title": "Domain" }, "email_address": { "anyOf": [ { "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$", "type": "string" }, { "type": "null" } ], "description": "The 'From' email address used when sending your newsletter. Must be verified before use.", "example": "newsletter@sheinhardt.com", "title": "Email Address" }, "email_domain": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "The custom domain from which your newsletter emails are sent (e.g., 'mail.example.com'). See [sending domains](https://docs.buttondown.com/sending-from-a-custom-domain) for setup instructions.", "example": "mail.sheinhardt.com", "title": "Email Domain" }, "email_theme_configuration": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "A dictionary of CSS token overrides for the email theme.", "example": { "primary-color": "#0069FF" }, "title": "Email Theme Configuration" }, "enabled_features": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "A list of features enabled for your newsletter. Common values include 'archives', 'portal', 'surveys', 'comments', 'paid_subscriptions', 'automations', 'webhooks', 'tracking', and 'referrals'.", "example": [ "archives", "portal", "surveys" ], "title": "Enabled Features" }, "footer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content displayed at the bottom of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags).", "example": "

Thanks for reading!

", "title": "Footer" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name shown in the 'From' field of your emails (e.g., 'Jane from Acme Newsletter').", "example": "Sheinhardt Wig Company", "title": "From Name" }, "header": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML content displayed at the top of your newsletter emails. Supports [template tags](https://docs.buttondown.com/template-tags).", "example": "

Welcome to our newsletter!

", "title": "Header" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to your newsletter's icon image, used as a favicon and in various UI contexts.", "example": "https://example.com/icon.png", "title": "Icon" }, "icon_alt_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alt text for the newsletter icon, used by screen readers and shown when the image cannot load.", "title": "Icon Alt Text" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to your newsletter's header or branding image, displayed on archive pages and in social previews.", "example": "https://example.com/header.jpg", "title": "Image" }, "locale": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterLocale" }, { "type": "null" } ], "description": "The language/locale for your newsletter's UI elements (confirmation emails, unsubscribe pages, etc.). See [localization](https://docs.buttondown.com/localization) for supported locales.", "example": "en" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "example": { "source": "my-app", "tier": "pro" }, "title": "Metadata" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of your newsletter, shown to subscribers and on your archive page.", "example": "Sheinhardt Wig Company", "title": "Name" }, "reply_to_address": { "anyOf": [ { "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$", "type": "string" }, { "type": "null" } ], "description": "An alternative email address that receives replies to your newsletter emails, instead of the sending address.", "example": "newsletter@sheinhardt.com", "title": "Reply To Address" }, "socials": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SocialAccountSchema" }, "type": "array" }, { "type": "null" } ], "description": "A list of social media accounts linked to your newsletter, displayed on your archive page. Each entry has a `type`, `url`, and optional `label`.", "example": [ { "label": null, "type": "twitter", "url": "https://x.com/sheinhardt" } ], "title": "Socials" }, "subscription_confirmation_redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URL to redirect subscribers to after they confirm their subscription via double opt-in.", "example": "https://example.com/confirmed", "title": "Subscription Confirmation Redirect Url" }, "subscription_redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A URL to redirect subscribers to immediately after they submit the subscription form (before confirmation).", "example": "https://example.com/thanks", "title": "Subscription Redirect Url" }, "template": { "anyOf": [ { "$ref": "#/components/schemas/NewsletterEmailTemplate" }, { "type": "null" } ], "description": "The default email template for your newsletter. See [email templates](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates) for available options.", "example": "modern" }, "test_mode": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether test mode is enabled. When enabled, emails are not actually sent to subscribers, useful for testing automations and workflows.", "title": "Test Mode" }, "theme_configuration": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "Custom theme configuration (variables) for your newsletter. These can be referenced in your CSS and templates to maintain consistent styling.", "example": { "primary-color": "#0069FF" }, "title": "Theme Configuration" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timezone used for scheduling and displaying dates in your newsletter (e.g., 'America/New_York', 'Europe/London').", "example": "America/New_York", "title": "Timezone" }, "tint_color": { "anyOf": [ { "maxLength": 7, "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "type": "string" }, { "type": "null" } ], "description": "The accent color for your newsletter, used in emails and on your archive page. Must be a valid hex color code.", "example": "#0069FF", "title": "Tint Color" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The unique URL-safe identifier for your newsletter, used in your archive URL (e.g., 'buttondown.com/username').", "example": "sheinhardt", "title": "Username" }, "web_css": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom CSS styling applied to your newsletter's web presence (archive pages, subscription forms, etc.).", "example": ".container { max-width: 800px; }", "title": "Web Css" } }, "title": "NewsletterUpdateInput", "type": "object" }, "Note": { "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" }, "body": { "description": "The text content of the note.", "example": "This subscriber upgraded to a paid plan.", "minLength": 1, "pattern": "[\\s\\S]*\\S[\\s\\S]*", "title": "Body", "type": "string" }, "model_type": { "description": "The type of object this note is attached to (e.g., 'email', 'subscriber').", "enum": [ "automation", "comment", "conversation", "email", "external_feed", "invitation", "socialmention", "stripe_customer", "subscriber", "survey", "tag", "webmention" ], "example": "email", "title": "Model Type", "type": "string" }, "model_id": { "description": "The UUID or TypeID of the object this note is attached to.", "example": "13121cd6-0dfc-424c-bb12-988b0a32fcb3", "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:permission|unsub_req|auth_tok|rec_code|webauthn|api_req|aut_att|ext_evt|str_cus|str_sub|sub_imp|sub_tag|adslot|em_dom|em_evt|em_imp|le_evt|str_pd|adsku|socmn|webmn|book|bulk|cnvs|form|hook|inbx|news|note|resp|rssi|snip|snpr|acc|att|aut|com|exp|img|inv|mes|rss|smp|srv|sub|dr|em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "title": "Model Id", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "source": { "description": "The source of the note. If the note was created by a Buttondown admin, this will be 'admin'; otherwise, it will be 'user'.", "enum": [ "admin", "user" ], "example": "admin", "title": "Source", "type": "string" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] } }, "required": [ "id", "creation_date", "body", "model_type", "model_id", "metadata", "source" ], "title": "Note", "type": "object" }, "NoteInput": { "properties": { "body": { "description": "The text content of the note.", "example": "This subscriber upgraded to a paid plan.", "minLength": 1, "pattern": "[\\s\\S]*\\S[\\s\\S]*", "title": "Body", "type": "string" }, "model_type": { "description": "The type of object this note is attached to (e.g., 'email', 'subscriber').", "enum": [ "automation", "comment", "conversation", "email", "external_feed", "invitation", "socialmention", "stripe_customer", "subscriber", "survey", "tag", "webmention" ], "example": "email", "title": "Model Type", "type": "string" }, "model_id": { "description": "The UUID or TypeID of the object this note is attached to.", "example": "13121cd6-0dfc-424c-bb12-988b0a32fcb3", "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:permission|unsub_req|auth_tok|rec_code|webauthn|api_req|aut_att|ext_evt|str_cus|str_sub|sub_imp|sub_tag|adslot|em_dom|em_evt|em_imp|le_evt|str_pd|adsku|socmn|webmn|book|bulk|cnvs|form|hook|inbx|news|note|resp|rssi|snip|snpr|acc|att|aut|com|exp|img|inv|mes|rss|smp|srv|sub|dr|em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "title": "Model Id", "type": "string" }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" } }, "required": [ "body", "model_type", "model_id" ], "title": "NoteInput", "type": "object" }, "Price": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The price amount in the smallest currency unit (e.g. cents).", "title": "Amount" }, "cadence": { "description": "The billing cadence for this price.", "enum": [ "year", "month", "one-time", "email", "week" ], "title": "Cadence", "type": "string" }, "currency": { "description": "The three-letter ISO currency code (e.g. 'usd').", "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional human-readable description of the price.", "title": "Description" }, "maximum_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The maximum amount for pay-what-you-want prices.", "title": "Maximum Amount" }, "minimum_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The minimum amount for pay-what-you-want prices.", "title": "Minimum Amount" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the Stripe product this price belongs to.", "title": "Product Id" }, "style": { "description": "The pricing style: 'fixed', 'pay-what-you-want', or 'usage-based'.", "enum": [ "pay-what-you-want", "fixed", "usage-based" ], "title": "Style", "type": "string" }, "suggested_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The suggested amount for pay-what-you-want prices.", "title": "Suggested Amount" }, "id": { "description": "The unique identifier of the price.", "title": "Id", "type": "string" }, "product": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "null" } ] } }, "required": [ "cadence", "currency", "style", "id" ], "title": "Price", "type": "object" }, "Product": { "properties": { "id": { "description": "The unique identifier of the product.", "title": "Id", "type": "string" }, "product_id": { "description": "The Stripe product ID.", "title": "Product Id", "type": "string" }, "name": { "description": "The name of the product.", "title": "Name", "type": "string" }, "creation_date": { "description": "The date the product was created in Stripe.", "title": "Creation Date", "type": "string" }, "active": { "description": "Whether the product is currently active.", "title": "Active", "type": "boolean" }, "default_price": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the default price for this product.", "title": "Default Price" } }, "required": [ "id", "product_id", "name", "creation_date", "active" ], "title": "Product", "type": "object" }, "ErrorMessage_ListPricesErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/ListPricesErrorCode" } ], "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[ListPricesErrorCode]", "type": "object" }, "ListPricesErrorCode": { "description": "Represents the type of error that occurred when listing a price.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "paid_subscriptions_uninitialized" ], "title": "ListPricesErrorCode", "type": "string" }, "CreatePriceErrorCode": { "description": "Represents the type of error that occurred when listing a price.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "invalid_amount", "maximum_amount_too_high", "minimum_amount_not_less_than_maximum", "paid_subscriptions_uninitialized", "product_deleted", "suggested_amount_out_of_range" ], "title": "CreatePriceErrorCode", "type": "string" }, "ErrorMessage_CreatePriceErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreatePriceErrorCode" } ], "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[CreatePriceErrorCode]", "type": "object" }, "PriceInput": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The price amount in the smallest currency unit (e.g. cents).", "title": "Amount" }, "cadence": { "description": "The billing cadence for this price.", "enum": [ "year", "month", "one-time", "email", "week" ], "title": "Cadence", "type": "string" }, "currency": { "description": "The three-letter ISO currency code (e.g. 'usd').", "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An optional human-readable description of the price.", "title": "Description" }, "maximum_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The maximum amount for pay-what-you-want prices.", "title": "Maximum Amount" }, "minimum_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The minimum amount for pay-what-you-want prices.", "title": "Minimum Amount" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the Stripe product this price belongs to.", "title": "Product Id" }, "style": { "description": "The pricing style: 'fixed', 'pay-what-you-want', or 'usage-based'.", "enum": [ "pay-what-you-want", "fixed", "usage-based" ], "title": "Style", "type": "string" }, "suggested_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The suggested amount for pay-what-you-want prices.", "title": "Suggested Amount" } }, "required": [ "cadence", "currency", "style" ], "title": "PriceInput", "type": "object" }, "PublicEmail": { "description": "Public email schema for email search results.", "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" }, "subject": { "title": "Subject", "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "publish_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Publish Date" }, "description": { "title": "Description", "type": "string" }, "absolute_url": { "title": "Absolute Url", "type": "string" } }, "required": [ "id", "creation_date", "subject", "description", "absolute_url" ], "title": "PublicEmail", "type": "object" }, "Snippet": { "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" }, "identifier": { "description": "A unique, newsletter-scoped slug used to reference the snippet inside email content (e.g. `{{ snippets.footer }}`). Must be unique per newsletter.", "title": "Identifier", "type": "string" }, "name": { "description": "A human-readable name for the snippet, shown in the Buttondown UI.", "title": "Name", "type": "string" }, "content": { "description": "The body of the snippet, substituted wherever the snippet is referenced. Interpreted according to `mode`.", "title": "Content", "type": "string" }, "mode": { "$ref": "#/components/schemas/SnippetMode", "description": "The editor mode for the snippet, which controls how `content` is rendered: `fancy` (Markdown), `plaintext`, or `naked` (raw HTML with no processing)." }, "reference_count": { "default": 0, "description": "The number of emails that currently reference this snippet.", "title": "Reference Count", "type": "integer" } }, "required": [ "id", "creation_date", "identifier", "name", "content", "mode" ], "title": "Snippet", "type": "object" }, "SnippetInput": { "properties": { "identifier": { "description": "A unique, newsletter-scoped slug used to reference the snippet inside email content (e.g. `{{ snippets.footer }}`). Must be unique per newsletter.", "maxLength": 100, "title": "Identifier", "type": "string", "example": "footer" }, "name": { "description": "A human-readable name for the snippet, shown in the Buttondown UI.", "maxLength": 255, "title": "Name", "type": "string", "example": "Footer" }, "content": { "default": "", "description": "The body of the snippet, substituted wherever the snippet is referenced. Interpreted according to `mode`.", "title": "Content", "type": "string", "example": "Thanks for reading!" }, "mode": { "allOf": [ { "$ref": "#/components/schemas/SnippetMode" } ], "default": "fancy", "description": "The editor mode for the snippet, which controls how `content` is rendered: `fancy` (Markdown), `plaintext`, or `naked` (raw HTML with no processing)." } }, "required": [ "identifier", "name" ], "title": "SnippetInput", "type": "object" }, "SnippetUpdateInput": { "properties": { "identifier": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "A unique, newsletter-scoped slug used to reference the snippet inside email content (e.g. `{{ snippets.footer }}`). Must be unique per newsletter.", "title": "Identifier", "example": "footer" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "A human-readable name for the snippet, shown in the Buttondown UI.", "title": "Name", "example": "Footer" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body of the snippet, substituted wherever the snippet is referenced. Interpreted according to `mode`.", "title": "Content", "example": "Thanks for reading!" }, "mode": { "anyOf": [ { "$ref": "#/components/schemas/SnippetMode" }, { "type": "null" } ], "description": "The editor mode for the snippet, which controls how `content` is rendered: `fancy` (Markdown), `plaintext`, or `naked` (raw HTML with no processing)." } }, "title": "SnippetUpdateInput", "type": "object" }, "CollisionBehavior": { "enum": [ "no_op", "add", "overwrite", "fail" ], "title": "CollisionBehavior", "type": "string", "description": "An enumeration." }, "ErrorMessage_ValidationErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/SubscriberInputValidationErrorCode" } ], "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[SubscriberInput.ValidationErrorCode]", "type": "object" }, "SubscriberInput": { "properties": { "email_address": { "description": "The email address of the subscriber.", "example": "telemachus@buttondown.email", "maxLength": 254, "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$", "title": "Email Address", "type": "string" }, "notes": { "default": "", "description": "Any notes you want to attach to the subscriber. These are not publicly visible.", "example": "One of our first subscribers!", "title": "Notes", "type": "string" }, "metadata": { "additionalProperties": true, "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata", "type": "object" }, "tags": { "default": [], "description": "A list of [tag](https://docs.buttondown.com/api-tags-introduction) names applied to the subscriber. Tags that don't already exist will be created.", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "referrer_url": { "default": "", "description": "The URL the subscriber was referred from (e.g. where they submitted the subscription form).", "title": "Referrer Url", "type": "string" }, "utm_campaign": { "default": "", "description": "The UTM campaign the subscriber was attributed to at signup.", "maxLength": 300, "title": "Utm Campaign", "type": "string" }, "utm_medium": { "default": "", "description": "The UTM medium the subscriber was attributed to at signup.", "maxLength": 300, "title": "Utm Medium", "type": "string" }, "utm_source": { "default": "", "description": "The UTM source the subscriber was attributed to at signup.", "maxLength": 300, "title": "Utm Source", "type": "string" }, "referring_subscriber_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the subscriber that referred this subscriber.", "title": "Referring Subscriber Id" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/SubscriberType" }, { "type": "null" } ], "description": "The subscriber's lifecycle state \u2014 e.g. `regular` (active), `premium` (paid), `unactivated` (pending confirmation), `unsubscribed`, `removed`.", "example": "regular" }, "ip_address": { "anyOf": [ { "pattern": "^[^\\s]+$", "type": "string" }, { "type": "null" } ], "description": "The IP address of the subscriber. If provided, we will use this IP address to determine the subscriber's location and validate their legitimacy.", "example": "127.0.0.1", "title": "Ip Address" } }, "required": [ "email_address" ], "title": "SubscriberInput", "type": "object" }, "ErrorMessage_ListSubscribersErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/ListSubscribersErrorCode" } ], "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[ListSubscribersErrorCode]", "type": "object" }, "ListSubscribersErrorCode": { "description": "Represents the type of error that occurred when listing subscribers.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "invalid_tag", "date_invalid", "invalid_ordering" ], "title": "ListSubscribersErrorCode", "type": "string" }, "ErrorMessage_UpdateSubscriberErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/UpdateSubscriberErrorCode" } ], "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[UpdateSubscriberErrorCode]", "type": "object" }, "UpdateSubscriberErrorCode": { "description": "Represents the type of error that occurred when updating a subscriber.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "email_already_exists", "email_invalid", "email_has_been_changed_too_many_times", "firewall_blocked", "subscriber_type_invalid", "tag_invalid" ], "title": "UpdateSubscriberErrorCode", "type": "string" }, "SubscriberUpdateInput": { "properties": { "commenting_disabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether this subscriber is prevented from commenting.", "title": "Commenting Disabled" }, "email_address": { "anyOf": [ { "maxLength": 254, "pattern": "^[a-zA-Z0-9.'_%+\\-!]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$", "type": "string" }, { "type": "null" } ], "description": "The email address of the subscriber.", "example": "telemachus@buttondown.email", "title": "Email Address" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Any notes you want to attach to the subscriber. These are not publicly visible.", "example": "One of our first subscribers!", "title": "Notes" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": {}, "description": "A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested \u2014 you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))", "title": "Metadata" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "A list of [tag](https://docs.buttondown.com/api-tags-introduction) names applied to the subscriber. Tags that don't already exist will be created.", "title": "Tags" }, "referrer_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "", "description": "The URL the subscriber was referred from (e.g. where they submitted the subscription form).", "title": "Referrer Url" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/SubscriberType" }, { "type": "null" } ], "description": "The subscriber's lifecycle state \u2014 e.g. `regular` (active), `premium` (paid), `unactivated` (pending confirmation), `unsubscribed`, `removed`." }, "unsubscription_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text reason the subscriber unsubscribed, if provided.", "title": "Unsubscription Reason" }, "email_which_prompted_unsubscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the email that prompted the subscriber to unsubscribe, if any.", "title": "Email Which Prompted Unsubscription Id" } }, "title": "SubscriberUpdateInput", "type": "object" }, "AutomationForSubscriber": { "properties": { "id": { "description": "The ID of this automation attempt.", "title": "Id", "type": "string" }, "name": { "description": "The name of the automation that was triggered.", "title": "Name", "type": "string" }, "status": { "$ref": "#/components/schemas/AutomationAttemptStatus", "description": "The status of the automation attempt (e.g. `pending`, `completed`, `skipped`)." }, "automation_id": { "description": "The ID of the automation that was triggered.", "title": "Automation Id", "type": "string" }, "execution_date": { "description": "When the automation attempt is scheduled to execute (or executed).", "format": "date-time", "title": "Execution Date", "type": "string" }, "actions": { "description": "The resolved actions the automation will take for this subscriber.", "items": { "additionalProperties": true, "type": "object" }, "title": "Actions", "type": "array" } }, "required": [ "id", "name", "status", "automation_id", "execution_date", "actions" ], "title": "AutomationForSubscriber", "type": "object" }, "ErrorMessage_UpdateAutomationAttemptErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/UpdateAutomationAttemptErrorCode" } ], "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[UpdateAutomationAttemptErrorCode]", "type": "object" }, "UpdateAutomationAttemptErrorCode": { "description": "Represents the type of error that occurred when updating an automation attempt.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "automation_attempt_not_found", "invalid_status" ], "title": "UpdateAutomationAttemptErrorCode", "type": "string" }, "AutomationAttemptUpdateInput": { "properties": { "status": { "const": "skipped", "description": "The status to set for the automation attempt. Only 'skipped' is allowed.", "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "AutomationAttemptUpdateInput", "type": "object" }, "Response": { "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" }, "answer": { "description": "The answer given to the survey.", "maxLength": 500, "title": "Answer", "type": "string" }, "text": { "description": "Optional text included by the subscriber with the response. Subscribers are only prompted to supply a text response if the `is_freeform_response_enabled` field is set to `true` on the survey.", "title": "Text", "type": "string" }, "survey_id": { "description": "The ID of the survey this response was submitted to.", "title": "Survey Id", "type": "string" }, "subscriber_id": { "description": "The ID of the subscriber who submitted this response.", "title": "Subscriber Id", "type": "string" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the email where this response was submitted, if any.", "title": "Email Id" }, "automation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ID of the automation where this response was submitted, if any.", "title": "Automation Id" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For responses not tied to an email or automation, the origin the survey was answered from (e.g. a `transactional:*` template). Null otherwise.", "title": "Source" }, "subscriber": { "anyOf": [ { "$ref": "#/components/schemas/Subscriber" }, { "type": "null" } ] }, "survey": { "anyOf": [ { "$ref": "#/components/schemas/Survey" }, { "type": "null" } ] }, "email": { "anyOf": [ { "$ref": "#/components/schemas/Email" }, { "type": "null" } ] }, "automation": { "anyOf": [ { "$ref": "#/components/schemas/Automation" }, { "type": "null" } ] } }, "required": [ "id", "creation_date", "answer", "text", "survey_id", "subscriber_id" ], "title": "Response", "type": "object" }, "Survey": { "description": "Surveys let you ask your subscribers a question\u2014and personalize future\nemails based on their answers. You can attach a survey to any email and read\nback the responses via the API.", "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" }, "identifier": { "description": "A newsletter-scoped slug used to reference this survey when embedding it in emails.", "maxLength": 100, "title": "Identifier", "type": "string" }, "question": { "description": "The survey question shown to subscribers.", "maxLength": 500, "title": "Question", "type": "string" }, "response_count": { "description": "The total number of responses this survey has received.", "minimum": 0, "title": "Response Count", "type": "integer" }, "answers": { "description": "The list of pre-defined answer choices. Order is preserved unless `randomize_answers` is true.", "items": { "maxLength": 500, "type": "string" }, "title": "Answers", "type": "array" }, "notes": { "description": "Internal notes about the survey. Not shown to subscribers.", "title": "Notes", "type": "string" }, "randomize_answers": { "description": "If true, the order of `answers` is shuffled each time the survey is rendered.", "title": "Randomize Answers", "type": "boolean" }, "response_cadence": { "$ref": "#/components/schemas/SurveyResponseCadence", "description": "How often a given subscriber can respond \u2014 e.g. `once` (single response per subscriber) or `unlimited`." }, "status": { "$ref": "#/components/schemas/SurveyStatus", "description": "The lifecycle status of the survey (e.g. `active`, `archived`)." }, "is_freeform_response_enabled": { "description": "If true, subscribers can provide a freeform text response in addition to (or instead of) picking from `answers`.", "title": "Is Freeform Response Enabled", "type": "boolean" }, "input_type": { "$ref": "#/components/schemas/SurveyInputType", "description": "The UI control used to collect responses (e.g. `radio`, `checkbox`)." } }, "required": [ "id", "creation_date", "identifier", "question", "response_count", "answers", "notes", "randomize_answers", "response_cadence", "status", "is_freeform_response_enabled", "input_type" ], "title": "Survey", "type": "object" }, "CreateSurveyResponseErrorCode": { "enum": [ "invalid_input" ], "title": "CreateSurveyResponseErrorCode", "type": "string", "description": "An enumeration." }, "ErrorMessage_CreateSurveyResponseErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreateSurveyResponseErrorCode" } ], "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[CreateSurveyResponseErrorCode]", "type": "object" }, "ResponseInput": { "additionalProperties": false, "properties": { "subscriber_id": { "description": "The subscriber who submitted the response.", "example": [ "sub_01jv2m9q8r7s6t5w4x3y2z1abc" ], "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "title": "Subscriber Id", "type": "string" }, "survey_id": { "description": "The survey being answered.", "example": [ "srv_01jv2m9q8r7s6t5w4x3y2z1abc" ], "maxLength": 50, "pattern": "^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:srv)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$", "title": "Survey Id", "type": "string" }, "email_id": { "description": "The email ID, automation ID, or arbitrary source string where the survey was answered.", "example": "em_01jv2m9q8r7s6t5w4x3y2z1abc", "maxLength": 100, "minLength": 1, "title": "Email Id", "type": "string" }, "answer": { "description": "The 1-based index of the selected answer in the survey's `answers` list.", "example": 1, "minimum": 1, "title": "Answer", "type": "integer" } }, "required": [ "subscriber_id", "survey_id", "email_id", "answer" ], "title": "ResponseInput", "type": "object" }, "ResponseUpdateInput": { "additionalProperties": false, "properties": { "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The text response to update. Only applicable if the survey has freeform responses enabled.", "title": "Text" } }, "title": "ResponseUpdateInput", "type": "object" }, "CreateSurveyErrorCode": { "description": "Represents the type of error that occurred when creating a survey.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "identifier_already_exists" ], "title": "CreateSurveyErrorCode", "type": "string" }, "ErrorMessage_CreateSurveyErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/CreateSurveyErrorCode" } ], "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[CreateSurveyErrorCode]", "type": "object" }, "SurveyInput": { "additionalProperties": false, "properties": { "identifier": { "description": "A newsletter-scoped slug used to reference this survey when embedding it in emails.", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9]+$", "title": "Identifier", "type": "string", "example": "color" }, "question": { "description": "The survey question shown to subscribers.", "maxLength": 500, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "title": "Question", "type": "string", "example": "What's your favorite color?" }, "answers": { "description": "The list of pre-defined answer choices. Order is preserved unless `randomize_answers` is true.", "items": { "maxLength": 500, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "type": "string" }, "minItems": 2, "title": "Answers", "type": "array", "example": [ "Red", "Green", "Blue" ] }, "notes": { "default": "", "description": "Internal notes about the survey. Not shown to subscribers.", "title": "Notes", "type": "string", "example": "" }, "response_cadence": { "allOf": [ { "$ref": "#/components/schemas/SurveyResponseCadence" } ], "default": "once", "description": "How often a given subscriber can respond \u2014 e.g. `once` (single response per subscriber) or `unlimited`.", "example": "once" }, "is_freeform_response_enabled": { "default": false, "description": "If true, subscribers can provide a freeform text response in addition to (or instead of) picking from `answers`.", "title": "Is Freeform Response Enabled", "type": "boolean", "example": false }, "input_type": { "allOf": [ { "$ref": "#/components/schemas/SurveyInputType" } ], "default": "radio", "description": "The UI control used to collect responses (e.g. `radio`, `checkbox`).", "example": "radio" }, "randomize_answers": { "default": false, "description": "If true, the order of `answers` is shuffled each time the survey is rendered.", "title": "Randomize Answers", "type": "boolean", "example": false } }, "required": [ "identifier", "question", "answers" ], "title": "SurveyInput", "type": "object" }, "ErrorMessage_UpdateSurveyErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/UpdateSurveyErrorCode" } ], "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[UpdateSurveyErrorCode]", "type": "object" }, "UpdateSurveyErrorCode": { "enum": [ "survey_has_responses" ], "title": "UpdateSurveyErrorCode", "type": "string", "description": "An enumeration." }, "SurveyUpdateInput": { "additionalProperties": false, "properties": { "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal notes about the survey. Not shown to subscribers.", "title": "Notes" }, "answers": { "anyOf": [ { "items": { "maxLength": 500, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "type": "string" }, "minItems": 2, "type": "array" }, { "type": "null" } ], "description": "The list of pre-defined answer choices. Order is preserved unless `randomize_answers` is true.", "title": "Answers", "example": [ "Red", "Green", "Blue" ] }, "response_cadence": { "anyOf": [ { "$ref": "#/components/schemas/SurveyResponseCadence" }, { "type": "null" } ], "description": "How often a given subscriber can respond \u2014 e.g. `once` (single response per subscriber) or `unlimited`.", "example": "once" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/SurveyStatus" }, { "type": "null" } ], "description": "The lifecycle status of the survey (e.g. `active`, `archived`)." }, "is_freeform_response_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "If true, subscribers can provide a freeform text response in addition to (or instead of) picking from `answers`.", "title": "Is Freeform Response Enabled" }, "input_type": { "anyOf": [ { "$ref": "#/components/schemas/SurveyInputType" }, { "type": "null" } ], "description": "The UI control used to collect responses (e.g. `radio`, `checkbox`)." }, "randomize_answers": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "If true, the order of `answers` is shuffled each time the survey is rendered.", "title": "Randomize Answers" } }, "title": "SurveyUpdateInput", "type": "object" }, "Tag": { "description": "Tags are a way to organize your subscribers. You can create, update, and\ndelete tags via the API. You can also list all tags for a given newsletter.\n\nTags don't have any strict functionality on their own, but you can send emails\nto subscribers with a given tag (or to all subscribers _without_ a given tag.)", "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": "The name of the tag.", "title": "Name", "type": "string" }, "color": { "description": "The hex color code associated with the tag.", "title": "Color", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An internal description of the tag, only visible to the newsletter author.", "title": "Description" }, "public_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A public-facing description of the tag, visible to subscribers in the subscriber portal.", "title": "Public Description" }, "subscriber_editable": { "description": "If true, subscribers can add or remove this tag from their own profile via the subscriber portal.", "title": "Subscriber Editable", "type": "boolean" }, "secondary_id": { "description": "The secondary ID of the tag, used as a human-readable numeric identifier.", "maximum": 1000000000, "minimum": 1, "title": "Secondary Id", "type": "integer" } }, "required": [ "id", "creation_date", "name", "color", "subscriber_editable", "secondary_id" ], "title": "Tag", "type": "object" }, "ErrorMessage_TagErrorCode_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/TagErrorCode" } ], "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[TagErrorCode]", "type": "object" }, "TagErrorCode": { "description": "Error codes returned when creating or updating a tag fails.", "enum": [ "feature_disabled", "name_already_exists", "name_blank", "name_invalid", "name_too_long" ], "title": "TagErrorCode", "type": "string" }, "TagInput": { "additionalProperties": false, "description": "Input schema for creating a new tag.", "properties": { "name": { "description": "The name of the tag.", "maxLength": 100, "minLength": 1, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "title": "Name", "type": "string", "example": "VIP" }, "color": { "description": "The hex color code associated with the tag.", "maxLength": 7, "minLength": 4, "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "title": "Color", "type": "string", "example": "#FFD700" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An internal description of the tag, only visible to the newsletter author.", "title": "Description" }, "public_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A public-facing description of the tag, visible to subscribers in the subscriber portal.", "title": "Public Description" }, "subscriber_editable": { "default": false, "description": "If true, subscribers can add or remove this tag from their own profile via the subscriber portal.", "title": "Subscriber Editable", "type": "boolean", "example": false } }, "required": [ "name", "color" ], "title": "TagInput", "type": "object" }, "TagUpdateInput": { "additionalProperties": false, "description": "Input schema for updating an existing tag. All fields are optional.", "properties": { "name": { "anyOf": [ { "maxLength": 100, "minLength": 1, "pattern": "^[ -~]*[A-Za-z0-9][ -~]*$", "type": "string" }, { "type": "null" } ], "description": "The name of the tag.", "title": "Name", "example": "VIP" }, "color": { "anyOf": [ { "maxLength": 7, "minLength": 4, "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "type": "string" }, { "type": "null" } ], "description": "The hex color code associated with the tag.", "title": "Color", "example": "#FFD700" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "An internal description of the tag, only visible to the newsletter author.", "title": "Description" }, "public_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A public-facing description of the tag, visible to subscribers in the subscriber portal.", "title": "Public Description" }, "secondary_id": { "anyOf": [ { "maximum": 1000000000, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "The secondary ID of the tag, used as a human-readable numeric identifier.", "title": "Secondary Id" }, "subscriber_editable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "If true, subscribers can add or remove this tag from their own profile via the subscriber portal.", "title": "Subscriber Editable" } }, "title": "TagUpdateInput", "type": "object" }, "TagAnalytics": { "description": "Analytics data associated with a given tag.", "properties": { "created_subscribers": { "description": "The number of subscribers who have been created with this tag.", "minimum": 0, "title": "Created Subscribers", "type": "integer" }, "click_rate": { "description": "The click rate of emails sent to subscribers with this tag.", "title": "Click Rate", "type": "number" }, "open_rate": { "description": "The open rate of emails sent to subscribers with this tag.", "title": "Open Rate", "type": "number" } }, "required": [ "created_subscribers", "click_rate", "open_rate" ], "title": "TagAnalytics", "type": "object" }, "ErrorMessage_Failure_": { "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/Failure" } ], "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[Failure]", "type": "object" }, "Failure": { "enum": [ "email_already_exists" ], "title": "Failure", "type": "string", "description": "An enumeration." }, "UserInput": { "properties": { "permissions": { "$ref": "#/components/schemas/Permissions" }, "email_address": { "description": "The email address of the user.", "title": "Email Address", "type": "string" } }, "required": [ "permissions", "email_address" ], "title": "UserInput", "type": "object" }, "UserUpdateInput": { "properties": { "permissions": { "$ref": "#/components/schemas/Permissions" } }, "required": [ "permissions" ], "title": "UserUpdateInput", "type": "object" }, "Webhook": { "description": "Webhooks are used to notify external services of events that occur in the\nsystem. For example, when a newsletter is sent, a webhook can be used to\nnotify an external service that the newsletter has been sent.", "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" }, "status": { "allOf": [ { "$ref": "#/components/schemas/WebhookStatus" } ], "default": "enabled", "description": "Whether the webhook is enabled or not.", "example": "enabled" }, "event_types": { "description": "The types of event for which the webhook will be triggered.", "example": [ "email.created", "email.sent" ], "items": { "$ref": "#/components/schemas/ExternalEventType" }, "title": "Event Types", "type": "array" }, "url": { "description": "The URL to which the webhook will send POST requests.", "example": "https://my.api/webhook", "format": "uri", "minLength": 1, "title": "Url", "type": "string" }, "description": { "default": "", "description": "An optional description of the webhook, for reference.", "example": "Trigger when an email is created to notify in Slack.", "title": "Description", "type": "string" }, "signing_key": { "default": "", "description": "Optional HMAC signing key for webhook verification. When set, webhook requests will include an X-Buttondown-Signature header with sha256=.", "example": "", "title": "Signing Key", "type": "string" } }, "required": [ "id", "creation_date", "event_types", "url" ], "title": "Webhook", "type": "object" }, "WebhookStatus": { "description": "The status of a webhook.", "enum": [ "enabled", "disabled" ], "title": "WebhookStatus", "type": "string" }, "WebhookInput": { "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/WebhookStatus" } ], "default": "enabled", "description": "Whether the webhook is enabled or not.", "example": "enabled" }, "event_types": { "description": "The types of event for which the webhook will be triggered.", "example": [ "email.created", "email.sent" ], "items": { "$ref": "#/components/schemas/ExternalEventType" }, "title": "Event Types", "type": "array" }, "url": { "description": "The URL to which the webhook will send POST requests.", "example": "https://my.api/webhook", "format": "uri", "minLength": 1, "title": "Url", "type": "string" }, "description": { "default": "", "description": "An optional description of the webhook, for reference.", "example": "Trigger when an email is created to notify in Slack.", "title": "Description", "type": "string" }, "signing_key": { "default": "", "description": "Optional HMAC signing key for webhook verification. When set, webhook requests will include an X-Buttondown-Signature header with sha256=.", "example": "", "title": "Signing Key", "type": "string" } }, "required": [ "event_types", "url" ], "title": "WebhookInput", "type": "object" }, "WebhookAttemptStatus": { "enum": [ "unattempted", "successful", "failed" ], "title": "WebhookAttemptStatus", "type": "string", "description": "An enumeration." }, "WebhookAttemptOutput": { "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" }, "status": { "description": "The status of the webhook attempt.", "example": "successful", "title": "Status", "type": "string" }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The type of the event that triggered the attempt.", "example": "subscriber.created", "title": "Event Type" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The failure reason, if the attempt failed. Includes the response status code and a snippet of the response body when the endpoint returned a non-2xx response.", "example": "WebhookFailedError: Webhook returned 401: invalid signature", "title": "Error Message" }, "attempt_count": { "default": 0, "description": "The number of times this attempt has been retried.", "example": 1, "title": "Attempt Count", "type": "integer" }, "completion_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the attempt finished, if it has.", "example": "2026-04-27T05:25:19.819Z", "title": "Completion Date" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "How long the HTTP request took, in milliseconds.", "example": 412, "title": "Duration Ms" } }, "required": [ "id", "creation_date", "status" ], "title": "WebhookAttemptOutput", "type": "object" }, "EmailExcludableField": { "description": "Represents a field on the Email model that can be excluded from\nthe API response.", "enum": [ "body" ], "title": "ExcludableField", "type": "string" }, "AdvertisingSKUStatus": { "enum": [ "active", "inactive" ], "title": "Status", "type": "string", "description": "An enumeration." }, "AdvertisingSlotStatus": { "enum": [ "expired", "executed", "finalized", "held", "open", "sold" ], "title": "Status", "type": "string", "description": "An enumeration." }, "CommentStatus": { "enum": [ "pending", "active", "spammy" ], "title": "Status", "type": "string", "description": "An enumeration." }, "EmailSource": { "description": "Represents the original provenance of an email. This value is not exposed\nto subscribers, but does determine some behavior of the email (e.g. whether\nor not analytics can be calculated.)", "enum": [ "api", "import", "app", "external_feed" ], "title": "Source", "type": "string" }, "EmailStatus": { "description": "Represents the state of an email.\n\nNo action is required to move from one state or another; Buttondown\ninternally handles the transitions, and exposing the status is for\nobservability purposes only.", "enum": [ "draft", "managed_by_rss", "about_to_send", "scheduled", "in_flight", "paused", "deleted", "errored", "sent", "imported", "throttled", "resending", "transactional", "suppressed" ], "title": "Status", "type": "string" }, "EmailType": { "description": "Represents the audience of an email, and to whom it is visible both in the initial\nemail and in online archives.", "enum": [ "public", "private", "premium", "free", "churned", "archival" ], "title": "Type", "type": "string" }, "SubscriberSource": { "description": "Represents the original provenance of a subscriber. This value is not exposed\nto subscribers; it's only used for internal tracking purposes and governs some\nof the behavior of the subscriber (i.e. whether or not to require double\nopt-in.)", "enum": [ "admin", "api", "carrd", "comment", "embedded_form", "form", "import", "memberful", "netlify", "organic", "patreon", "stripe", "user", "zapier" ], "title": "Source", "type": "string" }, "SubscriberType": { "description": "Represents the state of a subscriber and what emails they\nshould or should not be receiving. This type is meant to be fully expressive\nso as to consolidate the logic of determining what emails a subscriber should\nreceive into a single place.\n\nNote that the only types that can be set programmatically are REGULAR, UNSUBSCRIBED,\nGIFTED and UNPAID. All other types are meant to be user-visible and cannot\nbe set programmatically.", "enum": [ "blocked", "complained", "churning", "churned", "gifted", "unactivated", "unpaid", "undeliverable", "premium", "past_due", "paused", "regular", "removed", "trialed", "unsubscribed", "upcoming" ], "title": "Type", "type": "string" }, "AutomationStatus": { "enum": [ "active", "inactive" ], "title": "Status", "type": "string", "description": "An enumeration." }, "ExternalEventType": { "description": "Various types of events that are recorded by Buttondown, both in terms of exogenous systems\nlike Stripe and Memberful, and endogenous ones like email opens and clicks. (In general, if anything\nimportant ever happens that could be relevant to your newsletter, we have an event type for it!)\n\nThese event types power lots of things within Buttondown. They're used to trigger automations, webhooks,\nand analytics.\n\n(Note that Buttondown also has a different thing we call \"events\"; those are `EmailEvents` and are used\nfor tracking aggregate details about an email. Alas, we shouldn't have used the term \"event\" for two different\nthings, but it's too late to go back now!)\n\nIn general, our event namespacing tries to hew to the following pattern:\n\n`..`\n\nWhen wondering which object we are referring to, default to the _more granular_ object.\n\nFor instance, an email being sent to a subscriber is `subscriber.delivered`, not `email.sent`.", "enum": [ "advertising_slot.inquiry", "advertising_slot.purchased", "automation.invoked", "date.day.started", "date.month.started", "date.week.started", "date.year.started", "bigcommerce.customer.created", "bigcommerce.customer.updated", "bigcommerce.order.created", "bigcommerce.order.updated", "email.created", "email.deleted", "email.sent", "email.status.changed", "email.updated", "external_feed_item.created", "export.completed", "export.created", "export.failed", "firewall.blocked", "mention.created", "memberful.member.updated", "memberful.subscription.created", "memberful.subscription.deleted", "note.created", "note.deleted", "patreon.member.updated", "patreon.membership.created", "patreon.membership.deleted", "shopify.customer.created", "shopify.customer.updated", "social_mention.created", "stripe.checkout.session.completed", "stripe.customer.updated", "stripe.subscription.activated", "stripe.subscription.churning", "stripe.subscription.deactivated", "subscriber.bounced", "subscriber.changed_email", "subscriber.churned", "subscriber.clicked", "subscriber.commented", "subscriber.complained", "subscriber.confirmed", "subscriber.created", "subscriber.deleted", "subscriber.delivered", "subscriber.opened", "subscriber.paid", "subscriber.paused", "subscriber.resumed", "subscriber.referred", "subscriber.referred.paid", "subscriber.rejected", "subscriber.replied", "subscriber.responded_to_survey", "subscriber.tags.changed", "subscriber.trial_ended", "subscriber.trial_started", "subscriber.type.changed", "subscriber.unsubscribed", "subscriber.updated", "subscriber.viewed_checkout_page", "survey.cleared_responses", "survey.created", "survey.deleted", "survey.updated", "form.created", "form.deleted", "form.updated" ], "title": "Type", "type": "string" }, "ExternalFeedItemStatus": { "description": "The status of a given item (meaning a distinct URL) within an RSS feed.", "enum": [ "unprocessed", "irrelevant", "errored", "skipped", "queued", "processed" ], "title": "Status", "type": "string" }, "SurveyStatus": { "enum": [ "active", "inactive" ], "title": "Status", "type": "string", "description": "An enumeration." }, "AutomationActionType": { "description": "The action that is triggered when the automation is successfully run.", "enum": [ "add_tags", "remove_tags", "send_email", "add_metadata", "change_email_address", "gift_premium_subscription", "ungift_premium_subscription", "send_discord_invitation", "send_github_invitation", "create_subscriber", "unsubscribe_subscriber", "shopify_unsubscribe", "shopify_resubscribe", "shopify_set_tags", "shopify_create_customer", "send_notification", "forward_reply", "create_arena_post", "create_bluesky_post", "create_linkedin_post", "create_mastodon_post", "create_tumblr_post", "create_twitter_post", "create_export", "create_gift_subscriber", "send_post_request", "send_confirmation_reminder", "update_email_type" ], "title": "ActionType", "type": "string" }, "NewsletterAnnouncementBarVisibility": { "enum": [ "disabled", "everyone", "free_only", "logged_out_only", "paid_only" ], "title": "AnnouncementBarVisibility", "type": "string", "description": "An enumeration." }, "NewsletterArchiveTheme": { "enum": [ "classic", "modern", "arbus", "lovelace", "myrna" ], "title": "ArchiveTheme", "type": "string", "description": "An enumeration." }, "NewsletterAuditingMode": { "enum": [ "disabled", "enabled", "aggressive" ], "title": "AuditingMode", "type": "string", "description": "An enumeration." }, "ExternalFeedAutomationBehavior": { "enum": [ "draft", "emails" ], "title": "Behavior", "type": "string", "description": "An enumeration." }, "ExternalFeedAutomationCadence": { "enum": [ "every", "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string", "description": "An enumeration." }, "ExportCollection": { "description": "A group of data that can be exported in an export.", "enum": [ "subscribers", "emails", "events", "referrals", "surveys", "comments", "requests", "mentions", "conversations", "images", "stripe_subscriptions", "stripe_products", "stripe_customers", "stripe_prices", "stripe_charges" ], "title": "Collection", "type": "string" }, "EmailCommentingMode": { "description": "Governs who can comment on this email.\n\nThis enum replaces the `is_comments_disabled` field, which has been deprecated. (Also note that this field may be superseded by newsletter-level settings; for instance, \"enabled\" is an invalid and inert value if the newsletter itself has comments disabled.)", "enum": [ "disabled", "enabled", "enabled_for_paid_subscribers" ], "title": "CommentingMode", "type": "string" }, "NewsletterEmailTemplate": { "description": "Represents the template of an email.\n\nEach template has a different layout/style; you can view screenshots and examples [in the docs](https://docs.buttondown.com/customizing-email-design#buttondowns-default-templates).", "enum": [ "classic", "modern", "plaintext", "naked" ], "title": "EmailTemplate", "type": "string" }, "ExportFormat": { "enum": [ "csv", "json" ], "title": "Format", "type": "string", "description": "An enumeration." }, "SurveyInputType": { "enum": [ "radio", "checkbox", "text" ], "title": "InputType", "type": "string", "description": "An enumeration." }, "NewsletterLocale": { "enum": [ "cs-CZ", "nl-NL", "en-AU", "en-CA", "en-GB", "en", "et", "fr", "de", "ne", "nb-NO", "pl-PL", "pt-BR", "pt-PT", "ru", "es", "tr", "sv-SE" ], "title": "Locale", "type": "string", "description": "An enumeration." }, "SnippetMode": { "enum": [ "fancy", "naked", "plaintext" ], "title": "Mode", "type": "string", "description": "An enumeration." }, "SurveyResponseCadence": { "enum": [ "once", "once_per_email" ], "title": "ResponseCadence", "type": "string", "description": "An enumeration." }, "EmailSuppressionReason": { "description": "Represents the reason an email was suppressed.", "enum": [ "law_enforcement", "internal_auditing" ], "title": "SuppressionReason", "type": "string" }, "SubscriberUndeliverabilityReason": { "description": "The reason Buttondown has marked the subscriber as undeliverable.\nUndeliverable subscribers are not sent emails, and may be periodically removed from the system (or restored, if the reason is no longer valid.)\n\nThese reasons are grouped into three categories:\n- PermanentFailure (\"Failed (recipient)\"): Address-based issues where the recipient is truly unreachable.\n Includes: HARD_BOUNCE\n- MessageFailure (\"Failed (message)\"): Message/sender problems where future emails may succeed.\n Includes: ACCESS_DENIED, AUTHENTICATION_ISSUE, DELIVERY_EXPIRED, DOMAIN_BLOCKED, EMAIL_BLOCKED,\n IP_BLOCKED, ON_ESP_DENYLIST, OUT_OF_STORAGE, PROBLEMATIC_URL, SPAM\n- Deferral (not shown to customers): Transient delivery issues that will be retried.\n Includes: RATE_LIMITED, TRANSIENT", "enum": [ "access_denied", "authentication_issue", "delivery_expired", "domain_blocked", "email_blocked", "hard_bounce", "ip_blocked", "ip_undeliverable", "malformed", "on_esp_denylist", "other", "out_of_storage", "problematic_url", "rate_limited", "spam", "transient", "disabled", "does_not_exist", "spf_failed", "unreachable" ], "title": "UndeliverabilityReason", "type": "string" }, "AdvertisingUnitPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/AdvertisingUnit" }, "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[AdvertisingUnit]", "type": "object" }, "AdvertisingSlotPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/AdvertisingSlot" }, "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[AdvertisingSlot]", "type": "object" }, "AttachmentPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Attachment" }, "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[Attachment]", "type": "object" }, "AutomationPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Automation" }, "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[Automation]", "type": "object" }, "BookPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Book" }, "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[Book]", "type": "object" }, "CommentPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Comment" }, "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[Comment]", "type": "object" }, "StripeCouponPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/StripeCoupon" }, "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[StripeCoupon]", "type": "object" }, "EmailPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Email" }, "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[Email]", "type": "object" }, "HistoryPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/History" }, "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[History]", "type": "object" }, "EmailEventPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/EmailEvent" }, "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[EmailEvent]", "type": "object" }, "ExportPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Export" }, "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[Export]", "type": "object" }, "ExternalFeedPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/ExternalFeed" }, "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[ExternalFeed]", "type": "object" }, "ExternalFeedItemPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/ExternalFeedItem" }, "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[ExternalFeedItem]", "type": "object" }, "FormPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Form" }, "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[Form]", "type": "object" }, "ImagePage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Image" }, "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[Image]", "type": "object" }, "ImportPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Import" }, "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[Import]", "type": "object" }, "NewsletterPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Newsletter" }, "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[Newsletter]", "type": "object" }, "NotePage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Note" }, "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[Note]", "type": "object" }, "PricePage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Price" }, "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[Price]", "type": "object" }, "PublicEmailPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/PublicEmail" }, "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[PublicEmail]", "type": "object" }, "SnippetPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Snippet" }, "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[Snippet]", "type": "object" }, "SubscriberPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Subscriber" }, "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[Subscriber]", "type": "object" }, "AutomationForSubscriberPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/AutomationForSubscriber" }, "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[AutomationForSubscriber]", "type": "object" }, "StripeSubscriptionPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/StripeSubscription" }, "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[UnexpandableStripeSubscription]", "type": "object" }, "ResponsePage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Response" }, "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[Response]", "type": "object" }, "SurveyPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Survey" }, "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[Survey]", "type": "object" }, "TagPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Tag" }, "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[Tag]", "type": "object" }, "UserPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/User" }, "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[User]", "type": "object" }, "WebhookPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/Webhook" }, "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[Webhook]", "type": "object" }, "WebhookAttemptOutputPage": { "properties": { "results": { "description": "The list of results for this page.", "items": { "$ref": "#/components/schemas/WebhookAttemptOutput" }, "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[WebhookAttemptOutput]", "type": "object" }, "StripeSubscription": { "properties": { "subscription_id": { "description": "The Stripe subscription ID (e.g. `sub_...`).", "title": "Subscription Id", "type": "string" }, "url": { "description": "A deep link to the subscription in the Stripe dashboard.", "title": "Url", "type": "string" }, "creation_date": { "description": "The date and time at which the object was first created.", "format": "date-time", "title": "Creation Date", "type": "string" }, "ending_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the subscription ended, or null if still active.", "title": "Ending Date" }, "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The subscription amount in the smallest currency unit (e.g. cents). Null for tiered-pricing plans.", "title": "Amount" }, "currency": { "description": "The three-letter ISO currency code (e.g. `usd`).", "title": "Currency", "type": "string" }, "cadence": { "description": "The billing cadence (e.g. `month`, `year`).", "title": "Cadence", "type": "string" }, "status": { "description": "The Stripe subscription status (e.g. `active`, `canceled`, `past_due`).", "title": "Status", "type": "string" }, "application_fee_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The application fee percent for the subscription.", "title": "Application Fee Percent" }, "source": { "anyOf": [ { "enum": [ "substack", "buttondown" ], "type": "string" }, { "type": "null" } ], "description": "Buttondown attempts to detect the source of a subscription, but this is not always possible.", "title": "Source" }, "product": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the product which the subscriber is subscribed to. (You can override this by setting the `buttondown_template_facing_id` metadata on the product in Stripe.)", "title": "Product" } }, "required": [ "subscription_id", "url", "creation_date", "currency", "cadence", "status" ], "title": "StripeSubscription", "type": "object" }, "SubscriberInputValidationErrorCode": { "description": "Represents the type of error that occurred when validating subscriber input.\n\nHuman-readable error messages are provided in the `detail` field of the response;\nthese values are meant to be parseable by code or client logic.", "enum": [ "email_already_exists", "email_blocked", "email_empty", "email_invalid", "ip_address_spammy", "metadata_invalid", "rate_limited", "subscriber_already_exists", "subscriber_blocked", "subscriber_id_invalid", "subscriber_suppressed", "tag_invalid" ], "title": "ValidationErrorCode", "type": "string" }, "APIRequestSource": { "type": "string", "enum": [ "api", "app", "axios", "carrd", "cli", "curl", "go", "make", "netlify", "node", "pipedream", "powershell", "python", "ruby", "wordpress", "zapier" ], "title": "APIRequestSource", "description": "An enumeration." }, "AutomationAttemptStatus": { "type": "string", "enum": [ "unprocessed", "processed", "failed", "pending", "skipped" ], "title": "AutomationAttemptStatus", "description": "An enumeration." }, "BulkActionStatus": { "type": "string", "enum": [ "not_started", "in_progress", "processed", "failed" ], "title": "BulkActionStatus", "description": "Represents the status of a bulk action.\n\nNo action is required to move from one state or another; Buttondown\ninternally handles the transitions, and exposing the status is for\nobservability purposes only." }, "BulkActionType": { "type": "string", "enum": [ "add_notes", "apply_tags", "apply_metadata", "rename_metadata", "ban_subscribers", "delete_subscribers", "gift_subscribers", "ungift_subscribers", "reactivate_subscribers", "mark_subscribers_as_not_spammy", "resubscribe_subscribers", "send_emails", "unban_subscribers", "send_reminders", "unsubscribe_subscribers", "delete_attachments", "delete_emails", "delete_images", "update_email_types", "update_archival_modes", "update_commenting_modes", "mark_inbox_items_read", "delete_inbox_items", "change_tags_colors", "delete_comments", "delete_surveys", "delete_survey_responses", "delete_tags", "mark_comments_as_active", "mark_comments_as_spammy", "replay_events", "update_survey_statuses", "cancel_stripe_subscriptions", "modify_stripe_subscriptions", "pause_stripe_subscriptions" ], "title": "BulkActionType", "description": "Represents the action being performed on a bulk of objects.\n\n(Not to be coy, but these names should be self-explanatory.)" }, "ExportStatus": { "type": "string", "enum": [ "error", "in_progress", "not_started", "ready" ], "title": "ExportStatus", "description": "Represents the status of an export.\n\nNo action is required to move from one state or another; Buttondown\ninternally handles the transitions, and exposing the status is for\nobservability purposes only." }, "ExternalFeedAutomationStatus": { "type": "string", "enum": [ "active", "failing", "inactive", "deleted" ], "title": "ExternalFeedAutomationStatus", "description": "Represents the status of the automation, and whether or not it is active. Inactive automations will not be processed. Deleted automations will not be processed." }, "FormStatus": { "type": "string", "enum": [ "active", "inactive" ], "title": "FormStatus", "description": "An enumeration." }, "InvitationStatus": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "owner" ], "title": "InvitationStatus", "description": "An enumeration." } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key passed as 'Token ' in the Authorization header." } } }, "servers": [ { "url": "https://api.buttondown.com/v1" } ] }