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

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

POST https://api.beehiiv.com/v2/workspaces/post_templates
Content-Type: application/json

This feature is currently in beta and the API is subject to change.

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

Create a post template that belongs to the workspace, so every publication in the workspace can start a post from it. A workspace template holds only what does not depend on a publication. Newsletter lists, sending addresses, paywalls, content tags, authors and thumbnails belong to a single publication and are not accepted. Blocks that need a publication (`automated_advertisement_placement`, `embed_link`, `paywall_break`, `poll`, `programmatic_ads_logo` and `rss`), condition sets in `visibility_settings`, and button blocks with a relative `href` are refused. As on every post template, `advertisement` blocks are refused too. Requires an API key with access to every publication in the workspace.

Reference: https://developers.beehiiv.com/api-reference/post-templates/workspace-create

## Authentication

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

## Request

### Body (application/json)

This endpoint expects an object.

- `name` (string, required) — The name of the post template.
- `description` (string, optional) — The description of the post template.
- `blocks` (list of Block, optional) — The structured content blocks posts built from this template start with. Blocks that need a publication are refused; see the endpoint description.
- `body_content` (string, optional) — The content posts built from this template start with, 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, so use inline styles for all visual styling.
- `social_share` (enum, optional) — The social share style posts built from this template start with.
  - Allowed values: `comments_and_likes_only`, `with_comments_and_likes`, `top`, `none`
- `email_capture_type_override` (enum, optional) — The email capture type posts built from this template start with.
  - Allowed values: `none`, `gated`, `popup`
- `headers` (map from string to string, optional) — Custom email headers posts built from this template start with. 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.
- `utm_source` (string, optional) — The utm_source appended to links in posts built from this template.
- `utm_medium` (string, optional) — The utm_medium appended to links in posts built from this template.
- `utm_campaign` (string, optional) — The utm_campaign appended to links in posts built from this template.
- `utm_params_enabled` (boolean, optional) — Whether UTM parameters are appended to links in posts built from this template. Omit to inherit from the newsletter list, then the publication.
- `email_settings` (WorkspacePostTemplateEmailSettings, optional) — The email settings posts built from this template start with.
- `web_settings` (WorkspacePostTemplateWebSettings, optional) — The web settings posts built from this template start with.

## Response

### 201

Created

- `data` (WorkspacePostTemplateDetail, required)

## Errors

### 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)

### 422 Unprocessable Entity Error

Unprocessable Entity

- `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`
  - `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.).

### WorkspacePostTemplateEmailSettings

- `display_title_in_email` (boolean, optional) — Whether the title is displayed in the email.
- `display_byline_in_email` (boolean, optional) — Whether the byline is displayed in the email.
- `display_subtitle_in_email` (boolean, optional) — Whether the subtitle is displayed in the email.
- `email_header_engagement_buttons` (boolean, optional) — Whether the engagement buttons are displayed in the email header.
- `email_header_social_share` (boolean, optional) — Whether the social share links are displayed in the email header.
- `email_preview_text` (string, optional) — The preview text of the email.
- `email_subject_line` (string, optional) — The subject line of the email.
- `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`. Resolved against the publication a post is built for.

### WorkspacePostTemplateWebSettings

- `title` (string, optional) — The headline posts built from this template start with.
- `subtitle` (string, optional) — The subtitle posts built from this template start with.
- `display_title_on_web` (boolean, optional) — Whether the title is displayed on the web.
- `display_subtitle_on_web` (boolean, optional) — Whether the subtitle is displayed on the web.
- `display_thumbnail_on_web` (boolean, optional) — Whether the thumbnail is displayed on the web.

### WorkspacePostTemplateDetail

- `id` (string, required) — The prefixed ID of the post template.
- `name` (string, required) — The name of the post template.
- `created` (integer, required) — When the post template was created. Measured in seconds since the Unix epoch.
- `updated` (integer, required) — When the post template was last updated. Measured in seconds since the Unix epoch.
- `email_settings` (WorkspacePostTemplateEmailSettings, required) — The email settings posts built from this template start with.
- `web_settings` (WorkspacePostTemplateWebSettings, required) — The web settings posts built from this template start with.
- `description` (string, optional) — The description of the post template.
- `social_share` (enum, optional) — The social share style posts built from this template start with. Omitted when the template does not set one.
  - Allowed values: `comments_and_likes_only`, `with_comments_and_likes`, `top`, `none`
- `email_capture_type_override` (enum, optional) — The email capture type posts built from this template start with. Omitted when the template does not set one.
  - Allowed values: `none`, `gated`, `popup`
- `headers` (map from string to string, optional) — Custom email headers posts built from this template start with.
- `utm_source` (string, optional) — The utm_source appended to links in posts built from this template.
- `utm_medium` (string, optional) — The utm_medium appended to links in posts built from this template.
- `utm_campaign` (string, optional) — The utm_campaign appended to links in posts built from this template.
- `utm_params_enabled` (boolean, optional) — Whether UTM parameters are appended to links in posts built from this template.

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

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

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

## Examples

**Request**

```json
{
  "name": "Workspace announcement"
}
```

**Response**

```json
{
  "data": {
    "id": "post_template_00000000-0000-0000-0000-000000000000",
    "name": "Workspace announcement",
    "created": 1700000000,
    "updated": 1700000000,
    "email_settings": {
      "display_title_in_email": true,
      "display_byline_in_email": false,
      "display_subtitle_in_email": true,
      "email_header_engagement_buttons": null,
      "email_header_social_share": null,
      "email_preview_text": null,
      "email_subject_line": null,
      "sender_name": null
    },
    "web_settings": {
      "title": null,
      "subtitle": null,
      "display_title_on_web": true,
      "display_subtitle_on_web": true,
      "display_thumbnail_on_web": false
    },
    "description": null,
    "headers": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_params_enabled": null
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.beehiiv.com/v2/workspaces/post_templates"

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

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

print(response.json())
```

```javascript
const url = 'https://api.beehiiv.com/v2/workspaces/post_templates';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Workspace announcement"}'
};

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/workspaces/post_templates"

	payload := strings.NewReader("{\n  \"name\": \"Workspace announcement\"\n}")

	req, _ := http.NewRequest("POST", 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/workspaces/post_templates")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Workspace announcement\"\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.post("https://api.beehiiv.com/v2/workspaces/post_templates")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Workspace announcement\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beehiiv.com/v2/workspaces/post_templates', [
  'body' => '{
  "name": "Workspace announcement"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.beehiiv.com/v2/workspaces/post_templates");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Workspace announcement\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

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

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/workspaces/post_templates")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```

> Build your audience with beehiiv's API and SDKs. Create new subscribers and posts, get real-time notifications of subscription activity, and more.