{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/publications/{publicationId}/advertisement_opportunities":{"get":{"operationId":"index","summary":"Get advertisement opportunities <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:read</Badge>","description":"Retrieve a list of accepted advertisement opportunities for the publication.","tags":["subpackage_advertisement_opportunities"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_advertisement_opportunities:AdvertisementOpportunitiesGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/authors":{"get":{"operationId":"index","summary":"List authors","description":"Retrieve a list of authors available for the publication.","tags":["subpackage_authors"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"name","in":"query","description":"Optionally filter authors by full name or first name (case-insensitive).","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_authors:AuthorsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/authors/{authorId}":{"get":{"operationId":"show","summary":"Get author","description":"Retrieve a single author from a publication.","tags":["subpackage_authors"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"authorId","in":"path","description":"The author identifier. This accepts author UUID, full name, or first name.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_authors:AuthorsGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/automations/{automationId}/journeys":{"post":{"operationId":"create","summary":"Add subscription to an automation <Badge intent=\"info\" minimal outlined>OAuth Scope: automations:write</Badge>","description":"Add an existing subscription to an automation flow. Requires the automation to have an active *Add by API* trigger. The specified `email` or `subscription_id` will be matched against your existing subscribers. If an existing subscriber is found, they will be enrolled immediately.\nLooking to enroll new subscribers? Use the **[Create Subscription](/api-reference/subscriptions/create)** endpoint instead and specify the `automation_ids` param.","tags":["subpackage_automationJourneys"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"automationId","in":"path","description":"The prefixed ID of the automation object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:AutomationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_automationJourneys:AutomationJourneysResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The email address associated with the subscription."},"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId"},"double_opt_override":{"$ref":"#/components/schemas/type_:DoubleOptOverride","description":"Override the publication's default double opt-in settings for this subscription. Possible values are:\n- \"on\" — The subscriber will receive a double opt-in confirmation email and will need to confirm their subscription prior to being marked as active.\n- \"off\" — The subscriber will be marked as active immediately and will not receive a double opt-in confirmation email.\n- \"not_set\" — The publication's default double opt-in settings will be applied to this subscription."}}}}}}},"get":{"operationId":"index","summary":"List automation journeys <Badge intent=\"info\" minimal outlined>OAuth Scope: automations:read</Badge>","description":"Retrieve a list of automation journeys that have occurred within a specific automation.","tags":["subpackage_automationJourneys"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"automationId","in":"path","description":"The prefixed ID of the automation object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:AutomationId"}},{"name":"status","in":"query","description":"Optionally filter the results by the automation journey's status.","required":false,"schema":{"$ref":"#/components/schemas/type_automationJourneys:AutomationJourneysGetRequestStatus"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_automationJourneys:AutomationJourneysIndexResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/automations/{automationId}/journeys/{automationJourneyId}":{"get":{"operationId":"show","summary":"Get automation journey <Badge intent=\"info\" minimal outlined>OAuth Scope: automations:read</Badge>","description":"Retrieve a single automation journey by ID.","tags":["subpackage_automationJourneys"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"automationId","in":"path","description":"The prefixed ID of the automation object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:AutomationId"}},{"name":"automationJourneyId","in":"path","description":"The prefixed automation journey id","required":true,"schema":{"$ref":"#/components/schemas/type_ids:AutomationJourneyId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_automationJourneys:AutomationJourneysResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/automations":{"get":{"operationId":"index","summary":"List automations <Badge intent=\"info\" minimal outlined>OAuth Scope: automations:read</Badge>","description":"Retrieve automations for a publication.","tags":["subpackage_automations"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.","required":false,"schema":{"$ref":"#/components/schemas/type_automations:AutomationsListRequestExpandItem"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_automations:AutomationsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/automations/{automationId}":{"get":{"operationId":"show","summary":"Get automation <Badge intent=\"info\" minimal outlined>OAuth Scope: automations:read</Badge>","description":"Retrieve a single automation for a publication.","tags":["subpackage_automations"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"automationId","in":"path","description":"The prefixed ID of the automation object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:AutomationId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.","required":false,"schema":{"$ref":"#/components/schemas/type_automations:AutomationsGetRequestExpandItem"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_automations:AutomationsGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/automations/{automationId}/emails":{"get":{"operationId":"list-emails","summary":"List automation emails","description":"Retrieve all emails belonging to a specific automation, including engagement statistics for each email.","tags":["subpackage_automations"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"automationId","in":"path","description":"The prefixed ID of the automation object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:AutomationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. Obtain it from the `next_cursor` field of a previous response.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"**Deprecated**: Use `cursor` instead. Pagination returns the results in pages. Limited to 100 pages maximum.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_automations:AutomationEmailsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/bulk_subscriptions":{"post":{"operationId":"create","summary":"Bulk create subscription <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Create new subscriptions for a publication.","tags":["subpackage_bulk_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscriptions created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_bulk_subscriptions:BulkSubscriptionCreateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/type_:SubscriptionRequest"}}},"required":["subscriptions"]}}}}}},"/publications/{publicationId}/bulk_subscription_updates":{"get":{"operationId":"index","summary":"List subscription updates <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>","description":"Returns a list of Subscription Update objects for a publication.","tags":["subpackage_bulkSubscriptionUpdates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/bulk_subscription_updates/{id}":{"get":{"operationId":"show","summary":"Get subscription update <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>","description":"Returns a single Subscription Update object for a publication.","tags":["subpackage_bulkSubscriptionUpdates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"id","in":"path","description":"The ID of the Subscription Update object","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/subscriptions/bulk_actions":{"put":{"operationId":"put","summary":"Update subscriptions <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Bulk update multiple subscriptions fields, including status, custom fields, and tiers.","tags":["subpackage_bulkSubscriptionUpdates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsPatchResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItem"},"description":"An array of objects representing the subscriptions to be updated (max 1000)."}}}}}}},"patch":{"operationId":"patch","summary":"Update subscriptions <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Bulk update multiple subscriptions fields, including status, custom fields, and tiers.","tags":["subpackage_bulkSubscriptionUpdates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsPatchResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItem"},"description":"An array of objects representing the subscriptions to be updated (max 1000)."}}}}}}}},"/publications/{publicationId}/subscriptions":{"put":{"operationId":"put-status","summary":"Update subscriptions' status <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Bulk update subscriptions' status.","tags":["subpackage_bulkSubscriptionUpdates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"array","items":{"type":"string"},"description":"An array of subscription IDs to be updated"},"new_status":{"type":"string","description":"The new status to set for the subscriptions"}},"required":["subscription_ids","new_status"]}}}}},"patch":{"operationId":"patch-status","summary":"Update subscriptions' status <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Bulk update subscriptions' status.","tags":["subpackage_bulkSubscriptionUpdates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"array","items":{"type":"string"},"description":"An array of subscription IDs to be updated"},"new_status":{"type":"string","description":"The new status to set for the subscriptions"}},"required":["subscription_ids","new_status"]}}}}},"post":{"operationId":"create","summary":"Create subscription <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Create new subscriptions for a publication.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:SubscriptionRequest"}}}}},"get":{"operationId":"index","summary":"List subscriptions <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>","description":"Retrieve all subscriptions belonging to a specific publication.\n\n<Info> **New**: This endpoint now supports cursor-based pagination for better performance and consistency. Use the `cursor` parameter instead of `page` for new integrations. </Info>\n<Warning> **Deprecation Notice**: Offset-based pagination (using `page` parameter) is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination. See our [Pagination Guide](/welcome/pagination) for details. </Warning>","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`subscription_premium_tiers ` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription. <br>`newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.","required":false,"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsListRequestExpandItem"}},{"name":"status","in":"query","description":"Optionally filter the results by a status","required":false,"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsListRequestStatus"}},{"name":"tier","in":"query","description":"Optionally filter the results by a their tier","required":false,"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsListRequestTier"}},{"name":"premium_tiers[]","in":"query","description":"Optionally filter the results by one or multiple premium tiers","required":false,"schema":{"type":"string"}},{"name":"premium_tier_ids[]","in":"query","description":"Optionally filter the results by one or multiple premium tier ids","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. See the [Pagination Guide](/welcome/pagination) for more details.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"**Offset-based pagination (deprecated)**: Page number for offset-based pagination. This method is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned. See the [Pagination Guide](/welcome/pagination) for migration guidance.","required":false,"schema":{"type":"integer"}},{"name":"email","in":"query","description":"Optional email address to find a subscription.<br>This param must be an exact match and is case insensitive.","required":false,"schema":{"type":"string"}},{"name":"order_by","in":"query","description":"The field that the results are sorted by. Defaults to created<br> `created` - The time in which the subscription was first created.<br>","required":false,"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsListRequestOrderBy"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"creation_date","in":"query","description":"Optional date entry (in the format YYYY/MM/DD) that filters returned subscriptions by their creation date.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/complimentary_access":{"get":{"operationId":"index","summary":"List complimentary access <Badge intent=\"info\" minimal outlined>OAuth Scope: complimentary_access:read</Badge>","description":"Retrieve all complimentary access objects belonging to a specific publication.","tags":["subpackage_complimentaryAccess"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`tier` - Returns the full tier object associated with this complimentary access.<br>`stats` - Returns granted subscription counts.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"Use this opaque cursor token to fetch the next page of results. Obtain the value from `next_cursor` in a previous response.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_complimentaryAccess:IndexComplimentaryAccessResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/complimentary_access/{complimentaryAccessId}":{"get":{"operationId":"show","summary":"Get complimentary access <Badge intent=\"info\" minimal outlined>OAuth Scope: complimentary_access:read</Badge>","description":"Retrieve a single complimentary access object belonging to a specific publication.","tags":["subpackage_complimentaryAccess"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"complimentaryAccessId","in":"path","description":"The prefixed ID of the complimentary access object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`tier` - Returns the full tier object associated with this complimentary access.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_complimentaryAccess:ComplimentaryAccessResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/condition_sets":{"get":{"operationId":"index","summary":"List condition sets <Badge intent=\"info\" minimal outlined>OAuth Scope: condition_sets:read</Badge>","description":"Retrieve all active condition sets for a publication. Condition sets define reusable audience segments for targeting content to specific subscribers. Use the `purpose` parameter to filter by a specific use case.","tags":["subpackage_conditionSets"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"**Offset-based pagination (deprecated)**: Page number for offset-based pagination. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"purpose","in":"query","description":"Filter condition sets by purpose. When not specified, all active condition sets are returned.","required":false,"schema":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetPurpose"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/condition_sets/{conditionSetId}":{"get":{"operationId":"show","summary":"Get condition set <Badge intent=\"info\" minimal outlined>OAuth Scope: condition_sets:read</Badge>","description":"Retrieve a single active dynamic content condition set for a publication. Use `expand[]=stats` to calculate and return the active subscriber count synchronously.","tags":["subpackage_conditionSets"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"conditionSetId","in":"path","description":"The UUID of the condition set object","required":true,"schema":{"type":"string"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data.<br> `stats` - Calculates and returns the active subscriber count for this condition set synchronously.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetShowExpandItems"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetShowResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/custom_fields":{"post":{"operationId":"create","summary":"Create custom field <Badge intent=\"info\" minimal outlined>OAuth Scope: custom_fields:write</Badge>","description":"Create a custom field on a publication, for use in subscriptions.","tags":["subpackage_customFields"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_customFields:CustomFieldResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/type_:CustomFieldType"},"display":{"type":"string"}},"required":["kind","display"]}}}}},"get":{"operationId":"index","summary":"List custom fields <Badge intent=\"info\" minimal outlined>OAuth Scope: custom_fields:read</Badge>","description":"List all custom fields on a publication.","tags":["subpackage_customFields"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_customFields:CustomFieldIndexResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/custom_fields/{id}":{"get":{"operationId":"show","summary":"Get custom field <Badge intent=\"info\" minimal outlined>OAuth Scope: custom_fields:read</Badge>","description":"View a specific custom field on a publication.","tags":["subpackage_customFields"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"id","in":"path","description":"The ID of the Custom Fields object","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_customFields:CustomFieldResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"put":{"operationId":"put","summary":"Update custom field <Badge intent=\"info\" minimal outlined>OAuth Scope: custom_fields:write</Badge>","description":"Update a custom field on a publication.","tags":["subpackage_customFields"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"id","in":"path","description":"The ID of the Custom Fields object","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_customFields:CustomFieldResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display":{"type":"string"}}}}}}},"patch":{"operationId":"patch","summary":"Update custom field <Badge intent=\"info\" minimal outlined>OAuth Scope: custom_fields:write</Badge>","description":"Update a custom field on a publication.","tags":["subpackage_customFields"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"id","in":"path","description":"The ID of the Custom Fields object","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_customFields:CustomFieldsPatchResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display":{"type":"string"}}}}}}},"delete":{"operationId":"delete","summary":"Delete custom field <Badge intent=\"info\" minimal outlined>OAuth Scope: custom_fields:write</Badge>","description":"Delete a custom field from a publication.","tags":["subpackage_customFields"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"id","in":"path","description":"The ID of the Custom Fields object","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_customFields:CustomFieldsDeleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/data_privacy/deletion_requests":{"post":{"operationId":"create","summary":"Create data deletion request <Badge intent=\"info\" minimal outlined>OAuth Scope: data_deletion:write</Badge>","description":"<Warning>This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.</Warning>\n\nCreates a data deletion request for a subscriber within your organization. The subscriber's data will be redacted from all publications in the organization after a 14-day safety delay. This action cannot be undone once processing begins.\n\nAPI keys restricted to specific publications cannot access this endpoint and will receive a 403 response, since deletion requests apply to the entire workspace.","tags":["subpackage_dataDeletion"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The email address of the subscriber to delete."}},"required":["email"]}}}}},"get":{"operationId":"index","summary":"List data deletion requests <Badge intent=\"info\" minimal outlined>OAuth Scope: data_deletion:read</Badge>","description":"<Warning>This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.</Warning>\n\nList all data deletion requests for your organization.\n\nAPI keys restricted to specific publications cannot access this endpoint and will receive a 403 response, since deletion requests apply to the entire workspace.","tags":["subpackage_dataDeletion"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestIndexResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/data_privacy/deletion_requests/{id}":{"get":{"operationId":"show","summary":"Get data deletion request <Badge intent=\"info\" minimal outlined>OAuth Scope: data_deletion:read</Badge>","description":"<Warning>This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.</Warning>\n\nRetrieve the details and current status of a specific data deletion request.\n\nAPI keys restricted to specific publications cannot access this endpoint and will receive a 403 response, since deletion requests apply to the entire workspace.","tags":["subpackage_dataDeletion"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"id","in":"path","description":"The ID of the data deletion request","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/engagements":{"get":{"operationId":"index","summary":"Get publication engagements <Badge intent=\"info\" minimal outlined>OAuth Scope: publications:read</Badge>","description":"Retrieve email engagement metrics for a specific publication over a defined date range and granularity.<br><br> By default, the endpoint returns metrics for the past day, aggregated daily. The max number of days allowed is 31. All dates and times are in UTC.","tags":["subpackage_engagements"],"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"start_date","in":"query","description":"The starting date for the engagement metrics in `YYYY-MM-DD` format. Defaults to 1 day ago if not provided.","required":false,"schema":{"type":"string","format":"date"}},{"name":"number_of_days","in":"query","description":"The number of days to return engagement metrics for, starting from `start_date`. Must be between 1 and 31. Defaults to `1` if not provided.","required":false,"schema":{"$ref":"#/components/schemas/type_engagements:NumberOfDays"}},{"name":"granularity","in":"query","description":"The granularity at which to report the engagement metrics. Defaults to `day` if not provided.","required":false,"schema":{"$ref":"#/components/schemas/type_engagements:PublicationEngagementGranularity"}},{"name":"email_type","in":"query","description":"Filter engagement metrics by email type. If omitted, all email engagement is included.<br> `post`: Only post emails.<br> `message`: Only automated and system-generated emails.","required":false,"schema":{"$ref":"#/components/schemas/type_engagements:PublicationEngagementEmailType"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to `asc`.<br> `asc`: Oldest to newest<br> `desc`: Newest to oldest","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_engagements:PublicationEngagementsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/newsletter_lists":{"get":{"operationId":"index","summary":"List newsletter lists <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nList all newsletter lists for a publication.","tags":["subpackage_newsletterLists"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListIndexResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"post":{"operationId":"create","summary":"Create newsletter list <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nCreate a new newsletter list for a publication. The list will be created with an active status. The slug will be auto-generated from the name if not provided.","tags":["subpackage_newsletterLists"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the newsletter list."},"description":{"type":"string","description":"A description of the newsletter list."},"slug":{"type":"string","description":"A unique slug for the newsletter list. Auto-generated from the name if not provided."},"auto_subscribe":{"type":"boolean","description":"Whether new subscribers are automatically subscribed to this list."}},"required":["name"]}}}}}},"/publications/{publicationId}/newsletter_lists/{newsletterListId}":{"get":{"operationId":"show","summary":"Get newsletter list <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nRetrieve a single newsletter list belonging to a specific publication.","tags":["subpackage_newsletterLists"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"patch":{"operationId":"update","summary":"Update newsletter list <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nUpdate a newsletter list belonging to a specific publication.","tags":["subpackage_newsletterLists"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the newsletter list."},"description":{"type":"string","description":"A description of the newsletter list."},"slug":{"type":"string","description":"A unique slug for the newsletter list."},"auto_subscribe":{"type":"boolean","description":"Whether new subscribers are automatically subscribed to this list."},"status":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListWritableStatus","description":"The status of the newsletter list. Valid values are `active` and `archived`. Setting `draft` is not permitted."}}}}}}},"delete":{"operationId":"delete","summary":"Delete newsletter list <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nDelete a newsletter list belonging to a specific publication.","tags":["subpackage_newsletterLists"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions":{"post":{"operationId":"create","summary":"Create newsletter list subscription <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nSubscribe a subscription to a newsletter list. Accepts either a subscription_id or email to identify the subscription.","tags":["subpackage_newsletterListSubscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId","description":"The prefixed ID of the subscription to subscribe. Either subscription_id or email must be provided."},"email":{"type":"string","description":"The email address of the subscription to subscribe. Either subscription_id or email must be provided."}}}}}}},"get":{"operationId":"index","summary":"List newsletter list subscriptions <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nList all subscriptions for a newsletter list.","tags":["subpackage_newsletterListSubscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"**Offset-based pagination (deprecated)**: Page number for offset-based pagination. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionIndexResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/{newsletterListSubscriptionId}":{"get":{"operationId":"show","summary":"Get newsletter list subscription <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nRetrieve a single newsletter list subscription.","tags":["subpackage_newsletterListSubscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"newsletterListSubscriptionId","in":"path","description":"The prefixed ID of the newsletter list subscription object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListSubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"patch":{"operationId":"update","summary":"Update newsletter list subscription <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nUpdate a newsletter list subscription. Currently supports unsubscribing a subscription from a newsletter list.","tags":["subpackage_newsletterListSubscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"newsletterListSubscriptionId","in":"path","description":"The prefixed ID of the newsletter list subscription object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListSubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"unsubscribe":{"type":"boolean","description":"Set to true to unsubscribe the subscription from this newsletter list."}}}}}}}},"/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/by_subscription_id/{subscriptionId}":{"patch":{"operationId":"update-by-subscription-id","summary":"Update newsletter list subscription by subscription ID <Badge intent=\"warning\" minimal outlined>Beta</Badge> <Badge intent=\"info\" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  Newsletter Lists is currently in beta, the API is subject to change.\n</Note>\nUpdate a newsletter list subscription by subscription ID. An alternative to the update endpoint when you don't have the newsletter list subscription ID. Accepts either a subscription_id or email to identify the subscription. Currently supports unsubscribing a subscription from a newsletter list.","tags":["subpackage_newsletterListSubscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"newsletterListId","in":"path","description":"The prefixed ID of the newsletter list object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:NewsletterListId"}},{"name":"subscriptionId","in":"path","description":"The prefixed ID of the subscription","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"unsubscribe":{"type":"boolean","description":"Set to true to unsubscribe the subscription from this newsletter list."}}}}}}}},"/users/identify":{"get":{"operationId":"identify","summary":"Identify user <Badge intent=\"info\" minimal outlined>OAuth Scope: identify:read</Badge>","description":"Retrieve information about the user who authorized the OAuth access token.","tags":["subpackage_oauth_users"],"parameters":[{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_oauth_users:UserIdentifyResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/polls":{"get":{"operationId":"index","summary":"List polls <Badge intent=\"info\" minimal outlined>OAuth Scope: polls:read</Badge>","description":"Retrieve all polls belonging to a specific publication. Poll choices are always included. Use `expand[]=stats` to include aggregate vote counts per choice.","tags":["subpackage_polls"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"**Offset-based pagination (deprecated)**: Page number for offset-based pagination. Please migrate to cursor-based pagination using the `cursor` parameter. If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"order_by","in":"query","description":"The field that the results are sorted by. Defaults to created.<br> `created` - The time the poll was created.<br> `name` - The name of the poll.","required":false,"schema":{"$ref":"#/components/schemas/type_polls:PollOrderBy"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc.<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data.<br> `stats` - Returns aggregate vote counts per choice and total completions.<br> `poll_responses` - Returns up to 10 most recent subscriber responses. Use /polls/{pollId}/responses for paginated access to all responses.<br> `trivia_answer` - Returns the correct answer for trivia-type polls.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:PollsExpandItems"}}},{"name":"post_id","in":"query","description":"Filter to only return polls that were embedded in the specified post. Accepts a prefixed post ID (e.g. `post_abc123`).","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_polls:PollsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/polls/{pollId}":{"get":{"operationId":"show","summary":"Get poll <Badge intent=\"info\" minimal outlined>OAuth Scope: polls:read</Badge>","description":"Retrieve detailed information about a specific poll belonging to a publication. Use `expand[]=stats` for aggregate vote counts, or `expand[]=poll_responses` for individual subscriber responses.","tags":["subpackage_polls"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"pollId","in":"path","description":"The prefixed ID of the poll object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PollId"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data.<br> `stats` - Returns aggregate vote counts per choice and total completions.<br> `poll_responses` - Returns up to 10 most recent subscriber responses. Use /polls/{pollId}/responses for paginated access to all responses.<br> `trivia_answer` - Returns the correct answer for trivia-type polls.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:PollsExpandItems"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_polls:PollShowResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/polls/{pollId}/responses":{"get":{"operationId":"list-responses","summary":"List poll responses <Badge intent=\"info\" minimal outlined>OAuth Scope: polls:read</Badge>","description":"Retrieve all individual subscriber responses for a specific poll with cursor-based pagination. Use this endpoint for large datasets instead of the `expand[]=poll_responses` parameter on the poll show endpoint.","tags":["subpackage_polls"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"pollId","in":"path","description":"The prefixed ID of the poll object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PollId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"cursor","in":"query","description":"**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"**Offset-based pagination (deprecated)**: Page number for offset-based pagination.","required":false,"schema":{"type":"integer"}},{"name":"order_by","in":"query","description":"The field that the results are sorted by. Defaults to created.","required":false,"schema":{"$ref":"#/components/schemas/type_polls:PollResponsesOrderBy"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc.<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data.<br> `post` - Returns the post title and publication date for the post where each response was collected.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:PollResponsesExpandItems"}}},{"name":"post_id","in":"query","description":"Filter to only return responses collected via the specified post. Accepts a prefixed post ID (e.g. `post_abc123`).","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_polls:PollResponsesListResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/posts":{"post":{"operationId":"create","summary":"Create post <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  This feature is currently in beta, the API is subject to change, and available only to Enterprise users.<br/><br/>To inquire about Enterprise pricing,\n  please visit our <a href=\"https://www.beehiiv.com/enterprise\">Enterprise page</a>.\n</Note>\nCreate a post for a specific publication. For a detailed walkthrough including setup, testing workflows, and working with custom HTML and templates, see the <a href=\"https://www.beehiiv.com/support/article/36759164012439-using-the-send-api-and-create-post-endpoint\">Using the Send API and Create Post Endpoint</a> guide.\n\n## Content methods\n\nThere are three ways to provide content for a post. You must provide either `blocks` or `body_content`, but not both.\n\n### 1. Blocks\n\nUse the `blocks` field to build your post with structured content blocks such as paragraphs, images, headings, buttons, tables, and more. Each block has a `type` and its own set of properties. This method gives you fine-grained control over individual content elements and supports features like visual settings, visibility settings, and dynamic content targeting.\n\n### 2. Raw HTML (`body_content`)\n\nUse the `body_content` field to provide a single string of raw HTML. The HTML is wrapped in an `htmlSnippet` block internally. This is useful when you have pre-built HTML content or are migrating from another platform.\n\n### 3. HTML blocks within blocks\n\nUse `type: html` blocks inside the `blocks` array to embed raw HTML snippets alongside other structured blocks. This lets you mix structured content (paragraphs, images, etc.) with custom HTML where needed.\n\n## CSS and styling guardrails\n\nbeehiiv processes all HTML content through a sanitization pipeline. When using `body_content` or `html` blocks, be aware of the following:\n\n- **`<style>` tags are removed.** All `<style>` block elements are stripped during sanitization. Do not rely on embedded stylesheets.\n- **`<link>` tags are removed.** External stylesheet references are not allowed.\n- **Inline styles are preserved.** Styles applied directly to elements via the `style` attribute (e.g., `<div style=\"color: red;\">`) are kept intact.\n- **CSS classes have no effect.** While class attributes are not stripped, no corresponding stylesheets are loaded to apply them.\n- **beehiiv's email template wraps your content.** Your HTML is rendered inside beehiiv's email table structure, which applies its own layout and spacing. This may affect the appearance of your content.\n- **Use inline styles for all visual styling.** Since `<style>` and `<link>` tags are removed, inline styles on individual elements are the only reliable way to control appearance.","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsCreateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:Block"},"description":"The structured content blocks that make up the post. Supports block types such as paragraph, image, heading, button, html, table, list, columns, and more. You can embed raw HTML snippets within blocks using the `html` block type. Either this field OR the `body_content` field must be provided."},"body_content":{"type":"string","description":"The content of the post as a single raw HTML string. The HTML is wrapped in an `htmlSnippet` block internally. Note that `<style>` and `<link>` tags are removed during sanitization — use inline styles for all visual styling. Either this field OR the `blocks` field must be provided."},"title":{"type":"string","description":"The title of the post."},"subtitle":{"type":"string","description":"The subtitle of the post."},"post_template_id":{"$ref":"#/components/schemas/type_ids:PostTemplateId","description":"The ID of the template to use for the post. If not provided, the default template will be used."},"status":{"$ref":"#/components/schemas/type_posts:PostPublishStatus","description":"The status of the post. If not provided, the default (`confirmed`) value will be used and the post will either publish immediately (if no `scheduled_at` is provided) or at the `scheduled_at` time. **Deprecation notice:** The default will change to `draft` in a future release. Explicitly pass `confirmed` to preserve current auto-publish behavior."},"scheduled_at":{"type":"string","format":"date-time","description":"The time in which the post will be published. If not provided, the post will be published immediately unless `status` is set to `draft`. A draft post cannot be scheduled."},"custom_link_tracking_enabled":{"type":"boolean","description":"If true, custom link tracking will be enabled for this post. If not provided, the default value will be used."},"email_capture_type_override":{"$ref":"#/components/schemas/type_posts:PostEmailCaptureTypeOverride","description":"The email capture type to use for this post. If not provided, the default value will be used."},"override_scheduled_at":{"type":"string","format":"date-time","description":"If you wish to display a date other than the scheduled_at date in the email, you can provide a date here. This will not affect the actual publish date of the post."},"social_share":{"$ref":"#/components/schemas/type_posts:PostSocialShare","description":"The social share type to use for this post. If not provided, the default value will be used."},"thumbnail_image_url":{"type":"string","description":"The URL of the thumbnail image to use for the post. If not provided, the default value will be used."},"recipients":{"$ref":"#/components/schemas/type_posts:PostRecipients","description":"The recipients to use for this post. If not provided, the default value will be used."},"email_settings":{"$ref":"#/components/schemas/type_posts:PostEmailSettings","description":"The email settings to use for this post. If not provided, the default value will be used."},"web_settings":{"$ref":"#/components/schemas/type_posts:PostWebSettings","description":"The web settings to use for this post. If not provided, the default value will be used."},"seo_settings":{"$ref":"#/components/schemas/type_posts:PostMetadata","description":"The metadata to use for this post. If not provided, the default value will be used."},"content_tags":{"type":"array","items":{"type":"string"},"description":"The content tags to use for this post. If not provided, the default value will be used."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"The headers to use for this post. If not provided, the default value will be used."},"custom_fields":{"type":"object","additionalProperties":{"type":"string"},"description":"The custom fields to use for this post. If not provided, the default value will be used."},"newsletter_list_id":{"type":"string","description":"The prefixed ID of the newsletter list to associate with this post. When provided, the post will only be sent to subscribers of this list. <Badge intent=\"warning\" minimal outlined>Beta</Badge>"}},"required":["title"]}}}}},"get":{"operationId":"index","summary":"List posts <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:read</Badge>","description":"Retrieve all posts belonging to a specific publication","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"expand","in":"query","description":"Optionally expand the results by adding additional information. <br>`stats` - Adds statistics about the post(s). <br>`free_web_content` - Adds the web HTML rendered to a free reader. <br>`free_email_content` - Adds the email HTML rendered to a free reader. <br>`free_rss_content` - Adds the RSS feed HTML. <br>`premium_web_content` - Adds the web HTML rendered to a premium reader. <br>`premium_email_content` - Adds the email HTML rendered to a premium reader.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:PostExpandField"}}},{"name":"audience","in":"query","description":"Optionally filter the results by audience","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostAudienceFilter"}},{"name":"platform","in":"query","description":"Optionally filter the results by platform.<br>`web` - Posts only published to web.<br>`email` - Posts only published to email.<br>`both` - Posts published to email and web.<br>`all` - Does not restrict results by platform.","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostPlatformFilter"}},{"name":"status","in":"query","description":"Optionally filter the results by the status of the post.<br>`draft` - not been scheduled.<br>`confirmed` - The post will be active after the `scheduled_at`.<br>`archived` - The post is no longer active.<br>`all` - Does not restrict results by status.","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostStatusFilter"}},{"name":"content_tags[]","in":"query","description":"Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it.<br><br><b>Example</b>: Filtering for `content_tags: [\"sales\",\"closing\"]` will return results of posts that have *either* `sales` or `closing` content_tags.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"slugs[]","in":"query","description":"Optionally filter posts by their slugs. Adding a slug will return any post with that exact slug associated to it.<br><br><b>Example:</b> Filtering for `slugs: [\"my-first-post\",\"another-post\"]` will return results of posts that have *either* `my-first-post` or `another-post` as their slug.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"authors[]","in":"query","description":"Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive).<br><br><b>Example:</b> Filtering for `authors: [\"John Doe\",\"Jane Smith\"]` will return results of posts that have *either* John Doe or Jane Smith as authors.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"premium_tiers","in":"query","description":"Optionally filter posts by audience based on premium tiers.<br> This takes in an array of Display Names of the premium tiers.<br> It will also scope any expanded content output to the specified premium tiers.<br> Note: This is case insensitive.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"order_by","in":"query","description":"The field that the results are sorted by. Defaults to created<br> `created` - The time in which the post was first created.<br> `publish_date` - The time the post was set to be published.<br> `displayed_date` - The time displayed in place of the `publish_date`. If no `displayed_date` was set, it will default to the `publish_date`","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostOrderBy"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"hidden_from_feed","in":"query","description":"Optionally filter the results by the `hidden_from_feed` attribute of the post.<br>`all` - Does not restrict results by `hidden_from_feed`.<br>`true` - Only return posts hidden from the feed.<br>`false` - Only return posts that are visible on the feed.","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostsListRequestHiddenFromFeed"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/posts/{postId}":{"patch":{"operationId":"update","summary":"Update post <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:write</Badge>","description":"<Note title=\"Currently in beta\" icon=\"b\">\n  This feature is currently in beta, the API is subject to change, and available only to Enterprise users.<br/><br/>To inquire about Enterprise pricing,\n  please visit our <a href=\"https://www.beehiiv.com/enterprise\">Enterprise page</a>.\n</Note>\nUpdate an existing post for a specific publication. Only the fields provided in the request body will be updated — all other fields remain unchanged. For a detailed walkthrough of content methods and working with custom HTML, see the <a href=\"https://www.beehiiv.com/support/article/36759164012439-using-the-send-api-and-create-post-endpoint\">Using the Send API and Create Post Endpoint</a> guide.\n\nTo update post content, provide either `blocks` or `body_content` (not both). If neither is provided, the existing content is preserved. The same content methods and CSS guardrails described in the create endpoint apply here.","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"postId","in":"path","description":"The prefixed ID of the post to update","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PostId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:Block"},"description":"The structured content blocks to replace the post's current content. Supports block types such as paragraph, image, heading, button, html, table, list, columns, and more. Cannot be provided together with `body_content`."},"body_content":{"type":"string","description":"Raw HTML to replace the post's current content. The HTML is wrapped in an `htmlSnippet` block internally. Note that `<style>` and `<link>` tags are removed during sanitization — use inline styles for all visual styling. Cannot be provided together with `blocks`."},"title":{"type":"string","description":"The title of the post."},"subtitle":{"type":"string","description":"The subtitle of the post."},"scheduled_at":{"type":"string","format":"date-time","description":"The time at which the post will be published. Cannot be updated after the post has already been sent."},"custom_link_tracking_enabled":{"type":"boolean","description":"If true, custom link tracking will be enabled for this post."},"email_capture_type_override":{"$ref":"#/components/schemas/type_posts:PostEmailCaptureTypeOverride","description":"The email capture type to use for this post."},"override_scheduled_at":{"type":"string","format":"date-time","description":"A display date that overrides the scheduled_at date shown in the email. Does not affect the actual publish date."},"social_share":{"$ref":"#/components/schemas/type_posts:PostSocialShare","description":"The social share type to use for this post."},"thumbnail_image_url":{"type":"string","description":"The URL of the thumbnail image to use for the post."},"email_settings":{"$ref":"#/components/schemas/type_posts:PostEmailSettings","description":"The email settings to use for this post. Only the provided fields within this object will be updated."},"web_settings":{"$ref":"#/components/schemas/type_posts:PostWebSettings","description":"The web settings to use for this post. Only the provided fields within this object will be updated."},"seo_settings":{"$ref":"#/components/schemas/type_posts:PostMetadata","description":"The SEO metadata to use for this post. Only the provided fields within this object will be updated."},"status":{"$ref":"#/components/schemas/type_posts:PostPublishStatus","description":"Transition the post's status. Use `confirmed` to schedule or publish a draft post. Only the `draft` → `confirmed` transition is supported — a confirmed post cannot be moved back to `draft`."},"content_tags":{"type":"array","items":{"type":"string"},"description":"The content tags for this post. When provided, this replaces all existing content tags on the post."}}}}}}},"get":{"operationId":"show","summary":"Get post <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:read</Badge>","description":"Retrieve a single Post belonging to a specific publication","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"postId","in":"path","description":"The prefixed ID of the post object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PostId"}},{"name":"expand","in":"query","description":"Optionally expand the results by adding additional information. <br>`stats` - Adds statistics about the post(s). <br>`free_web_content` - Adds the web HTML rendered to a free reader. <br>`free_email_content` - Adds the email HTML rendered to a free reader. <br>`free_rss_content` - Adds the RSS feed HTML. <br>`premium_web_content` - Adds the web HTML rendered to a premium reader. <br>`premium_email_content` - Adds the email HTML rendered to a premium reader.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:PostExpandField"}}},{"name":"premium_tiers","in":"query","description":"Scope any expanded content output to the specified premium tiers.<br> This takes in an array of Display Names of the premium tiers.<br> Note: This is case insensitive.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"delete":{"operationId":"delete","summary":"Delete post <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:write</Badge>","description":"Delete or Archive a post. Any post that has been confirmed will have it's status changed to `archived`. Posts in the `draft` status will be permanently deleted.","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"postId","in":"path","description":"The prefixed ID of the post object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PostId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsDeleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/posts/aggregate_stats":{"get":{"operationId":"aggregate-stats","summary":"Get aggregate stats <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:read</Badge>","description":"Retrieve aggregate stats for all posts","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"audience","in":"query","description":"Optionally filter the results by audience","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostAudienceFilter"}},{"name":"platform","in":"query","description":"Optionally filter the results by platform.<br>`web` - Posts only published to web.<br>`email` - Posts only published to email.<br>`both` - Posts published to email and web.<br>`all` - Does not restrict results by platform.","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostPlatformFilter"}},{"name":"status","in":"query","description":"Optionally filter the results by the status of the post.<br>`draft` - not been scheduled.<br>`confirmed` - The post will be active after the `scheduled_at`.<br>`archived` - The post is no longer active.<br>`all` - Does not restrict results by status.","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostStatusFilter"}},{"name":"content_tags[]","in":"query","description":"Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it.<br>Example: Filtering for `content_tags: [\"sales\",\"closing\"]` will return results of posts that have *either* sales or closing content_tags.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"authors[]","in":"query","description":"Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive).<br><br><b>Example:</b> Filtering for `authors: [\"John Doe\",\"Jane Smith\"]` will return results of posts that have *either* John Doe or Jane Smith as authors.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"hidden_from_feed","in":"query","description":"Optionally filter the results by the `hidden_from_feed` attribute of the post.<br>`all` - Does not restrict results by `hidden_from_feed`.<br>`true` - Only return posts hidden from the feed.<br>`false` - Only return posts that are visible on the feed.","required":false,"schema":{"$ref":"#/components/schemas/type_posts:PostsListRequestHiddenFromFeed"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsAggregateStatsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/posts/{postId}/test_sends":{"post":{"operationId":"test-send","summary":"Send test email <Badge intent=\"info\" minimal outlined>OAuth Scope: posts</Badge>","description":"Send a test email for a specific post to one or more email addresses. Returns the number of remaining test sends for the day and the time at which the limit resets.","tags":["subpackage_posts"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"postId","in":"path","description":"The prefixed ID of the post object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PostId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_posts:PostsTestSendResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_emails":{"type":"array","items":{"type":"string"},"description":"One or more email addresses to send the test to. Returns 422 if the daily test send limit has been reached."}},"required":["recipient_emails"]}}}}}},"/publications/{publicationId}/post_templates":{"get":{"operationId":"index","summary":"Get post templates <Badge intent=\"info\" minimal outlined>OAuth Scope: posts:read</Badge>","description":"Retrieve a list of post templates available for the publication.","tags":["subpackage_postTemplates"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"order","in":"query","description":"The direction of the request. Defaults to `asc`.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"order_by","in":"query","description":"The field to order by. Defaults to `created`.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_postTemplates:PostTemplatesGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications":{"get":{"operationId":"index","summary":"List publications <Badge intent=\"info\" minimal outlined>OAuth Scope: publications:read</Badge>","description":"Retrieve all publications associated with your API key.","tags":["subpackage_publications"],"parameters":[{"name":"expand","in":"query","description":"Optionally expand the results by adding additional information like subscription counts and engagement stats.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_publications:PublicationsRequestExpandItem"}}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"order_by","in":"query","description":"The field that the results are sorted by. Defaults to created<br> `created` - The time in which the publication was first created.<br> `name` - The name of the publication.","required":false,"schema":{"$ref":"#/components/schemas/type_publications:PublicationsListRequestOrderBy"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_publications:PublicationsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}":{"get":{"operationId":"show","summary":"Get publication <Badge intent=\"info\" minimal outlined>OAuth Scope: publications:read</Badge>","description":"Retrieve a single publication","tags":["subpackage_publications"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"expand","in":"query","description":"Optionally expand the results by adding additional information like subscription counts and engagement stats.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_publications:PublicationsGetRequestExpandItem"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_publications:PublicationsGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/referral_program":{"get":{"operationId":"show","summary":"Get referral program <Badge intent=\"info\" minimal outlined>OAuth Scope: referral_program:read</Badge>","description":"Retrieve details about the publication's referral program, including milestones and rewards.","tags":["subpackage_referralProgram"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_referralProgram:ReferralProgramGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/segments":{"post":{"operationId":"create","summary":"Create segment","description":"Create a new segment.<br><br> **Manual segments** — Use `subscriptions` or `emails` input to create a segment from an explicit list of subscription IDs or email addresses. The segment is processed synchronously and returns with `status: completed`. Net new email addresses will be ignored; create subscriptions using the `Create Subscription` endpoint.<br><br> **Dynamic segments** — Use `custom_fields` input to create a segment that filters subscribers by custom field values. The segment is processed asynchronously and returns with `status: pending`. Results will be available in the `List Segment Subscribers` endpoint after processing is complete.","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentShowResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"A unique name for the segment that does not already exist in the publication."},"input":{"$ref":"#/components/schemas/type_segments:SegmentSubscriptionInput"}},"required":["name","input"]}}}}},"get":{"operationId":"index","summary":"List segments <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>","description":"Retrieve information about all segments belonging to a specific publication","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"type","in":"query","description":"Optionally filter the results by the segment's type.","required":false,"schema":{"$ref":"#/components/schemas/type_:SegmentType"}},{"name":"status","in":"query","description":"Optionally filter the results by the segment's status.","required":false,"schema":{"$ref":"#/components/schemas/type_segments:SegmentRequestStatus"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"order_by","in":"query","description":"The field that the results are sorted by. Defaults to created<br> `created` - The time in which the segment was first created.<br> `last_calculated` - The time that the segment last completed calculation. Measured in seconds since the Unix epoch.","required":false,"schema":{"$ref":"#/components/schemas/type_segments:SegmentOrderBy"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data. <br> `stats` - Requests the most recently calculated statistics for a segment. <br> Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_segments:SegmentsExpandItems"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/segments/{segmentId}":{"get":{"operationId":"show","summary":"Get segment <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>","description":"Retrieve information about a specific segment belonging to a publication","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"segmentId","in":"path","description":"The prefixed ID of the segment object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SegmentId"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data. <br> `stats` - Requests the most recently calculated statistics for a segment. <br> Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_segments:SegmentsExpandItems"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentShowResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"delete":{"operationId":"delete","summary":"Delete segment <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:write</Badge>","description":"Delete a segment. Deleting the segment does not effect the subscriptions in the segment.","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"segmentId","in":"path","description":"The prefixed ID of the segment object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SegmentId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentDeleteResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/segments/{segmentId}/recalculate":{"put":{"operationId":"recalculate","summary":"Recalculate segment <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:write</Badge>","description":"Recalculates a specific segment belonging to a publication","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"segmentId","in":"path","description":"The prefixed ID of the segment object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SegmentId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentRecalculateResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/segments/{segmentId}/members":{"get":{"operationId":"list-members","summary":"List segment subscribers <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>","description":"List all members in a segment with full subscription data. Each member is returned as a subscription  object containing complete subscriber information and their subscription details.  Supports optional expansions for stats, custom fields, tags, referrals, and premium tiers.\n**Use this endpoint when you need detailed subscriber information.** If you only need subscriber IDs, use `/segments/{segmentId}/results` for a lighter-weight response.","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"segmentId","in":"path","description":"The prefixed ID of the segment object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SegmentId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"expand[]","in":"query","description":"Optionally expand the response to include additional data. <br> `stats` - Returns statistics about the subscription(s). <br> `custom_fields` - Returns custom field values set on the subscription. <br> `referrals` - Returns referrals made by the subscription. <br> `tags` - Returns tags associated with the subscription. <br> `subscription_premium_tiers` - Returns premium tier(s) the subscription is subscribed to.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_segments:SegmentMembersExpandItems"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentMembersResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/segments/{segmentId}/results":{"get":{"operationId":"expand-results","summary":"List segment subscriber IDs <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>","description":"List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details.\n**Use this endpoint when you only need subscriber IDs** (e.g., for counting, ID-based lookups, or  integrations with external systems). If you need full subscriber details (email, status, custom fields, etc.), use `/segments/{segmentId}/members` instead.","tags":["subpackage_segments"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"segmentId","in":"path","description":"The prefixed ID of the segment object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SegmentId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_segments:SegmentsGetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/subscriptions/by_email/{email}":{"get":{"operationId":"get-by-email","summary":"Get subscription by email <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>","description":"<Info>Please note that this endpoint requires the email to be URL encoded. Please reference your language's documentation for the correct method of encoding.</Info> Retrieve a single subscription belonging to a specific email address in a specific publication.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"email","in":"path","description":"The ID of the subscriber object","required":true,"schema":{"type":"string"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`subscription_premium_tiers ` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription. <br>`tags` - Returns an array of tags that have been set on the subscription.<br>`newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.","required":false,"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsGetRequestExpandItem"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"put":{"operationId":"update-by-email","summary":"Update subscription by email <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Update a single subscription by email.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"email","in":"path","description":"The email of the subscription object","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The new email address for the subscription"},"tier":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPutRequestSubscriptionsItemTier","description":"Optional parameter to set the tier for this subscription."},"premium_tier_ids":{"type":"array","items":{"type":"string"},"description":"An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with `premium_tiers` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"premium_tiers":{"type":"array","items":{"type":"string"},"description":"An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with `premium_tier_ids` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"stripe_customer_id":{"$ref":"#/components/schemas/type_ids:OptionalStripeCustomerId","description":"The Stripe Customer ID of the subscription (not required)"},"unsubscribe":{"type":"boolean","description":"A boolean value specifying whether to unsubscribe this subscription from the publication (not required)"},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem"},"description":"An array of custom field objects to update"},"complimentary_gift_id":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId","description":"The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication."}}}}}}}},"/publications/{publicationId}/subscriptions/{subscriptionId}":{"get":{"operationId":"get-by-id","summary":"Get subscription by ID <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:read</Badge>","description":"<Info>In previous versions of the API, another endpoint existed to retrieve a subscription by the subscriber ID. This endpoint is now deprecated and will be removed in a future version of the API. Please use this endpoint instead. The subscription ID can be found by exporting a list of subscriptions either via the `Settings > Publications > Export Data` or by exporting a CSV in a segment.</Info> Retrieve a single subscription belonging to a specific publication.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"subscriptionId","in":"path","description":"The prefixed ID of the subscription object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`subscription_premium_tiers` - Returns an array of tiers the subscription is associated with.<br>`referrals` - Returns an array of subscriptions with limited data - `id`, `email`, and `status`. These are the subscriptions that were referred by this subscription.<br>`stats` - Returns statistics about the subscription(s).<br>`custom_fields` - Returns an array of custom field values that have been set on the subscription. <br>`tags` - Returns an array of tags that have been set on the subscription.<br>`newsletter_lists` - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to.","required":false,"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsGetRequestExpandItem"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"put":{"operationId":"put","summary":"Update subscription by ID <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Update a single subscription.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"subscriptionId","in":"path","description":"The prefixed ID of the subscription object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPutRequestSubscriptionsItemTier","description":"Optional parameter to set the tier for this subscription."},"premium_tier_ids":{"type":"array","items":{"type":"string"},"description":"An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with `premium_tiers` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"premium_tiers":{"type":"array","items":{"type":"string"},"description":"An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with `premium_tier_ids` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"email":{"type":"string","description":"The new email address for the subscription"},"stripe_customer_id":{"$ref":"#/components/schemas/type_ids:OptionalStripeCustomerId","description":"The Stripe Customer ID of the subscription (not required)"},"unsubscribe":{"type":"boolean","description":"A boolean value specifying whether to unsubscribe this subscription from the publication (not required)"},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem"},"description":"An array of custom field objects to update"},"complimentary_gift_id":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId","description":"The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication."}}}}}}},"patch":{"operationId":"patch","summary":"Update subscription by ID <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Update a single subscription.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"subscriptionId","in":"path","description":"The prefixed ID of the subscription object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The new email address for the subscription"},"tier":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItemTier","description":"Optional parameter to set the tier for this subscription."},"premium_tier_ids":{"type":"array","items":{"type":"string"},"description":"An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with `premium_tiers` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"premium_tiers":{"type":"array","items":{"type":"string"},"description":"An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with `premium_tier_ids` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"stripe_customer_id":{"$ref":"#/components/schemas/type_ids:OptionalStripeCustomerId","description":"The Stripe Customer ID of the subscription (not required)"},"unsubscribe":{"type":"boolean","description":"A boolean value specifying whether to unsubscribe this subscription from the publication (not required)"},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem"},"description":"An array of custom field objects to update"},"complimentary_gift_id":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId","description":"The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication."}}}}}}},"delete":{"operationId":"delete","summary":"Delete subscription <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"<Warning>This cannot be undone. All data associated with the subscription will also be deleted. We recommend unsubscribing when possible instead of deleting. If a premium subscription is deleted they will no longer be billed.</Warning> Deletes a subscription.","tags":["subpackage_subscriptions"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"subscriptionId","in":"path","description":"The prefixed ID of the subscription object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionDeleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/subscriptions/{subscriptionId}/tags":{"post":{"operationId":"create","summary":"Add subscription tag <Badge intent=\"info\" minimal outlined>OAuth Scope: subscriptions:write</Badge>","description":"Adds tags to a subscription. If the tag does not exist on the publication, it will be created automatically.","tags":["subpackage_subscriptionTags"],"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"subscriptionId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_subscriptionTags:SubscriptionTagsCreateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Tags that can be used to group subscribers"}}}}}}}},"/publications/{publicationId}/tiers":{"post":{"operationId":"create","summary":"Create a tier <Badge intent=\"info\" minimal outlined>OAuth Scope: tiers:write</Badge>","description":"Create a new tier for a publication.","tags":["subpackage_tiers"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_tiers:TierResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"prices_attributes":{"type":"array","items":{"$ref":"#/components/schemas/type_tiers:TierPricesAttributesItem"}}},"required":["name"]}}}}},"get":{"operationId":"index","summary":"List tiers <Badge intent=\"info\" minimal outlined>OAuth Scope: tiers:read</Badge>","description":"Retrieve all tiers belonging to a specific publication","tags":["subpackage_tiers"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`stats` - Returns statistics about the tier(s).<br>`prices` - Returns prices for the tier(s).","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.","required":false,"schema":{"type":"integer"}},{"name":"direction","in":"query","description":"The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.","required":false,"schema":{"$ref":"#/components/schemas/type_:RequestDirection"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_tiers:IndexTiersResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/tiers/{tierId}":{"get":{"operationId":"show","summary":"Get tier <Badge intent=\"info\" minimal outlined>OAuth Scope: tiers:read</Badge>","description":"Retrieve a single tier belonging to a specific publication","tags":["subpackage_tiers"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"tierId","in":"path","description":"The prefixed ID of the tier object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:TierId"}},{"name":"expand[]","in":"query","description":"Optional list of expandable objects.<br>`stats` - Returns statistics about the tier(s).<br>`prices` - Returns prices for the tier(s).","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_tiers:TierResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"put":{"operationId":"put","summary":"Update a tier <Badge intent=\"info\" minimal outlined>OAuth Scope: tiers:write</Badge>","description":"Update an existing tier belonging to a specific publication","tags":["subpackage_tiers"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"tierId","in":"path","description":"The prefixed ID of the tier object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:TierId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_tiers:TierResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"prices_attributes":{"type":"array","items":{"$ref":"#/components/schemas/type_tiers:UpdateTierPriceRequest"}}}}}}}},"patch":{"operationId":"patch","summary":"Update a tier <Badge intent=\"info\" minimal outlined>OAuth Scope: tiers:write</Badge>","description":"Update an existing tier belonging to a specific publication","tags":["subpackage_tiers"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"tierId","in":"path","description":"The prefixed ID of the tier object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:TierId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_tiers:TierResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"prices_attributes":{"type":"array","items":{"$ref":"#/components/schemas/type_tiers:UpdateTierPriceRequest"}}}}}}}}},"/publications/{publicationId}/webhooks":{"post":{"operationId":"create","summary":"Create a webhook <Badge intent=\"info\" minimal outlined>OAuth Scope: webhooks:write</Badge>","description":"Create a new webhook for a given publication.","tags":["subpackage_webhooks"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_webhooks:WebhookResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to send events to."},"event_types":{"type":"array","items":{"$ref":"#/components/schemas/type_webhooks:WebhookEventType"},"description":"The types of events the webhook will receive."},"description":{"type":"string","description":"A description of the webhook."}},"required":["url","event_types"]}}}}},"get":{"operationId":"index","summary":"List webhooks <Badge intent=\"info\" minimal outlined>OAuth Scope: webhooks:read</Badge>","description":"Retrieve all webhooks belonging to a specific publication.","tags":["subpackage_webhooks"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"limit","in":"query","description":"A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_webhooks:IndexWebhooksResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/publications/{publicationId}/webhooks/{endpointId}":{"get":{"operationId":"show","summary":"Get webhook <Badge intent=\"info\" minimal outlined>OAuth Scope: webhooks:read</Badge>","description":"Retrieve a specific webhook belonging to a publication.","tags":["subpackage_webhooks"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"endpointId","in":"path","description":"The prefixed ID of the webhook object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:EndpointId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_webhooks:WebhookResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}},"patch":{"operationId":"update","summary":"Update webhook <Badge intent=\"info\" minimal outlined>OAuth Scope: webhooks:write</Badge>","description":"Update a webhook subscription for a publication.","tags":["subpackage_webhooks"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"endpointId","in":"path","description":"The prefixed ID of the webhook object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:EndpointId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_webhooks:WebhookResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event_types":{"type":"array","items":{"$ref":"#/components/schemas/type_webhooks:WebhookEventType"},"description":"The types of events the webhook will receive."},"description":{"type":"string","description":"A description of the webhook."}}}}}}},"delete":{"operationId":"delete","summary":"Delete a webhook <Badge intent=\"info\" minimal outlined>OAuth Scope: webhooks:write</Badge>","description":"Delete a webhook subscription from a publication.","tags":["subpackage_webhooks"],"parameters":[{"name":"publicationId","in":"path","description":"The prefixed ID of the publication object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:PublicationId"}},{"name":"endpointId","in":"path","description":"The prefixed ID of the webhook object","required":true,"schema":{"$ref":"#/components/schemas/type_ids:EndpointId"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_webhooks:WebhooksDeleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/workspaces/identify":{"get":{"operationId":"identify","summary":"Identify workspace <Badge intent=\"info\" minimal outlined>OAuth Scope: identify:read</Badge>","description":"Retrieve information about the workspace the OAuth or API token is associated with.","tags":["subpackage_workspaces"],"parameters":[{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_workspaces:WorkspaceIdentifyResponse"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}},"/workspaces/publications/by_subscription_email/{email}":{"get":{"operationId":"publications-by-subscription-email","summary":"Get publications by subscription email <Badge intent=\"info\" minimal outlined>OAuth Scope: publications:read</Badge>","description":"Retrieve all publications in the workspace that have a subscription for the specified email address. The workspace is determined by the provided API key.","tags":["subpackage_workspaces"],"parameters":[{"name":"email","in":"path","description":"The email address to search for subscriptions","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","description":"Optionally expand the results by adding additional information. <br>`subscription` - Returns the full Subscription object for the email address in each publication. <br>`publication` - Returns the full Publication object instead of just ID and name. <br>`subscription_custom_fields` - Returns custom field values nested within the subscription object. (Returns the subscription object regardless of whether `subscription` is requested.)","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_workspaces:PublicationsBySubscriptionEmailRequestExpandItem"}}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_workspaces:PublicationsBySubscriptionEmailResponseItem"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"401":{"description":"Unauthorized. The API key or OAuth access token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_:Error"}}}}}}}},"servers":[{"url":"https://api.beehiiv.com/v2","description":"Default"}],"components":{"schemas":{"type_ids:PublicationId":{"type":"string","description":"The prefixed ID of the publication.","title":"PublicationId"},"type_advertisement_opportunities:AdvertisementOpportunity":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the opportunity."},"advertiser_name":{"type":"string","description":"The name of the advertiser."},"payout_rate":{"type":"string","description":"The amount you'll earn."},"advertisement_kind":{"type":"string","description":"What kind of an ad it is. With or without logo."},"send_by_window_start_at":{"type":"integer","description":"The earliest this ad can be sent. Measured in seconds since the Unix epoch."},"send_by_window_end_at":{"type":"integer","description":"When this ad needs to be sent by. Measured in seconds since the Unix epoch."}},"required":["id","advertiser_name","payout_rate","advertisement_kind","send_by_window_start_at","send_by_window_end_at"],"title":"AdvertisementOpportunity"},"type_advertisement_opportunities:AdvertisementOpportunitiesGetResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_advertisement_opportunities:AdvertisementOpportunity"},"description":"A list of post templates available for this publication."},"total_results":{"type":"integer","description":"The total number of results from all pages."}},"required":["data","total_results"],"title":"AdvertisementOpportunitiesGetResponse"},"type_:ErrorDetail":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message","code"],"title":"ErrorDetail"},"type_:Error":{"type":"object","properties":{"status":{"type":"integer"},"statusText":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/type_:ErrorDetail"}}},"required":["status","statusText","errors"],"description":"The top level error response.","title":"Error"},"type_authors:AuthorType":{"type":"string","enum":["user","guest_author"],"title":"AuthorType"},"type_authors:AuthorSocialMediaLinks":{"type":"object","properties":{"twitter_handle":{"type":"string"},"facebook_url":{"type":"string"},"instagram_url":{"type":"string"},"linkedin_url":{"type":"string"},"youtube_url":{"type":"string"},"tiktok_url":{"type":"string"},"discord_url":{"type":"string"},"bluesky_url":{"type":"string"},"rss_url":{"type":"string"}},"title":"AuthorSocialMediaLinks"},"type_authors:Author":{"type":"object","properties":{"id":{"type":"string","description":"The UUID of the author."},"type":{"$ref":"#/components/schemas/type_authors:AuthorType","description":"The author type."},"name":{"type":"string","description":"The author display name."},"bio":{"type":"string","description":"The biography text for the author."},"bio_image_url":{"type":"string","description":"The profile image URL for the author."},"social_media_links":{"$ref":"#/components/schemas/type_authors:AuthorSocialMediaLinks"}},"required":["id","type","name","social_media_links"],"title":"Author"},"type_authors:AuthorsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_authors:Author"},"description":"A list of authors available for this publication."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"AuthorsListResponse"},"type_authors:AuthorsGetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_authors:Author"}},"required":["data"],"title":"AuthorsGetResponse"},"type_ids:AutomationId":{"type":"string","description":"The prefixed ID of the automation.","title":"AutomationId"},"type_ids:SubscriptionId":{"type":"string","description":"The prefixed ID of the subscription.","title":"SubscriptionId"},"type_:DoubleOptOverride":{"type":"string","description":"Override publication double-opt settings for this subscription.","title":"DoubleOptOverride"},"type_ids:AutomationJourneyId":{"type":"string","description":"The prefixed ID of the automation journey.","title":"AutomationJourneyId"},"type_:AutomationJourneyStatus":{"type":"string","enum":["in_progress","completed","exited_early","manually_removed"],"title":"AutomationJourneyStatus"},"type_:AutomationJourney":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:AutomationJourneyId","description":"The prefixed automation journey id"},"automation_id":{"$ref":"#/components/schemas/type_ids:AutomationId","description":"The prefixed automation id"},"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId"},"email":{"type":"string"},"status":{"$ref":"#/components/schemas/type_:AutomationJourneyStatus"},"started_at":{"type":"integer","description":"The time that the subscriber started their flow through the automation. Measured in seconds since the Unix epoch."},"completed_at":{"type":"integer","description":"The time that the subscriber finished their flow through the automation. Measured in seconds since the Unix epoch."}},"required":["id","automation_id","status"],"description":"A subscribers' journey through an automation flow.","title":"AutomationJourney"},"type_automationJourneys:AutomationJourneysResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:AutomationJourney"}},"required":["data"],"title":"AutomationJourneysResponse"},"type_automationJourneys:AutomationJourneysGetRequestStatus":{"type":"string","enum":["in_progress","completed","exited_early","all"],"default":"all","title":"AutomationJourneysGetRequestStatus"},"type_automationJourneys:AutomationJourneysIndexResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:AutomationJourney"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"AutomationJourneysIndexResponse"},"type_automations:AutomationsListRequestExpandItem":{"type":"string","enum":["stats"],"title":"AutomationsListRequestExpandItem"},"type_:AutomationStatus":{"type":"string","enum":["running","finishing","inactive","live","draft"],"title":"AutomationStatus"},"type_:AutomationTriggerEvent":{"type":"string","enum":["api","downgrade","email_submission","form_submission","manual","poll_submission","purchased_product","referral_action","segment_action","signup","unengaged","upgrade"],"title":"AutomationTriggerEvent"},"type_:AutomationStatsJourneys":{"type":"object","properties":{"running":{"type":"integer","default":0,"description":"Number of journeys currently in progress"},"completed":{"type":"integer","default":0,"description":"Number of completed journeys"},"total":{"type":"integer","default":0,"description":"Total number of journeys"}},"description":"Journey counts for an automation.","title":"AutomationStatsJourneys"},"type_:AutomationStatsEmail":{"type":"object","properties":{"recipients":{"type":"integer","default":0,"description":"Total number of email recipients across all emails"},"delivered":{"type":"integer","default":0,"description":"Total number of emails delivered"},"opens":{"type":"integer","default":0,"description":"Total number of email opens"},"unique_opens":{"type":"integer","default":0,"description":"Total number of unique email opens"},"open_rate":{"type":"number","format":"double","description":"The percentage of emails that have been opened"},"clicks":{"type":"integer","default":0,"description":"Total number of email clicks"},"unique_clicks":{"type":"integer","default":0,"description":"Unique number of email clicks"},"click_rate":{"type":"number","format":"double","description":"The percentage of emails that have been clicked"},"unsubscribes":{"type":"integer","default":0,"description":"Total number of email unsubscribes"},"spam_reports":{"type":"integer","default":0,"description":"The number of subscribers that reported emails as spam"}},"description":"Aggregate email engagement statistics for an automation.","title":"AutomationStatsEmail"},"type_:AutomationStats":{"type":"object","properties":{"journeys":{"$ref":"#/components/schemas/type_:AutomationStatsJourneys","description":"Journey counts for the automation"},"email":{"$ref":"#/components/schemas/type_:AutomationStatsEmail","description":"Aggregate email engagement statistics"}},"description":"Optional statistics for an automation. Retrievable by including `expand: [stats]` in the automation request.","title":"AutomationStats"},"type_:Automation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:AutomationId","description":"A unique prefixed id of the automation"},"status":{"$ref":"#/components/schemas/type_:AutomationStatus"},"name":{"type":"string"},"trigger_events":{"type":"array","items":{"$ref":"#/components/schemas/type_:AutomationTriggerEvent"},"description":"The types of events that can trigger the automation."},"description":{"type":"string"},"stats":{"$ref":"#/components/schemas/type_:AutomationStats"}},"required":["id","status","name","trigger_events"],"title":"Automation"},"type_automations:AutomationsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Automation"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"title":"AutomationsListResponse"},"type_automations:AutomationsGetRequestExpandItem":{"type":"string","enum":["stats"],"title":"AutomationsGetRequestExpandItem"},"type_automations:AutomationsGetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:Automation"}},"title":"AutomationsGetResponse"},"type_automations:AutomationEmailStatsEmail":{"type":"object","properties":{"recipients":{"type":"integer","default":0,"description":"Total number of email recipients"},"delivered":{"type":"integer","default":0,"description":"Total number of emails delivered"},"opens":{"type":"integer","default":0,"description":"Total number of email opens"},"unique_opens":{"type":"integer","default":0,"description":"Total number of unique email opens"},"open_rate":{"type":"number","format":"double","description":"The percentage of emails that have been opened"},"clicks":{"type":"integer","default":0,"description":"Total number of email clicks"},"unique_clicks":{"type":"integer","default":0,"description":"Unique number of email clicks"},"click_rate":{"type":"number","format":"double","description":"The percentage of emails that have been clicked"},"unsubscribes":{"type":"integer","default":0,"description":"Total number of email unsubscribes"},"spam_reports":{"type":"integer","default":0,"description":"The number of subscribers that reported this email as spam"}},"description":"Email engagement statistics for an automation email.","title":"AutomationEmailStatsEmail"},"type_automations:AutomationEmailStatsClicks":{"type":"object","properties":{"url":{"type":"string","description":"The URL the stats are for"},"total_clicks":{"type":"integer"},"total_unique_clicks":{"type":"integer"},"total_click_through_rate":{"type":"number","format":"double","description":"The percentage of clicks on the URL compared to the total number of unique opens"}},"title":"AutomationEmailStatsClicks"},"type_automations:AutomationEmailStats":{"type":"object","properties":{"email":{"$ref":"#/components/schemas/type_automations:AutomationEmailStatsEmail","description":"Stats scoped to email recipients"},"clicks":{"type":"array","items":{"$ref":"#/components/schemas/type_automations:AutomationEmailStatsClicks"},"description":"An array of click statistics for each URL in the email"}},"description":"Statistics for an automation email message.","title":"AutomationEmailStats"},"type_automations:AutomationEmail":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the email message"},"automation_step_id":{"type":"string","description":"The unique ID of the automation step this email belongs to"},"subject_line":{"type":"string","description":"The email subject line"},"preview_text":{"type":"string","description":"The email preview text"},"status":{"type":"string","description":"The status of the email message. `active` - The email is active and will be sent. `inactive` - The email is inactive."},"first_sent_at":{"type":"integer","description":"The time the email was first sent. Measured in seconds since the Unix epoch"},"last_sent_at":{"type":"integer","description":"The time the email was last sent. Measured in seconds since the Unix epoch"},"created_at":{"type":"integer","description":"The time the email was created. Measured in seconds since the Unix epoch"},"stats":{"$ref":"#/components/schemas/type_automations:AutomationEmailStats"}},"required":["id","automation_step_id","subject_line","preview_text","status","created_at"],"description":"An email message within an automation.","title":"AutomationEmail"},"type_automations:AutomationEmailsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_automations:AutomationEmail"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"has_more":{"type":"boolean","description":"**Cursor pagination only**: Indicates whether there are more results available after the current page."},"next_cursor":{"type":"string","description":"**Cursor pagination only**: The cursor token to use for fetching the next page of results. This will be null if has_more is false."},"page":{"type":"integer","default":1,"description":"**Offset pagination only**: The page number the results are from. Only present when using deprecated offset-based pagination."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data"],"title":"AutomationEmailsListResponse"},"type_:CustomFieldDataType":{"oneOf":[{"type":"string"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}],"title":"CustomFieldDataType"},"type_:CustomFieldValue":{"type":"object","properties":{"name":{"type":"string","description":"The name of the existing custom field"},"value":{"$ref":"#/components/schemas/type_:CustomFieldDataType","description":"The value stored for the subscription"}},"description":"The object required for setting custom field values on a subscription","title":"CustomFieldValue"},"type_:SubscriptionsCreateRequestTier":{"type":"string","enum":["free","premium"],"description":"The tier for this subscription.","title":"SubscriptionsCreateRequestTier"},"type_ids:OptionalStripeCustomerId":{"type":"string","description":"The prefixed ID of the Stripe customer.","title":"OptionalStripeCustomerId"},"type_ids:ComplimentaryAccessId":{"type":"string","description":"The prefixed ID of the complimentary access object.","title":"ComplimentaryAccessId"},"type_:SubscriptionRequest":{"type":"object","properties":{"email":{"type":"string","description":"The email address of the subscription."},"reactivate_existing":{"type":"boolean","default":false,"description":"Whether or not to reactivate the subscription if they have already unsubscribed. This option should be used only if the subscriber is knowingly resubscribing."},"send_welcome_email":{"type":"boolean","default":false},"utm_source":{"type":"string","description":"The source of the subscription."},"utm_medium":{"type":"string","description":"The medium of the subscription"},"utm_campaign":{"type":"string","description":"The acquisition campaign of the subscription"},"utm_term":{"type":"string","description":"The acquisition term; typically the keyword or search term"},"utm_content":{"type":"string","description":"The acquisition content; typically used for A/B testing or ad variations"},"referring_site":{"type":"string","description":"The website that the subscriber was referred from"},"referral_code":{"type":"string","description":"This should be a subscribers referral_code. This gives referral credit for the new subscription."},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/type_:CustomFieldValue"},"description":"The custom fields must already exist for the publication. Any new custom fields here will be discarded."},"double_opt_override":{"$ref":"#/components/schemas/type_:DoubleOptOverride","description":"Override the publication's default double opt-in settings for this subscription. Possible values are:\n- \"on\" — The subscriber will receive a double opt-in confirmation email and will need to confirm their subscription prior to being marked as active.\n- \"off\" — The subscriber will be marked as active immediately and will not receive a double opt-in confirmation email.\n- \"not_set\" — The publication's default double opt-in settings will be applied to this subscription."},"tier":{"$ref":"#/components/schemas/type_:SubscriptionsCreateRequestTier","description":"The tier for this subscription."},"premium_tiers":{"type":"array","items":{"type":"string"},"description":"An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with `premium_tier_ids` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"premium_tier_ids":{"type":"array","items":{"type":"string"},"description":"An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with `premium_tiers` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter."},"stripe_customer_id":{"$ref":"#/components/schemas/type_ids:OptionalStripeCustomerId","description":"The Stripe customer ID for this subscription."},"automation_ids":{"type":"array","items":{"type":"string"},"description":"Enroll the subscriber into automations after their subscription has been created. Requires the automations to have an active *Add by API* trigger."},"newsletter_list_ids":{"type":"array","items":{"type":"string"},"description":"An array of newsletter list prefixed IDs to subscribe the new subscription to. The newsletter lists must belong to the same publication. <Badge intent=\"warning\" minimal outlined>Beta</Badge>"},"skip_newsletter_list_auto_subscribe":{"type":"boolean","description":"When true, the subscriber will not be auto-subscribed to newsletter lists configured with auto-subscribe. Defaults to false. <Badge intent=\"warning\" minimal outlined>Beta</Badge>"},"complimentary_gift_id":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId","description":"The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication."}},"required":["email"],"title":"SubscriptionRequest"},"type_bulk_subscriptions:BulkSubscriptionCreateResponse":{"type":"object","properties":{"message":{"type":"string","description":"The result of the create request"},"import_id":{"type":"string","description":"The database ID of the import object created from the Bulk Subscription Create request"}},"required":["message","import_id"],"description":"The response containing the import ID","title":"BulkSubscriptionCreateResponse"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponseDataItemType":{"type":"string","enum":["status","bulk"],"description":"The type of update (status or bulk)","title":"BulkSubscriptionUpdatesListResponseDataItemType"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponseDataItemStatus":{"type":"string","enum":["pending","processing","complete","failed"],"description":"The status of the update","title":"BulkSubscriptionUpdatesListResponseDataItemStatus"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponseDataItem":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the update object"},"type":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponseDataItemType","description":"The type of update (status or bulk)"},"params":{"type":"string","description":"The parameters passed in for the update"},"status":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponseDataItemStatus","description":"The status of the update"},"publication_id":{"$ref":"#/components/schemas/type_ids:PublicationId","description":"The publication ID associated with this update"},"failure_reason":{"type":"string","description":"If the job as a whole fails, this will detail the errors encountered"},"completed":{"type":"integer","description":"The timestamp of the job's completion"},"created":{"type":"integer","description":"The timestamp of the job's creation"},"updated":{"type":"integer","description":"The timestamp of the job's update"},"error_log":{"type":"array","items":{"type":"string"},"description":"An array of errors encountered for individual updates within the job"}},"title":"BulkSubscriptionUpdatesListResponseDataItem"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponseDataItem"},"description":"An array of Subscription Update objects"}},"title":"BulkSubscriptionUpdatesListResponse"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponseDataType":{"type":"string","enum":["bulk","status"],"description":"The type of update (status or bulk)","title":"BulkSubscriptionUpdatesGetResponseDataType"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponseDataStatus":{"type":"string","enum":["pending","processing","complete","failed"],"description":"The status of the update","title":"BulkSubscriptionUpdatesGetResponseDataStatus"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponseData":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the update object"},"type":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponseDataType","description":"The type of update (status or bulk)"},"params":{"type":"string","description":"The parameters passed in for the update"},"status":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponseDataStatus","description":"The status of the update"},"publication_id":{"$ref":"#/components/schemas/type_ids:PublicationId","description":"The publication ID associated with this update"},"failure_reason":{"type":"string","description":"If the job as a whole fails, this will detail the errors encountered"},"completed":{"type":"integer","description":"The timestamp of the job's completion"},"created":{"type":"integer","description":"The timestamp of the job's creation"},"updated":{"type":"integer","description":"The timestamp of the job's update"},"error_log":{"type":"array","items":{"type":"string"},"description":"An array of errors encountered for individual updates within the job"}},"title":"BulkSubscriptionUpdatesGetResponseData"},"type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponseData"}},"title":"BulkSubscriptionUpdatesGetResponse"},"type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItemTier":{"type":"string","enum":["free","premium"],"description":"The Tier of the Subscription (not required)","title":"SubscriptionsPatchRequestSubscriptionsItemTier"},"type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem":{"type":"object","properties":{"name":{"type":"string","description":"The display value of the custom field"},"value":{"$ref":"#/components/schemas/type_:CustomFieldDataType","description":"The value of the custom field"},"delete":{"type":"boolean","description":"A boolean value to specify whether to delete this custom field entry from the subscription"}},"title":"SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem"},"type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItem":{"type":"object","properties":{"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId"},"tier":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItemTier","description":"The Tier of the Subscription (not required)"},"stripe_customer_id":{"$ref":"#/components/schemas/type_ids:OptionalStripeCustomerId","description":"The Stripe Customer ID of the subscription (not required)"},"unsubscribe":{"type":"boolean","description":"A boolean value specifying whether to unsubscribe this subscription from the publication (not required)"},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItemCustomFieldsItem"},"description":"An array of custom field objects to update"},"complimentary_gift_id":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId","description":"The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication."}},"required":["subscription_id"],"title":"SubscriptionsPatchRequestSubscriptionsItem"},"type_subscriptions:SubscriptionsPatchResponseData":{"type":"object","properties":{"subscription_update_id":{"type":"string","description":"The ID of the Subscription Update object responsible for handling the update job"}},"title":"SubscriptionsPatchResponseData"},"type_subscriptions:SubscriptionsPatchResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_subscriptions:SubscriptionsPatchResponseData"}},"required":["data"],"title":"SubscriptionsPatchResponse"},"type_complimentaryAccess:ComplimentaryAccessTimeUnit":{"type":"string","enum":["days","months","years","forever"],"description":"The unit of time for the gift duration.<br>`days` - Duration in days.<br>`months` - Duration in months.<br>`years` - Duration in years.<br>`forever` - Lifetime access with no expiration.","title":"ComplimentaryAccessTimeUnit"},"type_ids:TierId":{"type":"string","description":"The prefixed ID of the tier.","title":"TierId"},"type_tiers:TierStatus":{"type":"string","enum":["active","archived"],"description":"Returns whether or not the tier has any active prices.","title":"TierStatus"},"type_tiers:TierStats":{"type":"object","properties":{"active_subscriptions":{"type":"integer","description":"Total number of active subscriptions belonging to this tier."}},"required":["active_subscriptions"],"description":"Optional list of stats for a tier. Retrievable by including `expand: [stats]` in the tier request body.","title":"TierStats"},"type_ids:PriceId":{"type":"string","description":"The prefixed ID of the price.","title":"PriceId"},"type_tiers:TierPriceCurrency":{"type":"string","enum":["usd","aud","cad","eur","gbp","inr","brl","mxn","nzd","dkk"],"title":"TierPriceCurrency"},"type_tiers:TierPriceInterval":{"type":"string","enum":["month","quarter","year","one_time","donation"],"title":"TierPriceInterval"},"type_tiers:TierPrice":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PriceId"},"currency":{"$ref":"#/components/schemas/type_tiers:TierPriceCurrency"},"amount_cents":{"type":"integer"},"enabled":{"type":"boolean","default":true},"interval":{"$ref":"#/components/schemas/type_tiers:TierPriceInterval"},"denominator":{"type":"string"},"cta":{"type":"string","description":"When using the external Stripe checkout, this text will be displayed on the button"},"features":{"type":"array","items":{"type":"string"}}},"description":"Price belonging to a Tier","title":"TierPrice"},"type_tiers:Tier":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:TierId"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/type_tiers:TierStatus","description":"Returns whether or not the tier has any active prices."},"description":{"type":"string","default":"Super engaged readers"},"stats":{"$ref":"#/components/schemas/type_tiers:TierStats"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/type_tiers:TierPrice"},"description":"Optional list of prices for a tier. Retrievable by including `expand: [prices]` in the tier request body."}},"required":["id","name","status"],"description":"The subscription tier object.","title":"Tier"},"type_complimentaryAccess:ComplimentaryAccessStats":{"type":"object","properties":{"total_granted":{"type":"integer","description":"Total number of subscriptions that have ever been granted this complimentary access."},"active_granted":{"type":"integer","description":"Number of subscriptions currently within an active complimentary access period."}},"required":["total_granted","active_granted"],"description":"Optional stats for a complimentary access object. Retrievable by including `expand: [stats]` in the request.","title":"ComplimentaryAccessStats"},"type_complimentaryAccess:ComplimentaryAccess":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:ComplimentaryAccessId","description":"The prefixed ID of the complimentary access object."},"duration":{"type":"integer","description":"The duration of the gift. Null when time_unit is \"forever\"."},"time_unit":{"$ref":"#/components/schemas/type_complimentaryAccess:ComplimentaryAccessTimeUnit","description":"The unit of time for the gift duration."},"description":{"type":"string","description":"A human-readable description of the gift (e.g., \"3 Months Gift\", \"Lifetime Gift\")."},"tier_id":{"$ref":"#/components/schemas/type_ids:TierId","description":"The prefixed ID of the associated tier. Always present."},"tier":{"$ref":"#/components/schemas/type_tiers:Tier","description":"The full tier object. Present when `expand: [tier]` is requested. Returned alongside `tier_id`."},"stats":{"$ref":"#/components/schemas/type_complimentaryAccess:ComplimentaryAccessStats","description":"Stats for this complimentary access. Retrievable by including `expand: [stats]` in the request."}},"required":["id","time_unit","description"],"description":"The complimentary access object.","title":"ComplimentaryAccess"},"type_complimentaryAccess:IndexComplimentaryAccessResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_complimentaryAccess:ComplimentaryAccess"}},"limit":{"type":"integer","description":"The limit placed on the results. Defaults to 10 if not specified."},"has_more":{"type":"boolean","description":"Indicates whether there are more results available after the current page."},"next_cursor":{"type":"string","description":"The cursor token to use for fetching the next page of results. This will be null if has_more is false."},"total_results":{"type":"integer","description":"The total number of results from all pages."}},"required":["data"],"title":"IndexComplimentaryAccessResponse"},"type_complimentaryAccess:ComplimentaryAccessResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_complimentaryAccess:ComplimentaryAccess"}},"title":"ComplimentaryAccessResponse"},"type_conditionSets:ConditionSetPurpose":{"type":"string","enum":["dynamic_content"],"description":"The purpose of the condition set, indicating its intended use.","title":"ConditionSetPurpose"},"type_conditionSets:ConditionSetStatus":{"type":"string","enum":["active","archived"],"title":"ConditionSetStatus"},"type_conditionSets:ConditionSetListItem":{"type":"object","properties":{"id":{"type":"string","description":"The UUID of the condition set."},"name":{"type":"string","description":"The display name of the condition set."},"status":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetStatus","description":"Whether the condition set is currently active or has been archived."},"created":{"type":"integer","description":"The time the condition set was created. Measured in seconds since the Unix epoch."},"updated":{"type":"integer","description":"The time the condition set was last updated. Measured in seconds since the Unix epoch."},"purpose":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetPurpose","description":"The purpose of the condition set, indicating its intended use."}},"required":["id","name","status","created","updated","purpose"],"title":"ConditionSetListItem"},"type_conditionSets:ConditionSetsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetListItem"},"description":"An array of condition sets."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"has_more":{"type":"boolean","description":"**Cursor pagination only**: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination."},"next_cursor":{"type":"string","description":"**Cursor pagination only**: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination."},"total_results":{"type":"integer","description":"The total number of results from all pages."}},"required":["data"],"title":"ConditionSetsListResponse"},"type_conditionSets:ConditionSetShowExpandItems":{"type":"string","enum":["stats"],"title":"ConditionSetShowExpandItems"},"type_conditionSets:ConditionSetStats":{"type":"object","properties":{"active_subscriber_count":{"type":"integer","description":"Count of active subscribers matching this condition set, calculated synchronously at request time."}},"required":["active_subscriber_count"],"title":"ConditionSetStats"},"type_conditionSets:ConditionSet":{"type":"object","properties":{"id":{"type":"string","description":"The UUID of the condition set."},"name":{"type":"string","description":"The display name of the condition set."},"status":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetStatus","description":"Whether the condition set is currently active or has been archived."},"created":{"type":"integer","description":"The time the condition set was created. Measured in seconds since the Unix epoch."},"updated":{"type":"integer","description":"The time the condition set was last updated. Measured in seconds since the Unix epoch."},"purpose":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetPurpose","description":"The purpose of the condition set, indicating its intended use."},"stats":{"$ref":"#/components/schemas/type_conditionSets:ConditionSetStats","description":"Subscriber count statistics for the condition set. Included when `expand[]=stats` is specified in the request."}},"required":["id","name","status","created","updated","purpose"],"title":"ConditionSet"},"type_conditionSets:ConditionSetShowResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_conditionSets:ConditionSet"}},"required":["data"],"title":"ConditionSetShowResponse"},"type_:CustomFieldType":{"type":"string","enum":["string","integer","boolean","date","datetime","list","double"],"description":"The type of value being stored in the custom field.","title":"CustomFieldType"},"type_customFields:CustomFieldInfo":{"type":"object","properties":{"id":{"type":"string"},"kind":{"$ref":"#/components/schemas/type_:CustomFieldType"},"display":{"type":"string"},"created":{"type":"integer"},"options":{"type":"array","items":{"type":"string"},"description":"Array of option values. Only included when kind is \"list\"."}},"title":"CustomFieldInfo"},"type_customFields:CustomFieldResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_customFields:CustomFieldInfo"}},"title":"CustomFieldResponse"},"type_customFields:CustomFieldIndexResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_customFields:CustomFieldInfo"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"title":"CustomFieldIndexResponse"},"type_customFields:CustomFieldsPatchResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_customFields:CustomFieldInfo"}},"title":"CustomFieldsPatchResponse"},"type_customFields:CustomFieldsDeleteResponse":{"type":"object","properties":{"message":{"type":"string"}},"title":"CustomFieldsDeleteResponse"},"type_dataDeletion:DataDeletionRequestStatus":{"type":"string","enum":["pending","processing","completed","failed","canceled"],"description":"The current status of the data deletion request.","title":"DataDeletionRequestStatus"},"type_dataDeletion:DataDeletionRequestSource":{"type":"string","enum":["zendesk","retool","website","app","public_api","other"],"description":"The source from which the deletion request was created.","title":"DataDeletionRequestSource"},"type_dataDeletion:DataDeletionRequestInfo":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestStatus"},"source":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestSource"},"requested_at":{"type":"string"},"scheduled_for_processing_at":{"type":"string"},"completed_at":{"type":"string"},"created_at":{"type":"string"}},"title":"DataDeletionRequestInfo"},"type_dataDeletion:DataDeletionRequestResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestInfo"}},"title":"DataDeletionRequestResponse"},"type_dataDeletion:DataDeletionRequestIndexResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_dataDeletion:DataDeletionRequestInfo"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"has_more":{"type":"boolean","description":"Whether there are more results available after this page."},"next_cursor":{"type":"string","description":"The cursor to use for the next page of results."}},"title":"DataDeletionRequestIndexResponse"},"type_engagements:NumberOfDays":{"type":"integer","title":"NumberOfDays"},"type_engagements:PublicationEngagementGranularity":{"type":"string","enum":["day","week","month"],"title":"PublicationEngagementGranularity"},"type_engagements:PublicationEngagementEmailType":{"type":"string","enum":["all","post","message"],"title":"PublicationEngagementEmailType"},"type_:RequestDirection":{"type":"string","enum":["asc","desc"],"default":"asc","description":"The direction of the request. Defaults to `asc`.","title":"RequestDirection"},"type_engagements:PublicationEngagementMetrics":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"The starting date of the period for which the engagement metrics are reported based on the selected granularity.<br><br> `day` granularity: The specific day.<br> `week` granularity: The Monday of the week.<br> `month` granularity: The first day of the month."},"total_opens":{"type":"integer","description":"The total number of times emails were opened during the period."},"unique_opens":{"type":"integer","description":"The number of unique subscribers who opened emails during the period."},"total_clicks":{"type":"integer","description":"The total number of times links were clicked during the period."},"total_verified_clicks":{"type":"integer","description":"The total number of times links were clicked, during the period, as <a href=\"https://www.beehiiv.com/support/article/28404633659159-introducing-verified-clicks-accurate-email-engagement-metrics?srsltid=AfmBOoregRzZ1N6bcwITVRA-Lo6NE06y6xNwb7WO85Gv0mrWMij-yFgb\">verified by our system</a>."},"unique_clicks":{"type":"integer","description":"The number of unique subscribers who clicked links during the period."},"unique_verified_clicks":{"type":"integer","description":"The number of times links were clicked by unique subscribers, during the period, as <a href=\"https://www.beehiiv.com/support/article/28404633659159-introducing-verified-clicks-accurate-email-engagement-metrics?srsltid=AfmBOoregRzZ1N6bcwITVRA-Lo6NE06y6xNwb7WO85Gv0mrWMij-yFgb\">verified by our system</a>."}},"required":["date","total_opens","unique_opens","total_clicks","total_verified_clicks","unique_clicks","unique_verified_clicks"],"title":"PublicationEngagementMetrics"},"type_engagements:PublicationEngagementsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_engagements:PublicationEngagementMetrics"},"description":"The list of engagement metrics for the publication within the specified date range and granularity. Returns an empty list if there is no engagement data for the specified period."},"publication_id":{"$ref":"#/components/schemas/type_ids:PublicationId","description":"The unique identifier of the publication. Passed as a path parameter in the request."},"granularity":{"$ref":"#/components/schemas/type_engagements:PublicationEngagementGranularity","description":"The granularity at which the engagement metrics are reported."},"email_type":{"$ref":"#/components/schemas/type_engagements:PublicationEngagementEmailType","description":"The email type filter applied to the engagement metrics. Defaults to `all`."},"start_date":{"type":"string","format":"date","description":"The starting date of the engagement metrics."},"number_of_days":{"$ref":"#/components/schemas/type_engagements:NumberOfDays","description":"The number of days of engagement metrics returned."}},"required":["data","publication_id","granularity","email_type","start_date","number_of_days"],"title":"PublicationEngagementsResponse"},"type_ids:NewsletterListId":{"type":"string","description":"The prefixed ID of the newsletter list.","title":"NewsletterListId"},"type_newsletterLists:NewsletterListStatus":{"type":"string","enum":["draft","active","archived"],"description":"The status of the newsletter list.","title":"NewsletterListStatus"},"type_newsletterLists:NewsletterListInfo":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:NewsletterListId","description":"The prefixed ID of the newsletter list."},"name":{"type":"string","description":"The name of the newsletter list."},"slug":{"type":"string","description":"The URL-friendly slug of the newsletter list."},"description":{"type":"string","description":"A description of the newsletter list."},"status":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListStatus","description":"The status of the newsletter list."},"auto_subscribe":{"type":"boolean","description":"Whether new subscribers are automatically subscribed to this list."},"subscriber_count":{"type":"integer","description":"The number of active subscribers on this list."},"created_at":{"type":"integer","description":"The time the newsletter list was created. Measured in seconds since the Unix epoch."},"updated_at":{"type":"integer","description":"The time the newsletter list was last updated. Measured in seconds since the Unix epoch."}},"required":["id","name","slug","status","auto_subscribe","subscriber_count","created_at","updated_at"],"title":"NewsletterListInfo"},"type_newsletterLists:NewsletterListIndexResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListInfo"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"NewsletterListIndexResponse"},"type_newsletterLists:NewsletterListResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_newsletterLists:NewsletterListInfo"}},"required":["data"],"title":"NewsletterListResponse"},"type_newsletterLists:NewsletterListWritableStatus":{"type":"string","enum":["active","archived"],"description":"Valid status values when updating a newsletter list. draft is not permitted.","title":"NewsletterListWritableStatus"},"type_ids:NewsletterListSubscriptionId":{"type":"string","description":"The prefixed ID of the newsletter list subscription.","title":"NewsletterListSubscriptionId"},"type_newsletterListSubscriptions:NewsletterListSubscriptionStatus":{"type":"string","enum":["pending","active","inactive","paused"],"description":"The status of the newsletter list subscription.","title":"NewsletterListSubscriptionStatus"},"type_newsletterListSubscriptions:NewsletterListSubscriptionInfo":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:NewsletterListSubscriptionId","description":"The prefixed ID of the newsletter list subscription."},"newsletter_list_id":{"$ref":"#/components/schemas/type_ids:NewsletterListId","description":"The prefixed ID of the newsletter list."},"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId","description":"The prefixed ID of the subscription."},"status":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionStatus","description":"The status of the newsletter list subscription."},"subscribed_at":{"type":"integer","description":"The time the subscription was activated. Measured in seconds since the Unix epoch."},"unsubscribed_at":{"type":"integer","description":"The time the subscription was deactivated. Measured in seconds since the Unix epoch."},"created_at":{"type":"integer","description":"The time the newsletter list subscription was created. Measured in seconds since the Unix epoch."}},"required":["id","newsletter_list_id","subscription_id","status","created_at"],"title":"NewsletterListSubscriptionInfo"},"type_newsletterListSubscriptions:NewsletterListSubscriptionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionInfo"}},"required":["data"],"title":"NewsletterListSubscriptionResponse"},"type_newsletterListSubscriptions:NewsletterListSubscriptionIndexResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_newsletterListSubscriptions:NewsletterListSubscriptionInfo"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"has_more":{"type":"boolean","description":"**Cursor pagination only**: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination."},"next_cursor":{"type":"string","description":"**Cursor pagination only**: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination."},"total_results":{"type":"integer","description":"The total number of results from all pages."}},"required":["data"],"title":"NewsletterListSubscriptionIndexResponse"},"type_oauth_users:UserIdentifyResponse":{"type":"object","properties":{"first_name":{"type":"string","description":"The first name of the user."},"last_name":{"type":"string","description":"The last name of the user."},"email":{"type":"string","description":"The email address of the user."},"profile_picture":{"type":"string","description":"URL to the user's profile picture."}},"description":"Response containing information about the authenticated user.","title":"UserIdentifyResponse"},"type_polls:PollOrderBy":{"type":"string","enum":["created","name"],"default":"created","title":"PollOrderBy"},"type_polls:PollsExpandItems":{"type":"string","enum":["stats","poll_responses","trivia_answer"],"title":"PollsExpandItems"},"type_ids:PollId":{"type":"string","description":"The prefixed ID of the poll.","title":"PollId"},"type_polls:PollType":{"type":"string","enum":["voting","trivia"],"title":"PollType"},"type_polls:PollStatus":{"type":"string","enum":["draft","published"],"title":"PollStatus"},"type_polls:PollChoice":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the poll choice."},"label":{"type":"string","description":"The text label for this choice."}},"required":["id","label"],"title":"PollChoice"},"type_polls:PollStats":{"type":"object","properties":{"completions":{"type":"integer","description":"The total number of responses to this poll."},"vote_counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"A map of poll choice labels to the number of votes each choice received."}},"required":["completions","vote_counts"],"title":"PollStats"},"type_polls:PollResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the poll response."},"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId","description":"The prefixed ID of the subscription that responded. Null if the subscription has been permanently deleted."},"subscription_deleted":{"type":"boolean","description":"Whether the associated subscription has been deleted or permanently removed."},"poll_choice_id":{"type":"string","description":"The UUID of the poll choice selected."},"poll_choice_label":{"type":"string","description":"The text label of the poll choice selected."},"created_at":{"type":"integer","description":"The time the response was created. Measured in seconds since the Unix epoch."},"extended_feedback":{"type":"string","description":"Optional extended feedback provided by the subscriber."},"post_id":{"type":"string","description":"The prefixed ID of the post where the response was collected. Only included when `expand[]=post` is specified."},"post_title":{"type":"string","description":"The title of the post where the response was collected. Only included when `expand[]=post` is specified."},"post_publish_date":{"type":"integer","description":"The scheduled publication date of the post where the response was collected. Measured in seconds since the Unix epoch. Only included when `expand[]=post` is specified. Null if the post is not yet scheduled."}},"required":["id","subscription_deleted","poll_choice_id","created_at"],"title":"PollResponseItem"},"type_polls:Poll":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PollId","description":"The prefixed ID of the poll."},"name":{"type":"string","description":"The name of the poll."},"question":{"type":"string","description":"The poll question text."},"description":{"type":"string","description":"An optional description of the poll."},"poll_type":{"$ref":"#/components/schemas/type_polls:PollType","description":"The type of poll."},"status":{"$ref":"#/components/schemas/type_polls:PollStatus","description":"The current status of the poll."},"created_at":{"type":"integer","description":"The time the poll was created. Measured in seconds since the Unix epoch."},"poll_choices":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:PollChoice"},"description":"The available choices for this poll."},"trivia_answer":{"type":"string","description":"The correct answer for trivia-type polls. Only included when `expand[]=trivia_answer` is specified and the poll is of type trivia."},"stats":{"$ref":"#/components/schemas/type_polls:PollStats","description":"Aggregate statistics for the poll. Only included when `expand[]=stats` is specified."},"total_responses":{"type":"integer","description":"Total number of responses to this poll. Only included when `expand[]=poll_responses` is specified."},"poll_responses":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:PollResponseItem"},"description":"Up to 10 most recent subscriber responses. Only included when `expand[]=poll_responses` is specified. Use /polls/{pollId}/responses for paginated access to all responses."}},"required":["id","name","question","poll_type","status","created_at","poll_choices"],"title":"Poll"},"type_polls:PollsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:Poll"},"description":"An array of polls."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"**Offset pagination only**: The page number the results are from. Only present when using deprecated offset-based pagination."},"total_pages":{"type":"integer","description":"**Offset pagination only**: The total number of pages. Only present when using deprecated offset-based pagination."},"has_more":{"type":"boolean","description":"**Cursor pagination only**: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination."},"next_cursor":{"type":"string","description":"**Cursor pagination only**: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination."},"total_results":{"type":"integer","description":"The total number of results from all pages."}},"required":["data"],"title":"PollsListResponse"},"type_polls:PollShowResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_polls:Poll"}},"required":["data"],"title":"PollShowResponse"},"type_polls:PollResponsesOrderBy":{"type":"string","enum":["created"],"default":"created","title":"PollResponsesOrderBy"},"type_polls:PollResponsesExpandItems":{"type":"string","enum":["post"],"title":"PollResponsesExpandItems"},"type_polls:PollResponsesListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_polls:PollResponseItem"},"description":"An array of poll responses."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"**Offset pagination only**: The page number the results are from. Only present when using deprecated offset-based pagination."},"total_pages":{"type":"integer","description":"**Offset pagination only**: The total number of pages. Only present when using deprecated offset-based pagination."},"has_more":{"type":"boolean","description":"**Cursor pagination only**: Indicates whether there are more results available after the current page."},"next_cursor":{"type":"string","description":"**Cursor pagination only**: The cursor token to use for fetching the next page of results."},"total_results":{"type":"integer","description":"The total number of results from all pages."}},"required":["data"],"title":"PollResponsesListResponse"},"type_posts:BorderStyle":{"type":"string","enum":["solid","dashed","dotted"],"title":"BorderStyle"},"type_posts:VisualSettings":{"type":"object","properties":{"background_color":{"type":"string","description":"The background color of the block."},"text_color":{"type":"string","description":"The text color of the block."},"border_color":{"type":"string","description":"The border color of the block."},"border_style":{"$ref":"#/components/schemas/type_posts:BorderStyle","description":"The border style of the block."},"border_width":{"type":"integer","description":"The border width of the block."},"border_width_top":{"type":"integer","description":"The border width of the top of the block."},"border_width_bottom":{"type":"integer","description":"The border width of the bottom of the block."},"border_width_left":{"type":"integer","description":"The border width of the left of the block."},"border_width_right":{"type":"integer","description":"The border width of the right of the block."},"border_radius":{"type":"integer","description":"The border radius of the block."},"border_radius_top_left":{"type":"integer","description":"The border radius of the top left of the block."},"border_radius_top_right":{"type":"integer","description":"The border radius of the top right of the block."},"border_radius_bottom_left":{"type":"integer","description":"The border radius of the bottom left of the block."},"border_radius_bottom_right":{"type":"integer","description":"The border radius of the bottom right of the block."},"inner_spacing":{"type":"integer","description":"The inner spacing of the block."},"inner_spacing_top":{"type":"integer","description":"The inner spacing of the top of the block."},"inner_spacing_bottom":{"type":"integer","description":"The inner spacing of the bottom of the block."},"inner_spacing_left":{"type":"integer","description":"The inner spacing of the left of the block."},"inner_spacing_right":{"type":"integer","description":"The inner spacing of the right of the block."},"outer_spacing":{"type":"integer","description":"The outer spacing of the block."},"outer_spacing_top":{"type":"integer","description":"The outer spacing of the top of the block."},"outer_spacing_bottom":{"type":"integer","description":"The outer spacing of the bottom of the block."},"outer_spacing_left":{"type":"integer","description":"The outer spacing of the left of the block."},"outer_spacing_right":{"type":"integer","description":"The outer spacing of the right of the block."}},"title":"VisualSettings"},"type_posts:ReferralCondition":{"type":"string","enum":["eq","gt","lt"],"title":"ReferralCondition"},"type_posts:ConditionSetOperator":{"type":"string","enum":["and","or"],"description":"How multiple condition sets are combined when evaluating dynamic content targeting.","title":"ConditionSetOperator"},"type_posts:VisibilitySettings":{"type":"object","properties":{"show_on_web":{"type":"boolean","description":"Whether to show the block on the web."},"show_on_email":{"type":"boolean","description":"Whether to show the block on the email."},"show_to_anonymous_users_web":{"type":"boolean","description":"Whether to show the block to anonymous users on the web."},"show_to_free_subscribers":{"type":"boolean","description":"Whether to show the block to free subscribers."},"show_to_paid_subscribers":{"type":"boolean","description":"Whether to show the block to paid subscribers."},"show_to_subscribers_with_referral_value":{"type":"integer","description":"The exact referral count required to show the block to subscribers."},"show_to_subscribers_with_referral_condition":{"$ref":"#/components/schemas/type_posts:ReferralCondition","description":"The condition required to show the block to subscribers."},"condition_set_ids":{"type":"array","items":{"type":"string"},"description":"An optional list of condition set UUIDs to gate this block behind dynamic content targeting. When provided, only subscribers matching the specified condition sets will see this block. Condition sets must belong to the same publication and be active."},"condition_set_operator":{"$ref":"#/components/schemas/type_posts:ConditionSetOperator","description":"Instructs how to combine multiple condition sets. Defaults to \"or\" (subscriber can match any condition). Use \"and\" to show the block if the subscriber meets all conditions."}},"title":"VisibilitySettings"},"type_posts:ParagraphBlockTextStyle":{"type":"string","enum":["bold","italic","underline","strikethrough"],"description":"Inline formatting to apply to a formatted text section. `strikethrough` renders as a strike mark.","title":"ParagraphBlockTextStyle"},"type_posts:Link":{"type":"object","properties":{"href":{"type":"string","description":"The URL of the link."},"target":{"type":"string","description":"The target of the link (e.g., _blank)."}},"required":["href"],"title":"Link"},"type_posts:ParagraphBlockTextSection":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the paragraph."},"styling":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ParagraphBlockTextStyle"},"description":"The inline styles for the text."},"text_color":{"type":"string","description":"The CSS color value for the text."},"highlight_color":{"type":"string","description":"The CSS color value for the text highlight."},"link":{"$ref":"#/components/schemas/type_posts:Link","description":"The link of the text."}},"required":["text"],"title":"ParagraphBlockTextSection"},"type_posts:TextAlignment":{"type":"string","enum":["left","center","right"],"description":"The text alignment of the content.","title":"TextAlignment"},"type_posts:Sizes":{"type":"string","enum":["small","normal","large"],"description":"The sizes of the button.","title":"Sizes"},"type_posts:HeadingLevel":{"type":"string","enum":["1","2","3","4","5","6"],"description":"The level of the header.","title":"HeadingLevel"},"type_ids:ExternalRssFeedId":{"type":"string","description":"The prefixed ID of the external RSS feed.","title":"ExternalRssFeedId"},"type_posts:RssBlockLayout":{"type":"string","enum":["1-col","2-col","3-col","4-col"],"description":"The layout of the articles from the feed.","title":"RssBlockLayout"},"type_posts:RssCtaStyle":{"type":"string","enum":["CTA button","CTA link","Title as link","Thumbnail as link","Title and thumbnail as link"],"description":"The style of the call to action.","title":"RssCtaStyle"},"type_posts:RssCtaAlignment":{"type":"string","enum":["Left","Center","Right"],"description":"The alignment of the call to action.","title":"RssCtaAlignment"},"type_posts:RssThumbnailPosition":{"type":"string","enum":["Above Title","Below Title","Left of content","Right of content","Alternating Horizontally"],"description":"The position of the thumbnail.","title":"RssThumbnailPosition"},"type_posts:AutomatedAdvertisementKind":{"type":"string","enum":["primary","secondary"],"title":"AutomatedAdvertisementKind"},"type_posts:ColumnPosition":{"type":"string","enum":["left","right"],"title":"ColumnPosition"},"type_posts:ColumnVerticalAlignment":{"type":"string","enum":["top","middle","bottom"],"title":"ColumnVerticalAlignment"},"type_posts:EmbeddableBlocks":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["paragraph"],"description":"Discriminator value: paragraph"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"plaintext":{"type":"string","description":"The plaintext content of the paragraph."},"formattedText":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ParagraphBlockTextSection"},"description":"The formatted content of the paragraph."},"textAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the paragraph (e.g., left, center, right)."},"textAlign":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"Legacy paragraph alignment field. Use `textAlignment` for new integrations."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Discriminator value: image"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"imageUrl":{"type":"string","description":"The URL of the image."},"url":{"type":"string","description":"The URL that the image should link to."},"title":{"type":"string","description":"The title of the image."},"alt_text":{"type":"string","description":"Alternative text for the image."},"caption":{"type":"string","description":"A caption for the image."},"imageAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the image."},"captionAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the caption."},"width":{"type":"integer","description":"The width of the image. Should be between 1 and 100."}},"required":["type","imageUrl"]},{"type":"object","properties":{"type":{"type":"string","enum":["button"],"description":"Discriminator value: button"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"href":{"type":"string","description":"The URL the button should use."},"text":{"type":"string","description":"The text content of the button."},"target":{"type":"string","description":"The target of the button (e.g., _blank)."},"alignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the button."},"size":{"$ref":"#/components/schemas/type_posts:Sizes","description":"The size of the button (e.g., small, normal, large)."}},"required":["type","href","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["heading"],"description":"Discriminator value: heading"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"level":{"$ref":"#/components/schemas/type_posts:HeadingLevel","description":"The level of the header (e.g., 1, 2, 3, etc.)."},"textAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the header (e.g., left, center, right)."},"text":{"type":"string","description":"The text content of the header."},"anchorHeader":{"type":"boolean","default":true,"description":"Whether the header should be an anchor header."},"anchorIncludeInToc":{"type":"boolean","default":true,"description":"Whether the header should be included in the table of contents."}},"required":["type","level","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["rss"],"description":"Discriminator value: rss"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"externalRssFeedId":{"$ref":"#/components/schemas/type_ids:ExternalRssFeedId","description":"The ID of the external RSS feed."},"rssFeedUrl":{"type":"string","description":"The URL of the RSS feed."},"articleLayout":{"$ref":"#/components/schemas/type_posts:RssBlockLayout","description":"The layout of the articles from the feed."},"articlesToShow":{"type":"integer","description":"The number of articles to show from the feed."},"showCta":{"type":"boolean","description":"Whether to show a call to action."},"ctaText":{"type":"string","description":"The text of the call to action. Applicable if ctaStyle is button or link."},"ctaStyle":{"$ref":"#/components/schemas/type_posts:RssCtaStyle","description":"The style of the call to action."},"ctaAlignment":{"$ref":"#/components/schemas/type_posts:RssCtaAlignment","description":"The alignment of the call to action."},"refreshOnSend":{"type":"boolean","description":"Whether or not to refresh the contents from the RSS feed before sending out the email."},"showArticleTitle":{"type":"boolean","description":"Whether to show the article title."},"showArticleThumbnail":{"type":"boolean","description":"Whether to show the article thumbnail."},"thumbnailPosition":{"$ref":"#/components/schemas/type_posts:RssThumbnailPosition","description":"The position of the thumbnail."},"showAuthor":{"type":"boolean","description":"Whether to show the author."},"showPublishedDate":{"type":"boolean","description":"Whether to show the date the article was published"},"showCategories":{"type":"boolean","description":"Whether to show the categories."},"showDescription":{"type":"boolean","description":"Whether to show the article description."},"showContent":{"type":"boolean","description":"Whether to show the article content."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["advertisement"],"description":"Discriminator value: advertisement"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"opportunity_id":{"type":"string","description":"The ID of the Advertisement opportunity."}},"required":["type","opportunity_id"]}],"discriminator":{"propertyName":"type"},"description":"A block in the post content that can be embedded within a column.","title":"EmbeddableBlocks"},"type_posts:ColumnBlock":{"type":"object","properties":{"position":{"$ref":"#/components/schemas/type_posts:ColumnPosition","description":"The column position. This field is deprecated but supported for existing column layouts."},"width":{"type":"integer","description":"The column width percentage. When omitted, width is calculated automatically."},"verticalAlign":{"$ref":"#/components/schemas/type_posts:ColumnVerticalAlignment","description":"The vertical alignment of the column content."},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:EmbeddableBlocks"},"description":"The blocks that make up the column."}},"required":["blocks"],"title":"ColumnBlock"},"type_posts:ListBlockItemData":{"type":"object","properties":{"text":{"type":"string","description":"The plain text content of the list item."},"formattedText":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ParagraphBlockTextSection"},"description":"The formatted content of the list item."}},"title":"ListBlockItemData"},"type_posts:ListBlockItem":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/type_posts:ListBlockItemData"}],"description":"A list item as either plain text or formatted text data.","title":"ListBlockItem"},"type_posts:ListType":{"type":"string","enum":["ordered","unordered"],"description":"The type of list (e.g., ordered, unordered).","title":"ListType"},"type_posts:TableCellData":{"type":"object","properties":{"text":{"type":"string","description":"The text content of the cell."},"formattedText":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ParagraphBlockTextSection"},"description":"The formatted content of the cell."},"alignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the cell."},"colspan":{"type":"integer","default":1,"description":"The number of columns the cell spans."},"rowspan":{"type":"integer","default":1,"description":"The number of rows the cell spans."}},"title":"TableCellData"},"type_posts:QuoteVariant":{"type":"string","enum":["block","inline","quotation"],"description":"The variant of the quote block.","title":"QuoteVariant"},"type_ids:PaywallId":{"type":"string","description":"The prefixed ID of the paywall.","title":"PaywallId"},"type_posts:Block":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["paragraph"],"description":"Discriminator value: paragraph"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"plaintext":{"type":"string","description":"The plaintext content of the paragraph."},"formattedText":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ParagraphBlockTextSection"},"description":"The formatted content of the paragraph."},"textAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the paragraph (e.g., left, center, right)."},"textAlign":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"Legacy paragraph alignment field. Use `textAlignment` for new integrations."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Discriminator value: image"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"imageUrl":{"type":"string","description":"The URL of the image."},"url":{"type":"string","description":"The URL that the image should link to."},"title":{"type":"string","description":"The title of the image."},"alt_text":{"type":"string","description":"Alternative text for the image."},"caption":{"type":"string","description":"A caption for the image."},"imageAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the image."},"captionAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the caption."},"width":{"type":"integer","description":"The width of the image. Should be between 1 and 100."}},"required":["type","imageUrl"]},{"type":"object","properties":{"type":{"type":"string","enum":["button"],"description":"Discriminator value: button"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"href":{"type":"string","description":"The URL the button should use."},"text":{"type":"string","description":"The text content of the button."},"target":{"type":"string","description":"The target of the button (e.g., _blank)."},"alignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the button."},"size":{"$ref":"#/components/schemas/type_posts:Sizes","description":"The size of the button (e.g., small, normal, large)."}},"required":["type","href","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["heading"],"description":"Discriminator value: heading"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"level":{"$ref":"#/components/schemas/type_posts:HeadingLevel","description":"The level of the header (e.g., 1, 2, 3, etc.)."},"textAlignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the header (e.g., left, center, right)."},"text":{"type":"string","description":"The text content of the header."},"anchorHeader":{"type":"boolean","default":true,"description":"Whether the header should be an anchor header."},"anchorIncludeInToc":{"type":"boolean","default":true,"description":"Whether the header should be included in the table of contents."}},"required":["type","level","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["rss"],"description":"Discriminator value: rss"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"externalRssFeedId":{"$ref":"#/components/schemas/type_ids:ExternalRssFeedId","description":"The ID of the external RSS feed."},"rssFeedUrl":{"type":"string","description":"The URL of the RSS feed."},"articleLayout":{"$ref":"#/components/schemas/type_posts:RssBlockLayout","description":"The layout of the articles from the feed."},"articlesToShow":{"type":"integer","description":"The number of articles to show from the feed."},"showCta":{"type":"boolean","description":"Whether to show a call to action."},"ctaText":{"type":"string","description":"The text of the call to action. Applicable if ctaStyle is button or link."},"ctaStyle":{"$ref":"#/components/schemas/type_posts:RssCtaStyle","description":"The style of the call to action."},"ctaAlignment":{"$ref":"#/components/schemas/type_posts:RssCtaAlignment","description":"The alignment of the call to action."},"refreshOnSend":{"type":"boolean","description":"Whether or not to refresh the contents from the RSS feed before sending out the email."},"showArticleTitle":{"type":"boolean","description":"Whether to show the article title."},"showArticleThumbnail":{"type":"boolean","description":"Whether to show the article thumbnail."},"thumbnailPosition":{"$ref":"#/components/schemas/type_posts:RssThumbnailPosition","description":"The position of the thumbnail."},"showAuthor":{"type":"boolean","description":"Whether to show the author."},"showPublishedDate":{"type":"boolean","description":"Whether to show the date the article was published"},"showCategories":{"type":"boolean","description":"Whether to show the categories."},"showDescription":{"type":"boolean","description":"Whether to show the article description."},"showContent":{"type":"boolean","description":"Whether to show the article content."}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["advertisement"],"description":"Discriminator value: advertisement"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"opportunity_id":{"type":"string","description":"The ID of the Advertisement opportunity."}},"required":["type","opportunity_id"]},{"type":"object","properties":{"type":{"type":"string","enum":["automated_advertisement_placement"],"description":"Discriminator value: automated_advertisement_placement"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"advertisement_kind":{"$ref":"#/components/schemas/type_posts:AutomatedAdvertisementKind","description":"The automated advertisement kind to fill at publish time."}},"required":["type","advertisement_kind"]},{"type":"object","properties":{"type":{"type":"string","enum":["columns"],"description":"Discriminator value: columns"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"stackOnMobile":{"type":"boolean","default":true,"description":"Whether columns should stack vertically on mobile devices."},"columns":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ColumnBlock"},"description":"The blocks that make up the columns."}},"required":["type","columns"]},{"type":"object","properties":{"type":{"type":"string","enum":["list"],"description":"Discriminator value: list"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"items":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:ListBlockItem"},"description":"The items in the list."},"listType":{"$ref":"#/components/schemas/type_posts:ListType","description":"The type of list (e.g., ordered, unordered)."},"startNumber":{"type":"integer","description":"The number to start the list at. Only applicable if listType is ordered."}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","enum":["table"],"description":"Discriminator value: table"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"rows":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/type_posts:TableCellData"}},"description":"The rows of the table."},"headerRow":{"type":"boolean","default":true,"description":"Whether the first row is a header row."},"headerColumn":{"type":"boolean","default":false,"description":"Whether the first column is a header column."}},"required":["type","rows"]},{"type":"object","properties":{"type":{"type":"string","enum":["html"],"description":"Discriminator value: html"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"html":{"type":"string","description":"The raw HTML content. Note that `<style>` and `<link>` tags are removed during sanitization — use inline styles for all visual styling."}},"required":["type","html"]},{"type":"object","properties":{"type":{"type":"string","enum":["embed_link"],"description":"Discriminator value: embed_link"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"url":{"type":"string","description":"The URL of the embed link."}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["poll"],"description":"Discriminator value: poll"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"poll_id":{"$ref":"#/components/schemas/type_ids:PollId","description":"The ID of the poll you wish to include."},"show_options_initially":{"type":"boolean","description":"Whether to show the poll options initially. Defaults to false."}},"required":["type","poll_id"]},{"type":"object","properties":{"type":{"type":"string","enum":["quote"],"description":"Discriminator value: quote"},"visual_settings":{"$ref":"#/components/schemas/type_posts:VisualSettings","description":"Optional styling for borders, spacing, colors, etc."},"visibility_settings":{"$ref":"#/components/schemas/type_posts:VisibilitySettings","description":"Optional rules for when/where this block is shown, including dynamic content targeting via condition sets."},"variant":{"$ref":"#/components/schemas/type_posts:QuoteVariant","description":"The type of quote block. Defaults to \"block\"."},"quote":{"type":"string","description":"The text of the quote."},"alignment":{"$ref":"#/components/schemas/type_posts:TextAlignment","description":"The text alignment of the quote. Defaults depend on the variant."},"author":{"type":"string","description":"The author of the quote."}},"required":["type","quote"]},{"type":"object","properties":{"type":{"type":"string","enum":["content_break"],"description":"Discriminator value: content_break"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["paywall_break"],"description":"Discriminator value: paywall_break"},"paywall_id":{"$ref":"#/components/schemas/type_ids:PaywallId","description":"The ID of the paywall."}},"required":["type","paywall_id"]}],"discriminator":{"propertyName":"type"},"description":"A block in the post content.","title":"Block"},"type_ids:PostTemplateId":{"type":"string","description":"The prefixed ID of the post template.","title":"PostTemplateId"},"type_posts:PostPublishStatus":{"type":"string","enum":["draft","confirmed"],"default":"confirmed","title":"PostPublishStatus"},"type_posts:PostEmailCaptureTypeOverride":{"type":"string","enum":["none","gated","popup"],"title":"PostEmailCaptureTypeOverride"},"type_posts:PostSocialShare":{"type":"string","enum":["comments_and_likes_only","with_comments_and_likes","top","none"],"title":"PostSocialShare"},"type_ids:SegmentId":{"type":"string","description":"The prefixed ID of the segment.","title":"SegmentId"},"type_posts:PostWebRecipients":{"type":"object","properties":{"tier_ids":{"type":"array","items":{"type":"string"},"description":"The tier IDs to target. Accepts specific tier UUIDs or the special values `\"free\"`, `\"premium\"`, or `\"all\"`. When `\"all\"` is provided, targets all subscriber tiers — free subscribers, and premium subscribers if the publication has an active paid tier."},"include_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/type_ids:SegmentId"}},"exclude_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/type_ids:SegmentId"}}},"title":"PostWebRecipients"},"type_posts:PostEmailRecipients":{"type":"object","properties":{"tier_ids":{"type":"array","items":{"type":"string"},"description":"The tier IDs to target. Accepts specific tier UUIDs or the special values `\"free\"`, `\"premium\"`, or `\"all\"`. When `\"all\"` is provided, targets all subscriber tiers — free subscribers, and premium subscribers if the publication has an active paid tier."},"include_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/type_ids:SegmentId"}},"exclude_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/type_ids:SegmentId"}}},"title":"PostEmailRecipients"},"type_posts:PostRecipients":{"type":"object","properties":{"web":{"$ref":"#/components/schemas/type_posts:PostWebRecipients","description":"Web audience targeting. Omit this key to create no web targets."},"email":{"$ref":"#/components/schemas/type_posts:PostEmailRecipients","description":"Email audience targeting. Omit this key to create no email targets."}},"required":["web","email"],"description":"Controls who receives the post. If omitted entirely, defaults to free tier only on both web and email. If a channel key (web or email) is provided but empty, no targets are created for that channel — omit the key to skip a channel.","title":"PostRecipients"},"type_posts:PostEmailSettings":{"type":"object","properties":{"from_address":{"type":"string"},"custom_live_url":{"type":"string"},"display_title_in_email":{"type":"boolean"},"display_byline_in_email":{"type":"boolean"},"display_subtitle_in_email":{"type":"boolean"},"email_header_engagement_buttons":{"type":"string"},"email_header_social_share":{"type":"string"},"email_preview_text":{"type":"string"},"email_subject_line":{"type":"string"}},"title":"PostEmailSettings"},"type_posts:PostWebSettings":{"type":"object","properties":{"display_thumbnail_on_web":{"type":"boolean"},"hide_from_feed":{"type":"boolean"},"paywall_break_price_id":{"$ref":"#/components/schemas/type_ids:PriceId"},"paywall_id":{"$ref":"#/components/schemas/type_ids:PaywallId"},"slug":{"type":"string"}},"title":"PostWebSettings"},"type_posts:PostMetadata":{"type":"object","properties":{"default_description":{"type":"string"},"default_title":{"type":"string"},"og_description":{"type":"string"},"og_title":{"type":"string"},"twitter_description":{"type":"string"},"twitter_title":{"type":"string"}},"title":"PostMetadata"},"type_ids:PostId":{"type":"string","description":"The prefixed ID of the post.","title":"PostId"},"type_:PostCreate":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PostId","description":"The prefixed post id"}},"required":["id"],"title":"PostCreate"},"type_posts:PostsCreateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:PostCreate"}},"required":["data"],"title":"PostsCreateResponse"},"type_:PostStatus":{"type":"string","enum":["draft","confirmed","archived"],"default":"draft","description":"The status of the post.<br>`draft` - not been scheduled.<br>`confirmed` - The post will be active after the `scheduled_at`.<br>`archived` - The post is no longer active.","title":"PostStatus"},"type_:PostAudience":{"type":"string","enum":["free","premium","both"],"description":"The audience that the post is available to on the web. Only applicable if the platform is `web` or `both`.","title":"PostAudience"},"type_:PostPlatform":{"type":"string","enum":["web","email","both"],"description":"The platform that the post is or will be published to.","title":"PostPlatform"},"type_:FreePostContent":{"type":"object","properties":{"web":{"type":"string","description":"The web HTML rendered to a free or annonomous reader."},"email":{"type":"string","description":"The email HTML rendered to a free reader."},"rss":{"type":"string","description":"The HTML that is rendered in RSS feeds."}},"description":"The requested free post HTML. This HTML has paywalls enforced.","title":"FreePostContent"},"type_:PremiumPostContent":{"type":"object","properties":{"web":{"type":"string","description":"The website HTML rendered to a free reader"},"email":{"type":"string","description":"The email HTML rendered to a premium reader"}},"description":"The requested premium post HTML. This HTML does not have paywalls enforced.","title":"PremiumPostContent"},"type_:PostContent":{"type":"object","properties":{"free":{"$ref":"#/components/schemas/type_:FreePostContent","description":"The requested free post HTML. This HTML has paywalls enforced."},"premium":{"$ref":"#/components/schemas/type_:PremiumPostContent","description":"The requested premium post HTML. This HTML does not have paywalls enforced."}},"description":"Optional html content for a post. Retrievable by including any of `expand: [free_web_content, free_email_content, free_rss_content, premium_web_content, premium_email_content]` in the post request body.\n\n**Note:** Generating HTML is slow. We recommend only requesting the HTML versions you need at the time.","title":"PostContent"},"type_:PostStatsEmail":{"type":"object","properties":{"recipients":{"type":"integer","default":0,"description":"Total number of email recipients"},"delivered":{"type":"integer","default":0,"description":"Total number of emails delivered"},"opens":{"type":"integer","default":0,"description":"Total number of email opens"},"unique_opens":{"type":"integer","default":0,"description":"Total number of unique email opens"},"open_rate":{"type":"number","format":"double","description":"The percentage of emails that have been opened"},"clicks":{"type":"integer","default":0,"description":"Total number of email clicks"},"unique_clicks":{"type":"integer","default":0,"description":"Unique number of email clicks"},"verified_clicks":{"type":"integer","default":0,"description":"Total number of verified human email clicks across all URLs in this post. Verified clicks have passed bot detection and are confirmed to be from real subscribers."},"unique_verified_clicks":{"type":"integer","default":0,"description":"Unique number of verified human email clicks across all URLs in this post. Only counts the first verified click per subscriber."},"click_rate":{"type":"number","format":"double","description":"The percentage of emails that have been clicked"},"unsubscribes":{"type":"integer","default":0,"description":"Total number of email unsubscribes"},"spam_reports":{"type":"integer","default":0,"description":"The number of subscribers that reported this post email as spam"}},"description":"Stats scoped only to email recipients. Not relevant for posts published only to web","title":"PostStatsEmail"},"type_:PostStatsWeb":{"type":"object","properties":{"views":{"type":"integer","default":0,"description":"Total number of web views"},"clicks":{"type":"integer","default":0,"description":"Total number of web clicks"}},"description":"Stats scoped only to web views. Not relevant for posts published only to email","title":"PostStatsWeb"},"type_:PostClickStatsEmail":{"type":"object","properties":{"clicks":{"type":"integer"},"unique_clicks":{"type":"integer"},"verified_clicks":{"type":"integer","description":"Total number of verified human email clicks on this URL. Verified clicks have passed bot detection and are confirmed to be from real subscribers."},"unique_verified_clicks":{"type":"integer","description":"Unique number of verified human email clicks on this URL. Only counts the first verified click per subscriber."},"click_through_rate":{"type":"number","format":"double","description":"The percentage of email clicks on the URL compared to the total number of recipients"}},"description":"URL stats scoped only to email recipients. Not relevant for posts published only to web","title":"PostClickStatsEmail"},"type_:PostClickStatsWeb":{"type":"object","properties":{"clicks":{"type":"integer"},"unique_clicks":{"type":"integer"},"click_through_rate":{"type":"number","format":"double","description":"The percentage of clicks on the URL compared to the total number of web views"}},"description":"Stats scoped only to web views. Not relevant for posts published only to email","title":"PostClickStatsWeb"},"type_:ClickStats":{"type":"object","properties":{"url":{"type":"string","description":"The URL the stats are for"},"base_url":{"type":"string","description":"The canonical URL with all query parameters and fragments removed. Derived by stripping everything after the '?' and '#' characters. Preserves the protocol, host (including casing), port, and path exactly as they appear in the original URL. Guaranteed to be present whenever url is present, enabling grouping of clicks by destination regardless of tracking parameters."},"email":{"$ref":"#/components/schemas/type_:PostClickStatsEmail","description":"URL stats scoped only to email recipients. Not relevant for posts published only to web"},"web":{"$ref":"#/components/schemas/type_:PostClickStatsWeb","description":"Stats scoped only to web views. Not relevant for posts published only to email"},"total_clicks":{"type":"integer"},"total_unique_clicks":{"type":"integer"},"total_click_through_rate":{"type":"number","format":"double","description":"The percentage of clicks on the URL compared to the total number of recipients and web views"}},"description":"Details about specific URL's click stats from a post.","title":"ClickStats"},"type_:PostStats":{"type":"object","properties":{"email":{"$ref":"#/components/schemas/type_:PostStatsEmail","description":"Stats scoped only to email recipients. Not relevant for posts published only to web"},"web":{"$ref":"#/components/schemas/type_:PostStatsWeb","description":"Stats scoped only to web views. Not relevant for posts published only to email"},"clicks":{"type":"array","items":{"$ref":"#/components/schemas/type_:ClickStats"},"description":"An array of click statistics for each URL in the post"},"upgrades":{"type":"integer","default":0,"description":"Total number of free-to-premium upgrades attributed to this post. Only populated when the publication has a paid subscription tier."}},"description":"Optional list of stats for a post. Retrievable by including `expand: [stats]` in the post request body. <br><br> **Note:** If a timeout occurs while aggregating stats, subsequent requests may return consolidated click metrics rather than individual raw click metrics.","title":"PostStats"},"type_:Post":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PostId","description":"The prefixed post id"},"subtitle":{"type":"string","description":"The subtitle displayed in web views"},"title":{"type":"string","description":"The title displayed in web views"},"authors":{"type":"array","items":{"type":"string"},"description":"An array of author names"},"created":{"type":"integer","description":"The time the post was created. Measured in seconds since the Unix epoch"},"status":{"$ref":"#/components/schemas/type_:PostStatus","description":"The status of the post.<br>`draft` - not been scheduled.<br>`confirmed` - The post will be active after the `scheduled_at`.<br>`archived` - The post is no longer active."},"publish_date":{"type":"integer","description":"The time the post was set to be published. Measured in seconds since the Unix epoch"},"displayed_date":{"type":"integer","description":"The time displayed in place of the `publish_date`. Measured in seconds since the Unix epoch"},"split_tested":{"type":"boolean","description":"A flag to indicate if a split test was done. Only applicable to email posts."},"subject_line":{"type":"string","description":"The email subject line. In cases of A/B Testing, this will be adjusted to the winning subject line."},"preview_text":{"type":"string","description":"The email preview text"},"slug":{"type":"string","description":"The web slug where this post can be accessed."},"thumbnail_url":{"type":"string","description":"The URL of the thumbnail. Defaults to the Publication logo if not set."},"web_url":{"type":"string","description":"The full URL where this post can be accessed on the web. Only applicable if the platform is `web` or `both`."},"audience":{"$ref":"#/components/schemas/type_:PostAudience","description":"The audience that the post is available to on the web. Only applicable if the platform is `web` or `both`."},"platform":{"$ref":"#/components/schemas/type_:PostPlatform","description":"The platform that the post is or will be published to."},"content_tags":{"type":"array","items":{"type":"string"},"description":"All content tags that were associated with the post."},"meta_default_description":{"type":"string","description":"Meta tag description for the post, called SEO Description in the admin UI"},"meta_default_title":{"type":"string","description":"meta tag title for the post, called SEO Title in the admin UI"},"newsletter_list_id":{"type":"string","description":"The prefixed ID of the newsletter list this post is associated with. When set, the post targets only subscribers of this newsletter list. <Badge intent=\"warning\" minimal outlined>Beta</Badge>"},"hidden_from_feed":{"type":"boolean","default":false,"description":"A flag to indicate if the post is hidden from the website feed."},"enforce_gated_content":{"type":"boolean","default":false,"description":"A flag to indicate if the post enforces gated content for non-subscribers."},"email_capture_popup":{"type":"boolean","default":false,"description":"A flag to indicate if popup email capture is enabled for this post."},"content":{"$ref":"#/components/schemas/type_:PostContent"},"stats":{"$ref":"#/components/schemas/type_:PostStats"}},"required":["id","subtitle","title","authors","created","status","split_tested","subject_line","preview_text","slug","thumbnail_url","web_url","audience","platform","content_tags","hidden_from_feed","enforce_gated_content","email_capture_popup"],"title":"Post"},"type_posts:PostsGetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:Post"}},"required":["data"],"title":"PostsGetResponse"},"type_posts:PostExpandField":{"type":"string","enum":["stats","free_web_content","free_email_content","free_rss_content","premium_web_content","premium_email_content"],"title":"PostExpandField"},"type_posts:PostAudienceFilter":{"type":"string","enum":["free","premium","all"],"default":"all","title":"PostAudienceFilter"},"type_posts:PostPlatformFilter":{"type":"string","enum":["web","email","both","all"],"default":"all","title":"PostPlatformFilter"},"type_posts:PostStatusFilter":{"type":"string","enum":["draft","confirmed","archived","all"],"default":"all","title":"PostStatusFilter"},"type_posts:PostOrderBy":{"type":"string","enum":["created","publish_date","displayed_date"],"default":"created","title":"PostOrderBy"},"type_posts:PostsListRequestHiddenFromFeed":{"type":"string","enum":["all","true","false"],"default":"all","title":"PostsListRequestHiddenFromFeed"},"type_posts:PostsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Post"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"PostsListResponse"},"type_posts:PostsAggregateStatsResponseStats":{"type":"object","properties":{"stats":{"$ref":"#/components/schemas/type_:PostStats"}},"required":["stats"],"title":"PostsAggregateStatsResponseStats"},"type_posts:PostsAggregateStatsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_posts:PostsAggregateStatsResponseStats"}},"required":["data"],"title":"PostsAggregateStatsResponse"},"type_posts:PostsDeleteResponse":{"type":"object","properties":{},"title":"PostsDeleteResponse"},"type_posts:PostsTestSendData":{"type":"object","properties":{"remaining_test_sends":{"type":"integer","description":"Number of test sends remaining for the publication today."},"reset_at":{"type":"integer","description":"Unix timestamp when the daily test send limit resets. Null if no test sends have been sent today."}},"required":["remaining_test_sends"],"title":"PostsTestSendData"},"type_posts:PostsTestSendResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_posts:PostsTestSendData"}},"required":["data"],"title":"PostsTestSendResponse"},"type_postTemplates:PostTemplate":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PostTemplateId","description":"The prefixed ID of the post template."},"name":{"type":"string","description":"The name of the post template."}},"required":["id","name"],"title":"PostTemplate"},"type_postTemplates:PostTemplatesGetResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_postTemplates:PostTemplate"},"description":"A list of post templates available for this publication."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"PostTemplatesGetResponse"},"type_publications:PublicationsRequestExpandItem":{"type":"string","enum":["stats","stat_active_subscriptions","stat_active_premium_subscriptions","stat_active_free_subscriptions","stat_average_open_rate","stat_average_click_rate","stat_total_sent","stat_total_unique_opened","stat_total_clicked"],"title":"PublicationsRequestExpandItem"},"type_publications:PublicationsListRequestOrderBy":{"type":"string","enum":["created","name"],"default":"created","title":"PublicationsListRequestOrderBy"},"type_:ActiveSubscriptionCount":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"Total number of active free and premium subscriptions","title":"ActiveSubscriptionCount"},"type_:ActivePremiumSubscriptionCount":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"Total number of active premium/paid subscriptions","title":"ActivePremiumSubscriptionCount"},"type_:ActiveFreeSubscriptionCount":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"Total number of active free subscriptions","title":"ActiveFreeSubscriptionCount"},"type_:AverageOpenRate":{"oneOf":[{"type":"number","format":"double"},{"type":"boolean"}],"description":"The publications historical average open rate","title":"AverageOpenRate"},"type_:AverageClickRate":{"oneOf":[{"type":"number","format":"double"},{"type":"boolean"}],"description":"The publications historical average click through rate","title":"AverageClickRate"},"type_:TotalEmailsSent":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"Total number of emails sent","title":"TotalEmailsSent"},"type_:TotalUniqueOpens":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"Total number of uniquely opened emails. Only counts the first open for each subscriber.","title":"TotalUniqueOpens"},"type_:TotalClicks":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"The total number of links clicked from emails.","title":"TotalClicks"},"type_:PublicationStats":{"type":"object","properties":{"active_subscriptions":{"$ref":"#/components/schemas/type_:ActiveSubscriptionCount","description":"Total number of active free and premium subscriptions"},"active_premium_subscriptions":{"$ref":"#/components/schemas/type_:ActivePremiumSubscriptionCount","description":"Total number of active premium/paid subscriptions"},"active_free_subscriptions":{"$ref":"#/components/schemas/type_:ActiveFreeSubscriptionCount","description":"Total number of active free subscriptions"},"average_open_rate":{"$ref":"#/components/schemas/type_:AverageOpenRate","description":"The publications historical average open rate"},"average_click_rate":{"$ref":"#/components/schemas/type_:AverageClickRate","description":"The publications historical average click through rate"},"total_sent":{"$ref":"#/components/schemas/type_:TotalEmailsSent","description":"Total number of emails sent"},"total_unique_opened":{"$ref":"#/components/schemas/type_:TotalUniqueOpens","description":"Total number of uniquely opened emails. Only counts the first open for each subscriber."},"total_clicked":{"$ref":"#/components/schemas/type_:TotalClicks","description":"The total number of links clicked from emails."}},"description":"Optional list of stats for a publication. Retrievable by including an `expand` array in the publication request body. Add `\"stats\"` to the array to retrieve all, or add individual stats (prefaced with `stat_`) to only retrieve specific ones.\n\nExamples:\n{\n  \"expand\": [\"stats\"]\n}\n\n{\n  \"expand\": [\"stat_active_subscriptions\", \"stat_average_click_rate\"]\n}","title":"PublicationStats"},"type_:Publication":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PublicationId","description":"A unique prefixed id of the publication"},"name":{"type":"string","description":"The name of the publication"},"organization_name":{"type":"string","description":"The name of the organization"},"referral_program_enabled":{"type":"boolean","description":"A boolean field indicating whether the referral program is active for this publication."},"created":{"type":"number","format":"double","description":"The time that the publication was created. Measured in seconds since the Unix epoch"},"stats":{"$ref":"#/components/schemas/type_:PublicationStats"}},"required":["id","name","organization_name","referral_program_enabled","created"],"title":"Publication"},"type_publications:PublicationsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Publication"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"PublicationsListResponse"},"type_publications:PublicationsGetRequestExpandItem":{"type":"string","enum":["stats","stat_active_subscriptions","stat_active_premium_subscriptions","stat_active_free_subscriptions","stat_average_open_rate","stat_average_click_rate","stat_total_sent","stat_total_unique_opened","stat_total_clicked"],"title":"PublicationsGetRequestExpandItem"},"type_publications:PublicationsGetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:Publication"}},"required":["data"],"title":"PublicationsGetResponse"},"type_ids:MilestoneId":{"type":"string","description":"The prefixed ID of the milestone.","title":"MilestoneId"},"type_ids:RewardId":{"type":"string","description":"The prefixed ID of the reward.","title":"RewardId"},"type_:MilestoneRewardType":{"type":"string","enum":["physical","promo_code","digital","premium_gift"],"description":"What type of reward this is.<br>`physical` - A product which must be sent to the subscriber.<br>`promo_code` - A code that is redeemable for goods or services.","title":"MilestoneRewardType"},"type_:MilestoneReward":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:RewardId","description":"A unique prefixed id of the reward."},"name":{"type":"string","description":"The name given to the reward at creation."},"description":{"type":"string","description":"The description given to the name at creation."},"image_url":{"type":"string","description":"A URL of an image to be displayed with the reward."},"type":{"$ref":"#/components/schemas/type_:MilestoneRewardType","description":"What type of reward this is.<br>`physical` - A product which must be sent to the subscriber.<br>`promo_code` - A code that is redeemable for goods or services."}},"required":["id","name","description","image_url","type"],"description":"The reward object.","title":"MilestoneReward"},"type_:Milestone":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:MilestoneId","description":"A unique prefixed id of the milestone."},"auto_fulfill":{"type":"boolean","description":"Only available with a promo code reward type. This indicates that an email will automatically be sent when the milestone is reached containing the reward promo code."},"num_referrals":{"type":"integer","description":"The number of referrals needed to reach this milestone."},"reward":{"$ref":"#/components/schemas/type_:MilestoneReward"}},"required":["id","auto_fulfill","num_referrals","reward"],"description":"The milestone object.","title":"Milestone"},"type_referralProgram:ReferralProgramGetResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Milestone"},"description":"A list of the milestones related to this publication's referral program."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"ReferralProgramGetResponse"},"type_segments:CustomFieldsLogicalOperator":{"type":"string","enum":["and","or"],"title":"CustomFieldsLogicalOperator"},"type_segments:CustomFieldFilter":{"type":"object","properties":{"name":{"type":"string","description":"The display name of the custom field (case-insensitive match). Must be an existing custom field on the publication."},"operator":{"type":"string","description":"The comparison operator for the filter (e.g., `equal`, `not_equal`, `contains`, `exists`, `does_not_exist`). Available operators depend on the custom field's type."},"value":{"type":"string","description":"The value to compare against. Required for all operators except `exists` and `does_not_exist`."}},"required":["name","operator"],"description":"A single custom field filter condition.","title":"CustomFieldFilter"},"type_segments:SegmentSubscriptionInput":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["subscriptions"],"description":"Discriminator value: subscriptions"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/type_ids:SubscriptionId"}}},"required":["type","subscriptions"]},{"type":"object","properties":{"type":{"type":"string","enum":["emails"],"description":"Discriminator value: emails"},"emails":{"type":"array","items":{"type":"string"}}},"required":["type","emails"]},{"type":"object","properties":{"type":{"type":"string","enum":["custom_fields"],"description":"Discriminator value: custom_fields"},"operator":{"$ref":"#/components/schemas/type_segments:CustomFieldsLogicalOperator","description":"The logical operator used to combine multiple custom field filters. Defaults to `and` if not specified."},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/type_segments:CustomFieldFilter"}}},"required":["type","custom_fields"]}],"discriminator":{"propertyName":"type"},"description":"Input for segment creation. Use `subscriptions` or `emails` to create a manual segment from explicit lists, or `custom_fields` to create a dynamic segment filtered by custom field values.","title":"SegmentSubscriptionInput"},"type_:SegmentType":{"type":"string","enum":["dynamic","static","manual","all"],"default":"all","description":"The type of segment.<br>`dynamic` - The segment is recalculated at set intervals.<br>`static` - The segment is calculated once at creation.<br>`manual` - The segment is not calculated at all. The results are created via CSV.","title":"SegmentType"},"type_:SegmentStatus":{"type":"string","enum":["pending","processing","completed","failed"],"description":"The status of the segment's most recent calculation.<br>`pending` - The segment has not been calculated yet.<br>`processing` - The calculation is in progress, and has not completed.<br>`completed` - The calculation was successful.<br>`failed` - Something went wrong during the calculation.","title":"SegmentStatus"},"type_:SegmentStats":{"type":"object","properties":{"open_rate":{"type":"number","format":"double","description":"The average open rate of the subscribers in the segment."},"total_sent":{"type":"integer","description":"The total number of emails sent to the subscribers in the segment."},"percentage_premium_subscribers":{"type":"number","format":"double","description":"The percentage of subscribers in this segment who are premium in any tier."},"percentage_subscribers_with_referrals":{"type":"number","format":"double","description":"The percentage of subscribers in this segment who have referred at least one other subscriber."},"unique_emails_clicked":{"type":"integer","description":"The total number of unique emails clicked by subscribers in the segment."},"total_delivered":{"type":"integer","description":"The total number of emails delivered to subscribers in the segment."},"total_referrals":{"type":"integer","description":"The total number of referrals from subscribers in the segment."},"unsubscribed_rate":{"type":"number","format":"double","description":"The percentage of subscribers in this segment who have unsubscribed."},"total_subscribers":{"type":"integer","description":"The total number of subscribers in the segment."},"clickthrough_rate":{"type":"number","format":"double","description":"The average clickthrough rate of the subscribers in the segment."},"unsubscribed_count":{"type":"integer","description":"The total number of subscribers in the segment who are unsubscribed."},"unique_emails_opened":{"type":"integer","description":"The total number of unique emails opened by subscribers in the segment."},"premium_subscribers":{"type":"integer","description":"The total number of premium subscribers in the segment."},"average_referrals_per_subscriber":{"type":"number","format":"double","description":"The average number of referrals per subscriber in the segment."}},"required":["open_rate","total_sent","percentage_premium_subscribers","percentage_subscribers_with_referrals","unique_emails_clicked","total_delivered","total_referrals","unsubscribed_rate","total_subscribers","clickthrough_rate","unsubscribed_count","unique_emails_opened","premium_subscribers","average_referrals_per_subscriber"],"title":"SegmentStats"},"type_:Segment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:SegmentId","description":"The prefixed ID of the segment."},"name":{"type":"string","description":"The name of the segment."},"type":{"$ref":"#/components/schemas/type_:SegmentType","description":"The type of segment.<br>`dynamic` - The segment is recalculated at set intervals.<br>`static` - The segment is calculated once at creation.<br>`manual` - The segment is not calculated at all. The results are created via CSV."},"last_calculated":{"type":"integer","description":"The time the Segment was last calculated. Measured in seconds since the Unix epoch"},"total_results":{"type":"integer","description":"The total number of subscriptions that belong in the segment from the last calculation."},"status":{"$ref":"#/components/schemas/type_:SegmentStatus","description":"The status of the segment's most recent calculation.<br>`pending` - The segment has not been calculated yet.<br>`processing` - The calculation is in progress, and has not completed.<br>`completed` - The calculation was successful.<br>`failed` - Something went wrong during the calculation."},"active":{"type":"boolean","description":"Dynamic segments are marked inactive if they haven't been used in a specific period of time. Inactive segments will not automatically be recalculated."},"stats":{"$ref":"#/components/schemas/type_:SegmentStats"}},"required":["id","name","type","total_results","status","active"],"description":"The segment object. To expand results, see the results endpoint.","title":"Segment"},"type_segments:SegmentShowResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:Segment"}},"required":["data"],"title":"SegmentShowResponse"},"type_segments:SegmentRequestStatus":{"type":"string","enum":["pending","processing","completed","failed","all"],"default":"all","title":"SegmentRequestStatus"},"type_segments:SegmentOrderBy":{"type":"string","enum":["created","last_calculated"],"default":"created","title":"SegmentOrderBy"},"type_segments:SegmentsExpandItems":{"type":"string","enum":["stats"],"title":"SegmentsExpandItems"},"type_segments:SegmentsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Segment"},"description":"An array of all segments."},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"SegmentsListResponse"},"type_segments:SegmentRecalculateResponse":{"type":"object","properties":{"message":{"type":"string"}},"title":"SegmentRecalculateResponse"},"type_segments:SegmentMembersExpandItems":{"type":"string","enum":["stats","custom_fields","referrals","tags","subscription_premium_tiers"],"title":"SegmentMembersExpandItems"},"type_:SubscriptionExpandedStatus":{"type":"string","enum":["validating","invalid","pending","active","inactive","needs_attention","paused"],"description":"The status of the subscription.<br>`validating` - The email address is being validated.<br>`invalid` - The email address is invalid.<br>`pending` - The email address is valid, but the subscription is pending double opt-in.<br>`active` - The email was valid and the subscription is active.<br>`inactive` - The subscription was made inactive, possibly due to an unsubscribe.<br>`needs_attention` - The subscription requires approval or denial.<br>`paused` - The subscriber has paused their subscription.","title":"SubscriptionExpandedStatus"},"type_:SubscriptionExpandedSubscriptionTier":{"type":"string","enum":["free","premium"],"description":"The current tier of the subscription.","title":"SubscriptionExpandedSubscriptionTier"},"type_:SubscriptionExpandedUtmChannel":{"type":"string","enum":["","website","import","embed","api","referral","recommendation","magic_link","boost","boost_send","boost_direct_link","integration","product","group_invite"],"description":"The acquisition channel","title":"SubscriptionExpandedUtmChannel"},"type_:SubscriptionTierInfoStatus":{"type":"string","enum":["active","archived"],"description":"Returns whether or not the tier has any active prices.","title":"SubscriptionTierInfoStatus"},"type_:SubscriptionTierInfo":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:TierId"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/type_:SubscriptionTierInfoStatus","description":"Returns whether or not the tier has any active prices."}},"required":["id","name","status"],"title":"SubscriptionTierInfo"},"type_:SubscriptionTierList":{"type":"array","items":{"$ref":"#/components/schemas/type_:SubscriptionTierInfo"},"description":"Optional list of tiers for a subscription. Retrievable by including `expand: [subscription_premium_tiers]` in the request body.","title":"SubscriptionTierList"},"type_:CustomField":{"type":"object","properties":{"name":{"type":"string","description":"The name of the existing custom field"},"kind":{"$ref":"#/components/schemas/type_:CustomFieldType","description":"The type of value being stored in the custom field."},"value":{"$ref":"#/components/schemas/type_:CustomFieldDataType","description":"The value stored for the subscription"}},"title":"CustomField"},"type_:SubscriptionCustomFieldList":{"type":"array","items":{"$ref":"#/components/schemas/type_:CustomField"},"description":"Optional list of custom fields for a subscription. Retrievable by including `expand: [custom_field]` in the request body.","title":"SubscriptionCustomFieldList"},"type_:SubscriptionTags":{"type":"array","items":{"type":"string"},"description":"Optional list of tags for a subscription. Retrievable by including `expand: [tags]` in the request body.\nMax limit of 100 unique tags per publication.","title":"SubscriptionTags"},"type_:SubscriptionStats":{"type":"object","properties":{"emails_received":{"type":"integer","description":"The total number of emails that have been sent to this subscriber"},"open_rate":{"type":"number","format":"double","description":"The percentage of emails that the subscriber has opened"},"click_through_rate":{"type":"number","format":"double","description":"The percentage of emails that the subscriber has clicked a link in"}},"description":"Optional list of stats for a subscription. Retrievable by including `expand: [stats]` in the request body.","title":"SubscriptionStats"},"type_:Subscription":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:SubscriptionId","description":"The prefixed subscription id"},"email":{"type":"string","format":"email"},"status":{"$ref":"#/components/schemas/type_:SubscriptionExpandedStatus","description":"The status of the subscription.<br>`validating` - The email address is being validated.<br>`invalid` - The email address is invalid.<br>`pending` - The email address is valid, but the subscription is pending double opt-in.<br>`active` - The email was valid and the subscription is active.<br>`inactive` - The subscription was made inactive, possibly due to an unsubscribe.<br>`needs_attention` - The subscription requires approval or denial."},"created":{"type":"integer","description":"The date the subscription was created. Measured in seconds since the Unix epoch"},"subscription_tier":{"$ref":"#/components/schemas/type_:SubscriptionExpandedSubscriptionTier","description":"The current tier of the subscription."},"subscription_premium_tier_names":{"type":"array","items":{"type":"string"},"description":"The current premium tiers of the subscription. Empty if the subscriber is not associated with any premium tiers."},"utm_source":{"type":"string","description":"The acquisition source; where the subscriber came from"},"utm_medium":{"type":"string","description":"The acquisition medium; how the subscriber got to your publication"},"utm_channel":{"$ref":"#/components/schemas/type_:SubscriptionExpandedUtmChannel","description":"The acquisition channel"},"utm_campaign":{"type":"string","description":"The acquisition campaign"},"utm_term":{"type":"string","description":"The acquisition term; typically the keyword or search term"},"utm_content":{"type":"string","description":"The acquisition content; typically used for A/B testing or ad variations"},"referring_site":{"type":"string","description":"The website that the subscriber was referred from"},"referral_code":{"type":"string","description":"The code associated to this subscriber to refer others. When a new subscription is created with this referral code, credit for the referral goes to this subscription."},"subscription_premium_tiers":{"$ref":"#/components/schemas/type_:SubscriptionTierList"},"custom_fields":{"$ref":"#/components/schemas/type_:SubscriptionCustomFieldList"},"tags":{"$ref":"#/components/schemas/type_:SubscriptionTags"},"stats":{"$ref":"#/components/schemas/type_:SubscriptionStats"},"newsletter_list_ids":{"type":"array","items":{"type":"string"},"description":"The prefixed IDs of the newsletter lists this subscription is actively subscribed to. Requires `expand[]=newsletter_lists`. <Badge intent=\"warning\" minimal outlined>Beta</Badge>"}},"required":["id","email","status","created","subscription_tier","subscription_premium_tier_names","utm_source","utm_medium","utm_channel","utm_campaign","utm_term","utm_content","referring_site","referral_code"],"description":"The subscription object","title":"Subscription"},"type_segments:SegmentMembersResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Subscription"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"SegmentMembersResponse"},"type_segments:SegmentsGetResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"},"description":"An array of subscription ids"},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"SegmentsGetResponse"},"type_segments:SegmentDeleteResponse":{"type":"object","properties":{"message":{"type":"string"}},"title":"SegmentDeleteResponse"},"type_subscriptions:SubscriptionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:Subscription"}},"required":["data"],"description":"The response containing subscription data","title":"SubscriptionResponse"},"type_subscriptions:SubscriptionsListRequestExpandItem":{"type":"string","enum":["stats","custom_fields","referrals","newsletter_lists"],"title":"SubscriptionsListRequestExpandItem"},"type_subscriptions:SubscriptionsListRequestStatus":{"type":"string","enum":["validating","invalid","pending","active","inactive","all"],"default":"all","title":"SubscriptionsListRequestStatus"},"type_subscriptions:SubscriptionsListRequestTier":{"type":"string","enum":["free","premium","all"],"default":"all","title":"SubscriptionsListRequestTier"},"type_subscriptions:SubscriptionsListRequestOrderBy":{"type":"string","enum":["created"],"default":"created","title":"SubscriptionsListRequestOrderBy"},"type_subscriptions:SubscriptionsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_:Subscription"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request, this defaults to 10."},"page":{"type":"integer","default":1,"description":"**Offset pagination only**: The page number the results are from. Only present when using deprecated offset-based pagination."},"total_pages":{"type":"integer","description":"**Offset pagination only**: The total number of pages. Only present when using deprecated offset-based pagination."},"has_more":{"type":"boolean","description":"**Cursor pagination only**: Indicates whether there are more results available after the current page. Only present when using cursor-based pagination."},"next_cursor":{"type":"string","description":"**Cursor pagination only**: The cursor token to use for fetching the next page of results. This will be null if has_more is false. Only present when using cursor-based pagination."},"total_results":{"type":"integer","description":"**Mixed pagination**: The total number of results from all pages. For offset-based pagination, this is always included."}},"required":["data"],"title":"SubscriptionsListResponse"},"type_subscriptions:SubscriptionsGetRequestExpandItem":{"type":"string","enum":["stats","custom_fields","referrals","tags","newsletter_lists"],"title":"SubscriptionsGetRequestExpandItem"},"type_bulkSubscriptionUpdates:SubscriptionsPutRequestSubscriptionsItemTier":{"type":"string","enum":["free","premium"],"description":"The Tier of the Subscription (not required)","title":"SubscriptionsPutRequestSubscriptionsItemTier"},"type_bulkSubscriptionUpdates:SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem":{"type":"object","properties":{"name":{"type":"string","description":"The name of the existing custom field"},"value":{"$ref":"#/components/schemas/type_:CustomFieldDataType","description":"The value of the custom field"},"delete":{"type":"boolean","description":"A boolean value to specify whether to delete this custom field entry from the subscription"}},"title":"SubscriptionsPutRequestSubscriptionsItemCustomFieldsItem"},"type_subscriptions:SubscriptionDeleteResponse":{"type":"object","properties":{"message":{"type":"string"}},"title":"SubscriptionDeleteResponse"},"type_subscriptionTags:SubscriptionTagsCreateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_:Subscription"}},"title":"SubscriptionTagsCreateResponse"},"type_tiers:TierPricesAttributesItem":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/type_tiers:TierPriceCurrency"},"amount_cents":{"type":"integer"},"enabled":{"type":"boolean","default":true},"interval":{"$ref":"#/components/schemas/type_tiers:TierPriceInterval"},"interval_display":{"type":"string"},"cta":{"type":"string"},"features":{"type":"array","items":{"type":"string"}}},"required":["currency","amount_cents","interval"],"title":"TierPricesAttributesItem"},"type_tiers:TierResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_tiers:Tier"}},"title":"TierResponse"},"type_tiers:IndexTiersResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_tiers:Tier"}},"limit":{"type":"integer","description":"The limit placed on the results. If no limit was specified in the request,this defaults to 10."},"page":{"type":"integer","default":1,"description":"The page number the results are from. If no page was specified in the request, this defaults to page 1."},"total_results":{"type":"integer","description":"The total number of results from all pages."},"total_pages":{"type":"integer","description":"The total number of pages."}},"required":["data","limit","page","total_results","total_pages"],"title":"IndexTiersResponse"},"type_tiers:UpdateTierPriceRequest":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:PriceId","description":"ID of the existing price."},"currency":{"$ref":"#/components/schemas/type_tiers:TierPriceCurrency"},"amount_cents":{"type":"integer"},"interval":{"$ref":"#/components/schemas/type_tiers:TierPriceInterval"},"interval_display":{"type":"string"},"cta":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"delete":{"type":"boolean","default":false,"description":"Optionally delete the price when updating the tier."}},"required":["id","currency","amount_cents","interval"],"title":"UpdateTierPriceRequest"},"type_webhooks:WebhookEventType":{"type":"string","enum":["post.sent","post.updated","subscription.confirmed","subscription.created","subscription.downgraded","subscription.paused","subscription.resumed","subscription.tier.paused","subscription.tier.resumed","subscription.upgraded","subscription.tier.created","subscription.tier.deleted","subscription.deleted","newsletter_list_subscription.subscribed","newsletter_list_subscription.unsubscribed","newsletter_list_subscription.paused","newsletter_list_subscription.resumed","post.scheduled","survey.response_submitted"],"title":"WebhookEventType"},"type_ids:EndpointId":{"type":"string","description":"The prefixed ID of the endpoint.","title":"EndpointId"},"type_webhooks:Webhook":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:EndpointId","description":"The prefixed ID for the webhook."},"url":{"type":"string","format":"uri","description":"The webhook URL to send events to."},"created":{"type":"integer","description":"The date the webhook was created. Measured in seconds since the Unix epoch."},"updated":{"type":"integer","description":"The date the webhook was last updated. Measured in seconds since the Unix epoch."},"event_types":{"type":"array","items":{"$ref":"#/components/schemas/type_webhooks:WebhookEventType"},"description":"The types of events the webhook will receive."},"description":{"type":"string","description":"The user-defined description for the webhook."}},"required":["id","url","created","updated","event_types","description"],"title":"Webhook"},"type_webhooks:WebhookResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_webhooks:Webhook"}},"required":["data"],"title":"WebhookResponse"},"type_webhooks:IndexWebhooksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/type_webhooks:Webhook"}}},"required":["data"],"title":"IndexWebhooksResponse"},"type_webhooks:WebhooksDeleteResponse":{"type":"object","properties":{"message":{"type":"string"}},"title":"WebhooksDeleteResponse"},"type_ids:WorkspaceId":{"type":"string","description":"The prefixed ID of the workspace.","title":"WorkspaceId"},"type_workspaces:WorkspaceIdentity":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/type_ids:WorkspaceId","description":"The prefixed ID of the workspace."},"name":{"type":"string","description":"The name of the workspace."},"owner_email":{"type":"string","description":"The email of the owner of the workspace."}},"required":["id","name","owner_email"],"title":"WorkspaceIdentity"},"type_workspaces:WorkspaceIdentifyResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/type_workspaces:WorkspaceIdentity"}},"required":["data"],"title":"WorkspaceIdentifyResponse"},"type_workspaces:PublicationsBySubscriptionEmailRequestExpandItem":{"type":"string","enum":["subscription","publication","subscription_custom_fields"],"title":"PublicationsBySubscriptionEmailRequestExpandItem"},"type_workspaces:PublicationsBySubscriptionEmailResponseItem":{"type":"object","properties":{"publication_id":{"$ref":"#/components/schemas/type_ids:PublicationId","description":"The prefixed ID of the publication"},"publication_name":{"type":"string","description":"The name of the publication"},"subscription_id":{"$ref":"#/components/schemas/type_ids:SubscriptionId","description":"The prefixed ID of the subscription matching the email address for this publication"},"status":{"$ref":"#/components/schemas/type_:SubscriptionExpandedStatus","description":"The status of the subscription matching the email address for this publication"},"publication":{"$ref":"#/components/schemas/type_:Publication","description":"The full Publication object. Only present when `expand` includes `publication`."},"subscription":{"$ref":"#/components/schemas/type_:Subscription","description":"The Subscription object matching the email address for this publication.  Only present when `expand` includes `subscription` or `subscription_custom_fields`."}},"required":["publication_id","publication_name","subscription_id","status"],"title":"PublicationsBySubscriptionEmailResponseItem"}},"securitySchemes":{"BearerAuthScheme":{"type":"http","scheme":"bearer"}}}}