Create post template OAuth Scope: posts:write

POST

https://api.beehiiv.com/v2/publications/:publicationId/post_templates

POST

/v2/publications/:publicationId/post_templates

curl -X POST https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/post_templates \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Newsletter Template"
}'

{
  "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": "[email protected]",
      "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,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_params_enabled": null
  }
}

Available on the Max and Enterprise plans

This endpoint is available to publications on the Max 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.

<Note title="Available on the Max and Enterprise plans"> This endpoint is available to publications on the Max and Enterprise plans. </Note> 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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

Request

This endpoint expects an object.

namestringRequired

The name of the post template.

descriptionstringOptional

The description of the post template.

blockslist of objectsOptional

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_contentstringOptional

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_urlstringOptional

The URL of the thumbnail image to download for the template.

social_shareenumOptional

The social share style posts built from this template start with.

Allowed values:

email_capture_type_overrideenumOptional

The email capture type posts built from this template start with.

Allowed values:

content_tagslist of stringsOptional

The content tags posts built from this template start with. Tags that do not exist on the publication are created.

guest_author_idslist of stringsOptional

The prefixed IDs of the guest authors posts built from this template start with. Guest authors must belong to the publication.

team_author_idslist of stringsOptional

The prefixed IDs of the team members posts built from this template start with as authors. Team authors must have access to the publication.

headersmap from strings to optional stringsOptional

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_sourcestringOptional

The utm_source appended to links in posts built from this template.

utm_mediumstringOptional

The utm_medium appended to links in posts built from this template.

utm_campaignstringOptional

The utm_campaign appended to links in posts built from this template.

utm_params_enabledbooleanOptional

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_idstringOptional

The prefixed ID of the newsletter list posts built from this template are associated with.

email_settingsobjectOptional

The email settings posts built from this template start with.

web_settingsobjectOptional

The web settings posts built from this template start with.

Response

Created

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error