> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.beehiiv.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server.

# Update post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>

PATCH https://api.beehiiv.com/v2/publications/{publicationId}/posts/{postId}
Content-Type: application/json

This endpoint is available to publications on the Pro and Enterprise plans.

Update 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 Using the Send API and Create Post Endpoint guide.

To 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.

Reference: https://developers.beehiiv.com/api-reference/posts/update

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `publicationId` (string, required) — The prefixed ID of the publication object
- `postId` (string, required) — The prefixed ID of the post to update

### Body (application/json)

This endpoint expects an object.

- `content_merge_strategy` (enum, optional) — Controls how provided `blocks` interact with the post's existing content. Defaults to `replace`. Use `append_to_template` to preserve template header blocks when updating posts that were created from a template.
  - Allowed values: `replace`, `append_to_template`, `append`, `prepend`
- `blocks` (list of Block, optional) — The structured content blocks for the post. How these interact with existing content depends on `content_merge_strategy` (default: full replacement). Supports block types such as paragraph, image, heading, button, html, table, list, columns, and more. Cannot be provided together with `body_content`.
- `body_content` (string, optional) — 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` (string, optional) — The title of the post.
- `subtitle` (string, optional) — The subtitle of the post.
- `scheduled_at` (datetime, optional) — The time at which the post will be published. Cannot be updated after the post has already been sent.
- `custom_link_tracking_enabled` (boolean, optional) — If true, custom link tracking will be enabled for this post.
- `email_capture_type_override` (enum, optional) — The email capture type to use for this post.
  - Allowed values: `none`, `gated`, `popup`
- `override_scheduled_at` (datetime, optional) — A display date that overrides the scheduled_at date shown in the email. Does not affect the actual publish date.
- `social_share` (enum, optional) — The social share type to use for this post.
  - Allowed values: `comments_and_likes_only`, `with_comments_and_likes`, `top`, `none`
- `thumbnail_image_url` (string, optional) — The URL of the thumbnail image to use for the post.
- `email_settings` (PostEmailSettings, optional) — The email settings to use for this post. Only the provided fields within this object will be updated.
- `web_settings` (PostWebSettings, optional) — The web settings to use for this post. Only the provided fields within this object will be updated.
- `seo_settings` (PostMetadata, optional) — The SEO metadata to use for this post. Only the provided fields within this object will be updated.
- `status` (enum, optional, default: draft) — 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`.
  - Allowed values: `draft`, `confirmed`
- `content_tags` (list of string, optional) — The content tags for this post. When provided, this replaces all existing content tags on the post.
- `headers` (map from string to string, optional) — Custom email headers for this post. Merges with newsletter list and publication headers at send time, with this post's values winning on a key collision. Set a value to `null` to suppress a header inherited from the newsletter list or publication. System-managed headers (e.g. List-Unsubscribe, X-SMTPAPI) cannot be overridden.
- `header_custom_css` (string, optional) — Custom CSS added to this post's email `<head>`, replacing any CSS the post already has. Pass an empty string to remove it. Applies to email only, not the web version.
- `utm_source` (string, optional) — The utm_source appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default.
- `utm_medium` (string, optional) — The utm_medium appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default.
- `utm_campaign` (string, optional) — The utm_campaign appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default.
- `utm_params_enabled` (boolean, optional) — Whether UTM parameters are appended to links in this post. When left unset on the post, falls back to the newsletter list, then the publication.
- `guest_author_ids` (list of string, optional) — The prefixed IDs of the guest authors to associate with this post. Guest authors must belong to the publication. When provided, replaces all existing guest authors on the post.
- `team_author_ids` (list of string, optional) — The prefixed IDs of the team members to associate with this post as authors. Team authors must have access to the publication. When provided, replaces all existing team authors on the post.
- `recipients` (PostRecipients, optional) — The recipients for this post. When provided, replaces all existing web and email audience targets with the specified values. If omitted, existing targets are unchanged.
- `newsletter_list_id` (string, optional) — The prefixed ID of the newsletter list to associate with this post. When provided, updates the newsletter list association. Pass null to remove the association.

## Response

### 200

Updated

- `data` (Post, required)

## Errors

### 202 Post Processing Error

The post was created via the Send API and is still being processed in the background. Wait briefly and retry, honoring the `Retry-After` header.

- `status` (integer, required)
- `statusText` (string, required)
- `data` (PostProcessingData, required)

### 400 Bad Request Error

Bad Request

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 401 Unauthorized Error

Unauthorized. The API key or OAuth access token is missing, invalid, or expired.

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 403 Forbidden Error

Forbidden

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 404 Not Found Error

Resource Not Found

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 429 Too Many Requests Error

Rate Limit Exceeded

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

### 500 Internal Server Error

Internal Server Error

- `status` (integer, required)
- `statusText` (string, required)
- `errors` (list of ErrorDetail, required)

## Types

### Block

A block in the post content.

- `type`: `paragraph`
  - `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the paragraph.
  - `plaintext` (string, optional) — The plaintext content of the paragraph.
  - `textAlign` (enum, optional) — Legacy paragraph alignment field. Use `textAlignment` for new integrations.
    - Allowed values: `left`, `center`, `right`
  - `textAlignment` (enum, optional) — The text alignment of the paragraph (e.g., left, center, right).
    - Allowed values: `left`, `center`, `right`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `image`
  - `imageUrl` (string, required) — The URL of the image.
  - `alt_text` (string, optional) — Alternative text for the image.
  - `caption` (string, optional) — A caption for the image.
  - `captionAlignment` (enum, optional) — The text alignment of the caption.
    - Allowed values: `left`, `center`, `right`
  - `imageAlignment` (enum, optional) — The text alignment of the image.
    - Allowed values: `left`, `center`, `right`
  - `title` (string, optional) — The title of the image.
  - `url` (string, optional) — The URL that the image should link to.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
  - `width` (integer, optional) — The width of the image. Should be between 1 and 100.
- `type`: `button`
  - `href` (string, required) — The URL the button should use.
  - `text` (string, required) — The text content of the button.
  - `alignment` (enum, optional) — The text alignment of the button.
    - Allowed values: `left`, `center`, `right`
  - `size` (enum, optional) — The size of the button (e.g., small, normal, large).
    - Allowed values: `small`, `normal`, `large`
  - `target` (string, optional) — The target of the button (e.g., _blank).
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `heading`
  - `level` (enum, required) — The level of the header (e.g., 1, 2, 3, etc.).
    - Allowed values: `1`, `2`, `3`, `4`, `5`, `6`
  - `anchorHeader` (boolean, optional, default: true) — Whether the header should be an anchor header.
  - `anchorIncludeInToc` (boolean, optional, default: true) — Whether the header should be included in the table of contents.
  - `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the header, supporting links and inline styling.
  - `text` (string, optional) — The text content of the header. Ignored if `formattedText` is provided.
  - `textAlignment` (enum, optional) — The text alignment of the header (e.g., left, center, right).
    - Allowed values: `left`, `center`, `right`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `rss`
  - `articleLayout` (enum, optional) — The layout of the articles from the feed.
    - Allowed values: `1-col`, `2-col`, `3-col`, `4-col`
  - `articlesToShow` (integer, optional) — The number of articles to show from the feed.
  - `ctaAlignment` (enum, optional) — The alignment of the call to action.
    - Allowed values: `Left`, `Center`, `Right`
  - `ctaStyle` (enum, optional) — The style of the call to action.
    - Allowed values: `CTA button`, `CTA link`, `Title as link`, `Thumbnail as link`, `Title and thumbnail as link`
  - `ctaText` (string, optional) — The text of the call to action. Applicable if ctaStyle is button or link.
  - `externalRssFeedId` (string, optional) — The ID of the external RSS feed.
  - `refreshOnSend` (boolean, optional) — Whether or not to refresh the contents from the RSS feed before sending out the email.
  - `rssFeedUrl` (string, optional) — The URL of the RSS feed.
  - `selectionMode` (enum, optional) — How to select feed articles, by count or time window.
    - Allowed values: `count`, `time`
  - `showArticleThumbnail` (boolean, optional) — Whether to show the article thumbnail.
  - `showArticleTitle` (boolean, optional) — Whether to show the article title.
  - `showAuthor` (boolean, optional) — Whether to show the author.
  - `showCategories` (boolean, optional) — Whether to show the categories.
  - `showContent` (boolean, optional) — Whether to show the article content.
  - `showCta` (boolean, optional) — Whether to show a call to action.
  - `showDescription` (boolean, optional) — Whether to show the article description.
  - `showPublishedDate` (boolean, optional) — Whether to show the date the article was published
  - `thumbnailPosition` (enum, optional) — The position of the thumbnail.
    - Allowed values: `Above Title`, `Below Title`, `Left of content`, `Right of content`, `Alternating Horizontally`
  - `timeWindowHours` (integer, optional) — Trailing window in hours when selectionMode is time.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `advertisement`
  - `opportunity_id` (string, required) — The ID of the Advertisement opportunity.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `advertisement_logo`
  - `opportunity_id` (string, required) — The ID of the advertisement opportunity whose logo to display.
  - `override_sponsor_text` (enum, required) — The sponsor text to display with the advertisement logo. Required.
    - Allowed values: `sponsored_by`, `together_with`, `in_partnership_with`, `presented_by`, `todays_sponsor`
  - `override_align` (enum, optional) — The logo alignment. Defaults to center.
    - Allowed values: `left`, `center`, `right`
  - `override_width` (integer, optional) — The logo width as a percentage. Must be greater than 0. Defaults to 100.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `automated_advertisement_placement`
  - `advertisement_kind` (enum, required) — The automated advertisement kind to fill at publish time.
    - Allowed values: `primary`, `secondary`, `tertiary`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `programmatic_ads_logo`
  - `override_sponsor_text` (enum, required) — The sponsor text to display with the advertisement logo. Required.
    - Allowed values: `sponsored_by`, `together_with`, `in_partnership_with`, `presented_by`, `todays_sponsor`
  - `override_align` (enum, optional) — The logo alignment. Defaults to center.
    - Allowed values: `left`, `center`, `right`
  - `override_width` (integer, optional) — The logo width as a percentage. Must be greater than 0. Defaults to 100.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `columns`
  - `columns` (list of ColumnBlock, required) — The blocks that make up the columns.
  - `stackOnMobile` (boolean, optional, default: true) — Whether columns should stack vertically on mobile devices.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `list`
  - `items` (list of ListBlockItem, required) — The items in the list.
  - `listType` (enum, optional) — The type of list (e.g., ordered, unordered).
    - Allowed values: `ordered`, `unordered`
  - `startNumber` (integer, optional) — The number to start the list at. Only applicable if listType is ordered.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `table`
  - `rows` (list of list of TableCellData, required) — The rows of the table.
  - `headerColumn` (boolean, optional, default: false) — Whether the first column is a header column.
  - `headerRow` (boolean, optional, default: true) — Whether the first row is a header row.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `html`
  - `html` (string, required) — The raw HTML content. Note that `<style>` and `<link>` tags are removed during sanitization — use inline styles for all visual styling.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `embed_link`
  - `url` (string, required) — The URL of the embed link.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `poll`
  - `poll_id` (string, required) — The ID of the poll you wish to include.
  - `show_options_initially` (boolean, optional) — Whether to show the poll options initially. Defaults to false.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `quote`
  - `quote` (string, required) — The text of the quote.
  - `alignment` (enum, optional) — The text alignment of the quote. Defaults depend on the variant.
    - Allowed values: `left`, `center`, `right`
  - `author` (string, optional) — The author of the quote.
  - `variant` (enum, optional) — The type of quote block. Defaults to "block".
    - Allowed values: `block`, `inline`, `quotation`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `content_break`
- `type`: `paywall_break`
  - `paywall_id` (string, required) — The ID of the paywall.
- `type`: `section`
  - `blocks` (list of SectionableBlock, required) — The blocks to group inside this section. Must contain at least one block. Cannot contain `section` or `columns` blocks.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this section is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling applied to the section as a whole (background color, padding, borders, etc.).

### PostEmailSettings

- `from_address` (string, optional)
- `custom_live_url` (string, optional)
- `display_title_in_email` (boolean, optional)
- `display_byline_in_email` (boolean, optional)
- `display_subtitle_in_email` (boolean, optional)
- `email_header_engagement_buttons` (string, optional)
- `email_header_social_share` (string, optional)
- `email_preview_text` (string, optional)
- `email_subject_line` (string, optional)
- `reply_to_address` (string, optional) — Email address to set as Reply-To. Must be a verified reply-to address owned by the publication. Returns 422 if not found.
- `sender_name` (string, optional) — The sender name preset, expressed as a composition key: either a single token, or `<token>|<connector>|<token>`. Tokens are `brand`, `list`, `authors_first` and `authors_full`; connectors are `from`, `with`, `by`, `at`, `comma`, `colon` and `space`. For a post by Jane Doe on the publication Bee Informed, `authors_first|from|brand` renders as "Jane from Bee Informed". The `list` token only resolves when the post is associated with a newsletter list. Pass `null` to clear the override and inherit from the newsletter list or publication.

### PostWebSettings

- `display_subtitle_on_web` (boolean, optional)
- `display_thumbnail_on_web` (boolean, optional)
- `display_title_on_web` (boolean, optional)
- `hide_from_feed` (boolean, optional)
- `paywall_break_price_id` (string, optional) — The prefixed ID of the price.
- `paywall_id` (string, optional) — The prefixed ID of the paywall.
- `slug` (string, optional)

### PostMetadata

- `default_description` (string, optional)
- `default_title` (string, optional)
- `og_description` (string, optional)
- `og_title` (string, optional)
- `twitter_description` (string, optional)
- `twitter_title` (string, optional)

### PostRecipients

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.

- `web` (PostWebRecipients, required) — Web audience targeting. Omit this key to create no web targets.
- `email` (PostEmailRecipients, required) — Email audience targeting. Omit this key to create no email targets.

### Post

- `id` (string, required) — The prefixed post id
- `subtitle` (string, required) — The subtitle displayed in web views
- `title` (string, required) — The title displayed in web views
- `authors` (list of string, required) — An array of author names
- `created` (integer, required) — The time the post was created. Measured in seconds since the Unix epoch
- `status` (enum, required, default: draft) — The status of the post.`draft` - not been scheduled.`confirmed` - The post will be active after the `scheduled_at`.`archived` - The post is no longer active.
  - Allowed values: `draft`, `confirmed`, `archived`
- `split_tested` (boolean, required) — A flag to indicate if a split test was done. Only applicable to email posts.
- `subject_line` (string, required) — The email subject line. In cases of A/B Testing, this will be adjusted to the winning subject line.
- `preview_text` (string, required) — The email preview text
- `slug` (string, required) — The web slug where this post can be accessed.
- `thumbnail_url` (string, required) — The URL of the thumbnail. Defaults to the Publication logo if not set.
- `web_url` (string, required) — The full URL where this post can be accessed on the web. Only applicable if the platform is `web` or `both`.
- `audience` (enum, required) — The audience that the post is available to on the web. Only applicable if the platform is `web` or `both`.
  - Allowed values: `free`, `premium`, `both`
- `platform` (enum, required) — The platform that the post is or will be published to.
  - Allowed values: `web`, `email`, `both`
- `content_tags` (list of string, required) — All content tags that were associated with the post.
- `hidden_from_feed` (boolean, required, default: false) — A flag to indicate if the post is hidden from the website feed.
- `enforce_gated_content` (boolean, required, default: false) — A flag to indicate if the post enforces gated content for non-subscribers.
- `email_capture_popup` (boolean, required, default: false) — A flag to indicate if popup email capture is enabled for this post.
- `publish_date` (integer, optional) — The time the post was set to be published. Measured in seconds since the Unix epoch
- `displayed_date` (integer, optional) — The time displayed in place of the `publish_date`. Measured in seconds since the Unix epoch
- `preview_url` (string, optional) — A stable URL to the post's email preview in the beehiiv app. Renders the current post content on every visit. Requires a beehiiv session with access to the publication. The same URL is returned on every create, update, or show. Supports optional query parameters to preview as a specific audience: `platform` (`email` default, or `web`), `subscriber_type` (`free` default, or `premium` - requires `tier_ids[]`), `tier_ids[]` (one or more tier ids, only used when `subscriber_type=premium`), and `subscriber_id` (renders using that subscriber's real tier memberships and takes precedence over `subscriber_type`/`tier_ids[]`).
- `meta_default_description` (string, optional) — Meta tag description for the post, called SEO Description in the admin UI
- `meta_default_title` (string, optional) — meta tag title for the post, called SEO Title in the admin UI
- `newsletter_list_id` (string, optional) — The prefixed ID of the newsletter list this post is associated with. When set, the post targets only subscribers of this newsletter list.
- `recipients` (PostRecipientsResponse, optional) — The targeting configuration for this post.
- `recipient_count` (integer, optional) — Estimated (draft/confirmed) or actual (sent) number of email subscribers targeted by this post.
- `headers` (map from string to string, optional) — Custom email headers set on this post. A `null` value is a suppression marker for a header inherited from the newsletter list or publication.
- `header_custom_css` (string, optional) — The custom CSS added to this post's email `<head>`, including CSS that comes from the publication's email style. Returned when retrieving or updating a single post, not when listing posts.
- `from_address` (string, optional) — The from address for this post. If not set, falls back to the publication default.
- `reply_to_address` (string, optional) — The reply-to address replies to this post will go to. If not set on the post, falls back to the newsletter list it sends to, then the publication default, then the workspace owner.
- `sender_name` (string, optional) — The sender name preset composition key set on this post. If not set, falls back to the newsletter list or publication.
- `utm_source` (string, optional) — The utm_source set on this post. If not set, falls back to the newsletter list or publication.
- `utm_medium` (string, optional) — The utm_medium set on this post. If not set, falls back to the newsletter list or publication.
- `utm_campaign` (string, optional) — The utm_campaign set on this post. If not set, falls back to the newsletter list or publication.
- `utm_params_enabled` (boolean, optional) — Whether UTM parameters are appended to links in this post. If not set, falls back to the newsletter list or publication.
- `content` (PostContent, optional) — 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. **Note:** Generating HTML is slow. We recommend only requesting the HTML versions you need at the time.
- `stats` (PostStats, optional) — Optional list of stats for a post. Retrievable by including `expand: [stats]` in the post request body. **Note:** If a timeout occurs while aggregating stats, subsequent requests may return consolidated click metrics rather than individual raw click metrics.

### PostProcessingData

- `id` (string, required) — The prefixed post id. Stable — this is the id the post will have once created.
- `state` (enum, required) — The background creation state of the post.
  - Allowed values: `pending`

### ErrorDetail

- `message` (string, required)
- `code` (string, required)

### ParagraphBlockTextSection

- `text` (string, required) — The text content of the paragraph.
- `styling` (list of enum, optional) — The inline styles for the text.
  - Allowed values: `bold`, `italic`, `underline`, `strikethrough`
- `text_color` (string, optional) — The CSS color value for the text.
- `highlight_color` (string, optional) — The CSS color value for the text highlight.
- `link` (Link, optional) — The link of the text.

### VisibilitySettings

- `show_on_web` (boolean, optional) — Whether to show the block on the web.
- `show_on_email` (boolean, optional) — Whether to show the block on the email.
- `show_to_anonymous_users_web` (boolean, optional) — Whether to show the block to anonymous users on the web.
- `show_to_free_subscribers` (boolean, optional) — Whether to show the block to free subscribers.
- `show_to_paid_subscribers` (boolean, optional) — Whether to show the block to paid subscribers.
- `show_to_subscribers_with_referral_value` (integer, optional) — The exact referral count required to show the block to subscribers.
- `show_to_subscribers_with_referral_condition` (enum, optional) — The condition required to show the block to subscribers.
  - Allowed values: `eq`, `gt`, `lt`
- `condition_set_ids` (list of string, optional) — 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` (enum, optional) — 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.
  - Allowed values: `and`, `or`

### VisualSettings

- `background_color` (string, optional) — The background color of the block.
- `text_color` (string, optional) — The text color of the block.
- `border_color` (string, optional) — The border color of the block.
- `border_style` (enum, optional) — The border style of the block.
  - Allowed values: `solid`, `dashed`, `dotted`
- `border_width` (integer, optional) — The border width of the block.
- `border_width_top` (integer, optional) — The border width of the top of the block.
- `border_width_bottom` (integer, optional) — The border width of the bottom of the block.
- `border_width_left` (integer, optional) — The border width of the left of the block.
- `border_width_right` (integer, optional) — The border width of the right of the block.
- `border_radius` (integer, optional) — The border radius of the block.
- `border_radius_top_left` (integer, optional) — The border radius of the top left of the block.
- `border_radius_top_right` (integer, optional) — The border radius of the top right of the block.
- `border_radius_bottom_left` (integer, optional) — The border radius of the bottom left of the block.
- `border_radius_bottom_right` (integer, optional) — The border radius of the bottom right of the block.
- `inner_spacing` (integer, optional) — The inner spacing of the block.
- `inner_spacing_top` (integer, optional) — The inner spacing of the top of the block.
- `inner_spacing_bottom` (integer, optional) — The inner spacing of the bottom of the block.
- `inner_spacing_left` (integer, optional) — The inner spacing of the left of the block.
- `inner_spacing_right` (integer, optional) — The inner spacing of the right of the block.
- `outer_spacing` (integer, optional) — The outer spacing of the block.
- `outer_spacing_top` (integer, optional) — The outer spacing of the top of the block.
- `outer_spacing_bottom` (integer, optional) — The outer spacing of the bottom of the block.
- `outer_spacing_left` (integer, optional) — The outer spacing of the left of the block.
- `outer_spacing_right` (integer, optional) — The outer spacing of the right of the block.

### ColumnBlock

- `blocks` (list of EmbeddableBlocks, required) — The blocks that make up the column.
- `position` (enum, optional) — The column position. This field is deprecated but supported for existing column layouts.
  - Allowed values: `left`, `right`
- `width` (integer, optional) — The column width percentage. When omitted, width is calculated automatically.
- `verticalAlign` (enum, optional) — The vertical alignment of the column content.
  - Allowed values: `top`, `middle`, `bottom`

### ListBlockItem

A list item as either plain text or formatted text data.

- string
- List Block Item Data: ListBlockItemData

### TableCellData

- `text` (string, optional) — The text content of the cell.
- `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the cell.
- `alignment` (enum, optional) — The text alignment of the cell.
  - Allowed values: `left`, `center`, `right`
- `colspan` (integer, optional, default: 1) — The number of columns the cell spans.
- `rowspan` (integer, optional, default: 1) — The number of rows the cell spans.

### SectionableBlock

A block that can appear inside a section. Excludes `section` and `columns` (TipTap's schema does not allow nested sections).

- `type`: `paragraph`
  - `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the paragraph.
  - `plaintext` (string, optional) — The plaintext content of the paragraph.
  - `textAlign` (enum, optional) — Legacy paragraph alignment field. Use `textAlignment` for new integrations.
    - Allowed values: `left`, `center`, `right`
  - `textAlignment` (enum, optional) — The text alignment of the paragraph (e.g., left, center, right).
    - Allowed values: `left`, `center`, `right`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `image`
  - `imageUrl` (string, required) — The URL of the image.
  - `alt_text` (string, optional) — Alternative text for the image.
  - `caption` (string, optional) — A caption for the image.
  - `captionAlignment` (enum, optional) — The text alignment of the caption.
    - Allowed values: `left`, `center`, `right`
  - `imageAlignment` (enum, optional) — The text alignment of the image.
    - Allowed values: `left`, `center`, `right`
  - `title` (string, optional) — The title of the image.
  - `url` (string, optional) — The URL that the image should link to.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
  - `width` (integer, optional) — The width of the image. Should be between 1 and 100.
- `type`: `button`
  - `href` (string, required) — The URL the button should use.
  - `text` (string, required) — The text content of the button.
  - `alignment` (enum, optional) — The text alignment of the button.
    - Allowed values: `left`, `center`, `right`
  - `size` (enum, optional) — The size of the button (e.g., small, normal, large).
    - Allowed values: `small`, `normal`, `large`
  - `target` (string, optional) — The target of the button (e.g., _blank).
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `heading`
  - `level` (enum, required) — The level of the header (e.g., 1, 2, 3, etc.).
    - Allowed values: `1`, `2`, `3`, `4`, `5`, `6`
  - `anchorHeader` (boolean, optional, default: true) — Whether the header should be an anchor header.
  - `anchorIncludeInToc` (boolean, optional, default: true) — Whether the header should be included in the table of contents.
  - `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the header, supporting links and inline styling.
  - `text` (string, optional) — The text content of the header. Ignored if `formattedText` is provided.
  - `textAlignment` (enum, optional) — The text alignment of the header (e.g., left, center, right).
    - Allowed values: `left`, `center`, `right`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `rss`
  - `articleLayout` (enum, optional) — The layout of the articles from the feed.
    - Allowed values: `1-col`, `2-col`, `3-col`, `4-col`
  - `articlesToShow` (integer, optional) — The number of articles to show from the feed.
  - `ctaAlignment` (enum, optional) — The alignment of the call to action.
    - Allowed values: `Left`, `Center`, `Right`
  - `ctaStyle` (enum, optional) — The style of the call to action.
    - Allowed values: `CTA button`, `CTA link`, `Title as link`, `Thumbnail as link`, `Title and thumbnail as link`
  - `ctaText` (string, optional) — The text of the call to action. Applicable if ctaStyle is button or link.
  - `externalRssFeedId` (string, optional) — The ID of the external RSS feed.
  - `refreshOnSend` (boolean, optional) — Whether or not to refresh the contents from the RSS feed before sending out the email.
  - `rssFeedUrl` (string, optional) — The URL of the RSS feed.
  - `selectionMode` (enum, optional) — How to select feed articles, by count or time window.
    - Allowed values: `count`, `time`
  - `showArticleThumbnail` (boolean, optional) — Whether to show the article thumbnail.
  - `showArticleTitle` (boolean, optional) — Whether to show the article title.
  - `showAuthor` (boolean, optional) — Whether to show the author.
  - `showCategories` (boolean, optional) — Whether to show the categories.
  - `showContent` (boolean, optional) — Whether to show the article content.
  - `showCta` (boolean, optional) — Whether to show a call to action.
  - `showDescription` (boolean, optional) — Whether to show the article description.
  - `showPublishedDate` (boolean, optional) — Whether to show the date the article was published
  - `thumbnailPosition` (enum, optional) — The position of the thumbnail.
    - Allowed values: `Above Title`, `Below Title`, `Left of content`, `Right of content`, `Alternating Horizontally`
  - `timeWindowHours` (integer, optional) — Trailing window in hours when selectionMode is time.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `advertisement`
  - `opportunity_id` (string, required) — The ID of the Advertisement opportunity.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `advertisement_logo`
  - `opportunity_id` (string, required) — The ID of the advertisement opportunity whose logo to display.
  - `override_sponsor_text` (enum, required) — The sponsor text to display with the advertisement logo. Required.
    - Allowed values: `sponsored_by`, `together_with`, `in_partnership_with`, `presented_by`, `todays_sponsor`
  - `override_align` (enum, optional) — The logo alignment. Defaults to center.
    - Allowed values: `left`, `center`, `right`
  - `override_width` (integer, optional) — The logo width as a percentage. Must be greater than 0. Defaults to 100.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `list`
  - `items` (list of ListBlockItem, required) — The items in the list.
  - `listType` (enum, optional) — The type of list (e.g., ordered, unordered).
    - Allowed values: `ordered`, `unordered`
  - `startNumber` (integer, optional) — The number to start the list at. Only applicable if listType is ordered.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `table`
  - `rows` (list of list of TableCellData, required) — The rows of the table.
  - `headerColumn` (boolean, optional, default: false) — Whether the first column is a header column.
  - `headerRow` (boolean, optional, default: true) — Whether the first row is a header row.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `html`
  - `html` (string, required) — The raw HTML content. Note that `<style>` and `<link>` tags are removed during sanitization — use inline styles for all visual styling.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `embed_link`
  - `url` (string, required) — The URL of the embed link.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `poll`
  - `poll_id` (string, required) — The ID of the poll you wish to include.
  - `show_options_initially` (boolean, optional) — Whether to show the poll options initially. Defaults to false.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `quote`
  - `quote` (string, required) — The text of the quote.
  - `alignment` (enum, optional) — The text alignment of the quote. Defaults depend on the variant.
    - Allowed values: `left`, `center`, `right`
  - `author` (string, optional) — The author of the quote.
  - `variant` (enum, optional) — The type of quote block. Defaults to "block".
    - Allowed values: `block`, `inline`, `quotation`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `content_break`
- `type`: `paywall_break`
  - `paywall_id` (string, required) — The ID of the paywall.

### PostWebRecipients

- `tier_ids` (list of string, optional) — 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` (list of string, optional)
- `exclude_segment_ids` (list of string, optional)

### PostEmailRecipients

- `tier_ids` (list of string, optional) — 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. Cannot be combined with `include_segment_ids`.
- `include_segment_ids` (list of string, optional) — Cannot be combined with `tier_ids`.
- `exclude_segment_ids` (list of string, optional)

### PostRecipientsResponse

The targeting configuration currently set on the post.

- `web` (PostWebRecipientsResponse, optional) — Web targeting configuration. Absent if the post has no web targets.
- `email` (PostEmailRecipientsResponse, optional) — Email targeting configuration. Absent if the post has no email targets.

### PostContent

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. **Note:** Generating HTML is slow. We recommend only requesting the HTML versions you need at the time.

- `free` (FreePostContent, optional) — The requested free post HTML. This HTML has paywalls enforced.
- `premium` (PremiumPostContent, optional) — The requested premium post HTML. This HTML does not have paywalls enforced.

### PostStats

Optional list of stats for a post. Retrievable by including `expand: [stats]` in the post request body. **Note:** If a timeout occurs while aggregating stats, subsequent requests may return consolidated click metrics rather than individual raw click metrics.

- `email` (PostStatsEmail, optional) — Stats scoped only to email recipients. Not relevant for posts published only to web
- `web` (PostStatsWeb, optional) — Stats scoped only to web views. Not relevant for posts published only to email
- `clicks` (list of ClickStats, optional) — An array of click statistics for each URL in the post
- `upgrades` (integer, optional, default: 0) — Total number of free-to-premium upgrades attributed to this post. Only populated when the publication has a paid subscription tier.

### Link

- `href` (string, required) — The URL of the link.
- `target` (string, optional) — The target of the link (e.g., _blank).

### EmbeddableBlocks

A block in the post content that can be embedded within a column.

- `type`: `paragraph`
  - `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the paragraph.
  - `plaintext` (string, optional) — The plaintext content of the paragraph.
  - `textAlign` (enum, optional) — Legacy paragraph alignment field. Use `textAlignment` for new integrations.
    - Allowed values: `left`, `center`, `right`
  - `textAlignment` (enum, optional) — The text alignment of the paragraph (e.g., left, center, right).
    - Allowed values: `left`, `center`, `right`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `image`
  - `imageUrl` (string, required) — The URL of the image.
  - `alt_text` (string, optional) — Alternative text for the image.
  - `caption` (string, optional) — A caption for the image.
  - `captionAlignment` (enum, optional) — The text alignment of the caption.
    - Allowed values: `left`, `center`, `right`
  - `imageAlignment` (enum, optional) — The text alignment of the image.
    - Allowed values: `left`, `center`, `right`
  - `title` (string, optional) — The title of the image.
  - `url` (string, optional) — The URL that the image should link to.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
  - `width` (integer, optional) — The width of the image. Should be between 1 and 100.
- `type`: `button`
  - `href` (string, required) — The URL the button should use.
  - `text` (string, required) — The text content of the button.
  - `alignment` (enum, optional) — The text alignment of the button.
    - Allowed values: `left`, `center`, `right`
  - `size` (enum, optional) — The size of the button (e.g., small, normal, large).
    - Allowed values: `small`, `normal`, `large`
  - `target` (string, optional) — The target of the button (e.g., _blank).
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `heading`
  - `level` (enum, required) — The level of the header (e.g., 1, 2, 3, etc.).
    - Allowed values: `1`, `2`, `3`, `4`, `5`, `6`
  - `anchorHeader` (boolean, optional, default: true) — Whether the header should be an anchor header.
  - `anchorIncludeInToc` (boolean, optional, default: true) — Whether the header should be included in the table of contents.
  - `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the header, supporting links and inline styling.
  - `text` (string, optional) — The text content of the header. Ignored if `formattedText` is provided.
  - `textAlignment` (enum, optional) — The text alignment of the header (e.g., left, center, right).
    - Allowed values: `left`, `center`, `right`
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `rss`
  - `articleLayout` (enum, optional) — The layout of the articles from the feed.
    - Allowed values: `1-col`, `2-col`, `3-col`, `4-col`
  - `articlesToShow` (integer, optional) — The number of articles to show from the feed.
  - `ctaAlignment` (enum, optional) — The alignment of the call to action.
    - Allowed values: `Left`, `Center`, `Right`
  - `ctaStyle` (enum, optional) — The style of the call to action.
    - Allowed values: `CTA button`, `CTA link`, `Title as link`, `Thumbnail as link`, `Title and thumbnail as link`
  - `ctaText` (string, optional) — The text of the call to action. Applicable if ctaStyle is button or link.
  - `externalRssFeedId` (string, optional) — The ID of the external RSS feed.
  - `refreshOnSend` (boolean, optional) — Whether or not to refresh the contents from the RSS feed before sending out the email.
  - `rssFeedUrl` (string, optional) — The URL of the RSS feed.
  - `selectionMode` (enum, optional) — How to select feed articles, by count or time window.
    - Allowed values: `count`, `time`
  - `showArticleThumbnail` (boolean, optional) — Whether to show the article thumbnail.
  - `showArticleTitle` (boolean, optional) — Whether to show the article title.
  - `showAuthor` (boolean, optional) — Whether to show the author.
  - `showCategories` (boolean, optional) — Whether to show the categories.
  - `showContent` (boolean, optional) — Whether to show the article content.
  - `showCta` (boolean, optional) — Whether to show a call to action.
  - `showDescription` (boolean, optional) — Whether to show the article description.
  - `showPublishedDate` (boolean, optional) — Whether to show the date the article was published
  - `thumbnailPosition` (enum, optional) — The position of the thumbnail.
    - Allowed values: `Above Title`, `Below Title`, `Left of content`, `Right of content`, `Alternating Horizontally`
  - `timeWindowHours` (integer, optional) — Trailing window in hours when selectionMode is time.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `advertisement`
  - `opportunity_id` (string, required) — The ID of the Advertisement opportunity.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.
- `type`: `advertisement_logo`
  - `opportunity_id` (string, required) — The ID of the advertisement opportunity whose logo to display.
  - `override_sponsor_text` (enum, required) — The sponsor text to display with the advertisement logo. Required.
    - Allowed values: `sponsored_by`, `together_with`, `in_partnership_with`, `presented_by`, `todays_sponsor`
  - `override_align` (enum, optional) — The logo alignment. Defaults to center.
    - Allowed values: `left`, `center`, `right`
  - `override_width` (integer, optional) — The logo width as a percentage. Must be greater than 0. Defaults to 100.
  - `visibility_settings` (VisibilitySettings, optional) — Optional rules for when/where this block is shown, including dynamic content targeting via condition sets.
  - `visual_settings` (VisualSettings, optional) — Optional styling for borders, spacing, colors, etc.

### ListBlockItemData

- `text` (string, optional) — The plain text content of the list item.
- `formattedText` (list of ParagraphBlockTextSection, optional) — The formatted content of the list item.

### PostWebRecipientsResponse

- `tier_ids` (list of string, optional) — The tier IDs targeted for web. Values are `"free"`, `"premium"`, or a specific tier's prefixed ID.
- `include_segment_ids` (list of string, optional)
- `exclude_segment_ids` (list of string, optional)

### PostEmailRecipientsResponse

- `tier_ids` (list of string, optional) — The tier IDs targeted for email. Values are `"free"`, `"premium"`, or a specific tier's prefixed ID.
- `include_segment_ids` (list of string, optional)
- `exclude_segment_ids` (list of string, optional)

### FreePostContent

The requested free post HTML. This HTML has paywalls enforced.

- `web` (string, optional) — The web HTML rendered to a free or annonomous reader.
- `email` (string, optional) — The email HTML rendered to a free reader.
- `rss` (string, optional) — The HTML that is rendered in RSS feeds.

### PremiumPostContent

The requested premium post HTML. This HTML does not have paywalls enforced.

- `web` (string, optional) — The website HTML rendered to a free reader
- `email` (string, optional) — The email HTML rendered to a premium reader

### PostStatsEmail

Stats scoped only to email recipients. Not relevant for posts published only to web

- `recipients` (integer, optional, default: 0) — Total number of email recipients
- `delivered` (integer, optional, default: 0) — Total number of emails delivered
- `opens` (integer, optional, default: 0) — Total number of email opens
- `unique_opens` (integer, optional, default: 0) — Total number of unique email opens
- `open_rate` (double, optional) — The percentage of emails that have been opened
- `clicks` (integer, optional, default: 0) — Total number of email clicks
- `unique_clicks` (integer, optional, default: 0) — Unique number of email clicks
- `verified_clicks` (integer, optional, default: 0) — 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` (integer, optional, default: 0) — Unique number of verified human email clicks across all URLs in this post. Only counts the first verified click per subscriber.
- `click_rate` (double, optional) — The percentage of emails that have been clicked
- `unsubscribes` (integer, optional, default: 0) — Total number of email unsubscribes
- `spam_reports` (integer, optional, default: 0) — The number of subscribers that reported this post email as spam

### PostStatsWeb

Stats scoped only to web views. Not relevant for posts published only to email

- `views` (integer, optional, default: 0) — Total number of web views
- `clicks` (integer, optional, default: 0) — Total number of web clicks

### ClickStats

Details about specific URL's click stats from a post.

- `url` (string, optional) — The URL the stats are for
- `base_url` (string, optional) — 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` (PostClickStatsEmail, optional) — URL stats scoped only to email recipients. Not relevant for posts published only to web
- `web` (PostClickStatsWeb, optional) — Stats scoped only to web views. Not relevant for posts published only to email
- `total_clicks` (integer, optional)
- `total_unique_clicks` (integer, optional)
- `total_click_through_rate` (double, optional) — The percentage of clicks on the URL compared to the total number of recipients and web views

### PostClickStatsEmail

URL stats scoped only to email recipients. Not relevant for posts published only to web

- `clicks` (integer, optional)
- `unique_clicks` (integer, optional)
- `verified_clicks` (integer, optional) — 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` (integer, optional) — Unique number of verified human email clicks on this URL. Only counts the first verified click per subscriber.
- `click_through_rate` (double, optional) — The percentage of email clicks on the URL compared to the total number of recipients

### PostClickStatsWeb

Stats scoped only to web views. Not relevant for posts published only to email

- `clicks` (integer, optional)
- `unique_clicks` (integer, optional)
- `click_through_rate` (double, optional) — The percentage of clicks on the URL compared to the total number of web views

## Examples

### Example 1

**Request**

```json
{
  "title": "Updated Post Title",
  "subtitle": "Fixed a typo in the subtitle",
  "email_settings": {
    "email_subject_line": "Updated subject line"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "post_00000000-0000-0000-0000-000000000000",
    "subtitle": "Fixed a typo in the subtitle",
    "title": "Updated Post Title",
    "authors": [
      "John Doe"
    ],
    "created": 1710300000,
    "status": "confirmed",
    "split_tested": false,
    "subject_line": "Updated subject line",
    "preview_text": "Preview text",
    "slug": "updated-post-title",
    "thumbnail_url": "",
    "web_url": "https://example.beehiiv.com/p/updated-post-title",
    "audience": "both",
    "platform": "both",
    "content_tags": [],
    "hidden_from_feed": false,
    "enforce_gated_content": false,
    "email_capture_popup": false,
    "publish_date": 1710300060,
    "displayed_date": null,
    "preview_url": "https://app.beehiiv.com/posts/post_00000000-0000-0000-0000-000000000000/preview",
    "meta_default_description": null,
    "meta_default_title": null,
    "newsletter_list_id": null
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000"

payload = {
    "title": "Updated Post Title",
    "subtitle": "Fixed a typo in the subtitle",
    "email_settings": { "email_subject_line": "Updated subject line" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"Updated Post Title","subtitle":"Fixed a typo in the subtitle","email_settings":{"email_subject_line":"Updated subject line"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000"

	payload := strings.NewReader("{\n  \"title\": \"Updated Post Title\",\n  \"subtitle\": \"Fixed a typo in the subtitle\",\n  \"email_settings\": {\n    \"email_subject_line\": \"Updated subject line\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Updated Post Title\",\n  \"subtitle\": \"Fixed a typo in the subtitle\",\n  \"email_settings\": {\n    \"email_subject_line\": \"Updated subject line\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Updated Post Title\",\n  \"subtitle\": \"Fixed a typo in the subtitle\",\n  \"email_settings\": {\n    \"email_subject_line\": \"Updated subject line\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000', [
  'body' => '{
  "title": "Updated Post Title",
  "subtitle": "Fixed a typo in the subtitle",
  "email_settings": {
    "email_subject_line": "Updated subject line"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"title\": \"Updated Post Title\",\n  \"subtitle\": \"Fixed a typo in the subtitle\",\n  \"email_settings\": {\n    \"email_subject_line\": \"Updated subject line\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "title": "Updated Post Title",
  "subtitle": "Fixed a typo in the subtitle",
  "email_settings": ["email_subject_line": "Updated subject line"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts/post_00000000-0000-0000-0000-000000000000")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2

**Request**

```json
{}
```

**Response**

```json
{
  "data": {
    "id": "string",
    "state": "pending"
  },
  "status": 0,
  "statusText": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/publications/%3ApublicationId/posts/%3ApostId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```