> 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 post template <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>

POST https://api.beehiiv.com/v2/publications/{publicationId}/post_templates
Content-Type: application/json

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

Create a post template for a specific publication. Posts created from the template start with its content and settings.

Content is optional: a template created without `blocks` or `body_content` starts with an empty body. Provide one or the other, never both.

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

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

### 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. Supports the same block types as Create Post, with the exception of `advertisement`: an advertisement opportunity is booked for a single send and cannot be stored on a template.
- `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 — use inline styles for all visual styling.
- `thumbnail_image_url` (string, optional) — The URL of the thumbnail image to download for the template.
- `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`
- `content_tags` (list of string, optional) — The content tags posts built from this template start with. Tags that do not exist on the publication are created.
- `guest_author_ids` (list of string, optional) — The prefixed IDs of the guest authors posts built from this template start with. Guest authors must belong to the publication.
- `team_author_ids` (list of string, optional) — The prefixed IDs of the team members posts built from this template start with as authors. Team authors must have access to the publication.
- `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.
- `header_custom_css` (string, optional) — Custom CSS added to the email `<head>` of posts built from this template. Use this for styles, since `<style>` tags in `body_content` are removed. Applies to email only, not the web version.
- `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.
- `newsletter_list_id` (string, optional) — The prefixed ID of the newsletter list posts built from this template are associated with.
- `email_settings` (PostTemplateEmailSettings, optional) — The email settings posts built from this template start with.
- `web_settings` (PostTemplateWebSettings, optional) — The web settings posts built from this template start with.

## Response

### 201

Created

- `data` (PostTemplateDetail, 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)

### 404 Not Found Error

Resource Not Found

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

### PostTemplateEmailSettings

- `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.
- `from_address` (string, optional) — The address the email is sent from.
- `reply_to_address` (string, optional) — The address replies are directed to.
- `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`.

### PostTemplateWebSettings

- `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.
- `paywall_id` (string, optional) — The prefixed ID of the paywall applied at the template's paywall break.
- `paywall_break_price_id` (string, optional) — The price offered at the template's paywall break. Templates created in the beehiiv app store this as a bare UUID, so it is not returned as a prefixed ID.

### PostTemplateDetail

- `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.
- `authors` (list of string, required) — The names of the authors posts built from this template start with.
- `content_tags` (list of string, required) — The content tags posts built from this template start with.
- `email_settings` (PostTemplateEmailSettings, required) — The email settings posts built from this template start with.
- `web_settings` (PostTemplateWebSettings, required) — The web settings posts built from this template start with.
- `description` (string, optional) — The description of the post template.
- `thumbnail_url` (string, optional) — The URL of the post template's thumbnail image.
- `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`
- `newsletter_list_id` (string, optional) — The prefixed ID of the newsletter list associated with this template.
- `headers` (map from string to string, optional) — Custom email headers posts built from this template start with.
- `header_custom_css` (string, optional) — The custom CSS added to the email `<head>` of posts built from this template. `null` when there is none.
- `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.
- `content` (PostContent, optional) — The rendered HTML of the template, returned only for the variants named in `expand`.

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

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

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

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

## Examples

**Request**

```json
{
  "name": "Newsletter Template"
}
```

**Response**

```json
{
  "data": {
    "id": "post_template_00000000-0000-0000-0000-000000000000",
    "name": "Newsletter Template",
    "created": 1666800000,
    "updated": 1666800000,
    "authors": [],
    "content_tags": [],
    "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,
      "from_address": "hello@example.com",
      "reply_to_address": 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,
      "paywall_id": null,
      "paywall_break_price_id": null
    },
    "description": null,
    "thumbnail_url": null,
    "newsletter_list_id": null,
    "headers": null,
    "header_custom_css": 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/publications/pub_00000000-0000-0000-0000-000000000000/post_templates"

payload = { "name": "Newsletter Template" }
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/publications/pub_00000000-0000-0000-0000-000000000000/post_templates';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Newsletter Template"}'
};

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

	payload := strings.NewReader("{\n  \"name\": \"Newsletter Template\"\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/publications/pub_00000000-0000-0000-0000-000000000000/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\": \"Newsletter Template\"\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/publications/pub_00000000-0000-0000-0000-000000000000/post_templates")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Newsletter Template\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/post_templates', [
  'body' => '{
  "name": "Newsletter Template"
}',
  '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/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\": \"Newsletter Template\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["name": "Newsletter Template"] 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/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()
```