Create post OAuth Scope: posts:write
Create post OAuth Scope: posts:write
<Note title="Currently in beta" icon="b">
This feature is currently in beta, the API is subject to change, and available only to Enterprise users.<br/><br/>To inquire about Enterprise pricing,
please visit our <a href="https://www.beehiiv.com/enterprise">Enterprise page</a>.
</Note>
Create a post for a specific publication. For a detailed walkthrough including setup, testing workflows, and working with custom HTML and templates, see the <a href="https://www.beehiiv.com/support/article/36759164012439-using-the-send-api-and-create-post-endpoint">Using the Send API and Create Post Endpoint</a> guide.
## Content methods
There are three ways to provide content for a post. You must provide either `blocks` or `body_content`, but not both.
### 1. Blocks
Use the `blocks` field to build your post with structured content blocks such as paragraphs, images, headings, buttons, tables, and more. Each block has a `type` and its own set of properties. This method gives you fine-grained control over individual content elements and supports features like visual settings, visibility settings, and dynamic content targeting.
### 2. Raw HTML (`body_content`)
Use the `body_content` field to provide a single string of raw HTML. The HTML is wrapped in an `htmlSnippet` block internally. This is useful when you have pre-built HTML content or are migrating from another platform.
### 3. HTML blocks within blocks
Use `type: html` blocks inside the `blocks` array to embed raw HTML snippets alongside other structured blocks. This lets you mix structured content (paragraphs, images, etc.) with custom HTML where needed.
## CSS and styling guardrails
beehiiv processes all HTML content through a sanitization pipeline. When using `body_content` or `html` blocks, be aware of the following:
- **`<style>` tags are removed.** All `<style>` block elements are stripped during sanitization. Do not rely on embedded stylesheets.
- **`<link>` tags are removed.** External stylesheet references are not allowed.
- **Inline styles are preserved.** Styles applied directly to elements via the `style` attribute (e.g., `<div style="color: red;">`) are kept intact.
- **CSS classes have no effect.** While class attributes are not stripped, no corresponding stylesheets are loaded to apply them.
- **beehiiv's email template wraps your content.** Your HTML is rendered inside beehiiv's email table structure, which applies its own layout and spacing. This may affect the appearance of your content.
- **Use inline styles for all visual styling.** Since `<style>` and `<link>` tags are removed, inline styles on individual elements are the only reliable way to control appearance.
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
publicationId
The prefixed ID of the publication object
Request
This endpoint expects an object.
title
The title of the post.
blocks
The structured content blocks that make up the post. Supports block types such as paragraph, image, heading, button, html, table, list, columns, and more. You can embed raw HTML snippets within blocks using the html block type. Either this field OR the body_content field must be provided.
body_content
The content of the post as a single raw HTML string. The HTML is wrapped in an htmlSnippet block internally. Note that <style> and <link> tags are removed during sanitization — use inline styles for all visual styling. Either this field OR the blocks field must be provided.
subtitle
The subtitle of the post.
post_template_id
The ID of the template to use for the post. If not provided, the default template will be used.
status
The status of the post. If not provided, the default (`confirmed`) value will be used and the post will either publish immediately (if no `scheduled_at` is provided) or at the `scheduled_at` time. **Deprecation notice:** The default will change to `draft` in a future release. Explicitly pass `confirmed` to preserve current auto-publish behavior.
Allowed values:
scheduled_at
The time in which the post will be published. If not provided, the post will be published immediately unless status is set to draft. A draft post cannot be scheduled.
custom_link_tracking_enabled
If true, custom link tracking will be enabled for this post. If not provided, the default value will be used.
email_capture_type_override
The email capture type to use for this post. If not provided, the default value will be used.
Allowed values:
override_scheduled_at
If you wish to display a date other than the scheduled_at date in the email, you can provide a date here. This will not affect the actual publish date of the post.
thumbnail_image_url
The URL of the thumbnail image to use for the post. If not provided, the default value will be used.
recipients
The recipients to use for this post. If not provided, the default value will be used.
email_settings
The email settings to use for this post. If not provided, the default value will be used.
web_settings
The web settings to use for this post. If not provided, the default value will be used.
seo_settings
The metadata to use for this post. If not provided, the default value will be used.
headers
The headers to use for this post. If not provided, the default value will be used.
custom_fields
The custom fields to use for this post. If not provided, the default value will be used.
Response
Created
data
Errors
400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
