Create asset version

POST

assets

{id}

versions

curl --request POST \
  --url https://api.posta.co/assets/{id}/versions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "id": "astv_2jyk1xYhW4n0vVfHirU5eJeXsbw",
  "status": "draft",
  "notes": "Minor changes to the footer.",
  "content": {
    "source": "inline",
    "type": "text/html",
    "content": "<html><body>Hello {{firstName}}</body></html>"
  },
  "variableDefinitions": [
    {
      "name": "name",
      "behavior": "required",
      "allowEmpty": false
    }
  ],
  "contentType": "text/html",
  "contentLength": 100,
  "contentUrl": "https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content",
  "publish": false,
  "createdAt": "2023-06-07T12:34:56Z",
  "modifiedAt": "2023-06-07T12:34:56Z"
}'

{
  "id": "astv_2jyk1xYhW4n0vVfHirU5eJeXsbw",
  "status": "draft",
  "notes": "Minor changes to the footer.",
  "content": {
    "source": "inline",
    "type": "text/html",
    "content": "<html><body>Hello {{firstName}}</body></html>"
  },
  "variableDefinitions": [
    {
      "name": "name",
      "behavior": "required",
      "allowEmpty": false
    }
  ],
  "contentType": "text/html",
  "contentLength": 100,
  "contentUrl": "https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content",
  "publish": false,
  "createdAt": "2023-06-07T12:34:56Z",
  "modifiedAt": "2023-06-07T12:34:56Z"
}

The new version will be in ‘draft’ status by default.

Authorizations

X-Api-Key

string

header

required

Headers

Idempotency-Key

string

Unique idempotency key for each request (e.g., V4 UUID).

Path Parameters

string

required

The unique identifier of the asset to create a new version for. Format: 'ast_' followed by alphanumeric characters.

Body

application/json

Represents a specific version of an Asset, containing the actual content and metadata. Asset Versions are the core entities for version control, compliance tracking, and content management in Posta.

Key aspects:

Content: Can be HTML templates (with variable support), images, fonts, or documents (e.g., PDFs).
Status: Determines the overall status of the parent Asset (draft, published, archived, or deleted).
Version Control: Allows tracking changes and maintaining multiple iterations of an Asset.
Compliance: Facilitates auditing and regulatory compliance through versioning.

HTML templates can use variables for dynamic content. Images and fonts can be referenced as variables within HTML templates. Documents (like PDFs) are static and used for rendering documents without dynamic components.

notes

string

Optional notes or comments about this specific Asset Version. Useful for tracking changes or providing context.

Maximum length: 255

Example:

"Initial version."

content

object

Defines the content of an Asset Version, supporting multiple content sources. The source property determines how the content is provided and managed.

inline: Content is stored directly in Posta. It can be provided upon creation or added/edited later, used primarily for HTML templates. Maximum 102,400 bytes.
import: A convenience feature for initial content creation. Accepts a publicly available URL, downloads the content, and stores it in Posta. After import, it doesn't retain its external reference.
externalUrl: Content remains externally hosted and is fetched every time it's needed. Posta does not store this content but maintains a reference to the external URL.

Choose the appropriate type based on your content management needs, update frequency, and integration requirements. inline and import are recommended over externalUrl for security, compliance, and performance reasons.

Example:

{
  "source": "inline",
  "type": "text/html",
  "content": "<html><body>Hello {{firstName}}</body></html>"
}

variableDefinitions

object[]

List of variables defined for this Asset Version. Used for content personalization in HTML templates. Note: When using Assets with Variables with our Letter API, always review the variableHandling option on the Letter. If validationScope is set to none in the request, the defined variables and their behavior will not be evaluated at all. See further information on the Letter object.

List of variables defined for this Asset Version. Used for content personalization in HTML templates. A maximum of 128 variable definitions can be specified per Asset Version. This limit helps maintain performance and readability of templates.

variableDefinitions.name

string

required

Name of the Variable. Used as the key for content personalization. Must be unique within the Asset Version. Example: firstName

Required string length: 1 - 64

Example:

"firstName"

variableDefinitions.type

enum<string>

default:value

Specifies the type of the Variable:

value: A string value (default Variable type when not specified)
asset: References another Asset by its Id
externalUrl: References content at an external URL (must be publicly available)

Note: We recommend using asset type Variables instead of externalUrl for better consistency, security, compliance, and availability. External URLs might change without version control, may be subject to throttling, or could become unavailable.

Available options:

value,

asset,

externalUrl

Example:

"value"

variableDefinitions.behavior

enum<string>

default:optional

Specifies how the Variable should be handled during rendering.

optional: The Variable is optional and may or may not be provided in a request (such as create letter). If allowEmpty is true you can pass an empty string as its value.
required: The Variable must be provided in a request (such as create letter). If allowEmpty is true you can pass an empty string as its value.
preset: The preset value will be used and the variable should not be included in the request (such as create letter). The presetValue must be defined when this behavior is used. allowEmpty is not applicable to this behavior.
overridablePreset: The preset value will be used, unless a value is explicitly passed in a request to override the preset value. The presetValue must be set when this behavior is used, and the variable can be included in a request if an override is necessary, otherwise the presetValue will be used. If allowEmpty is true you can pass an empty string as its value.

Note: When using Assets with Variables with our Letter API, always review the variableHandling option on the Letter. If validationScope is set to none in the request, the defined variables and their behavior will not be evaluated at all. See further information on the Letter object.

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Available options:

optional,

required,

preset,

overridablePreset

Example:

"optional"

variableDefinitions.allowEmpty

boolean

Determines whether an empty value is acceptable for this Variable.

Example empty string: { "name": "firstName", "value": "" }

Note: null is considered as no value, not an empty one.

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Example:

true

variableDefinitions.presetValue

string

Specifies a preset value for the Variable. This value may be used when:

the Variable is not provided
a value is provided but the behavior is set to presetValue

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Example: "ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

Maximum length: 512

Example:

"ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

variableDefinitions.exampleValue

string

Provides a sample value for the Variable, useful for documentation and UI purposes. This value is not used in the actual rendering process. It's primarily for demonstrating expected input in user interfaces or documentation.

Example: "Jane"

Maximum length: 512

Example:

"Jane"

publish

boolean

If set to true, this Asset Version will be published immediately after creation. Default is false.

Example:

false

Response

201

application/json

The request has succeeded and a new resource has been created as a result

Represents a specific version of an Asset, containing the actual content and metadata. Asset Versions are the core entities for version control, compliance tracking, and content management in Posta.

Key aspects:

Content: Can be HTML templates (with variable support), images, fonts, or documents (e.g., PDFs).
Status: Determines the overall status of the parent Asset (draft, published, archived, or deleted).
Version Control: Allows tracking changes and maintaining multiple iterations of an Asset.
Compliance: Facilitates auditing and regulatory compliance through versioning.

string

required

Unique identifier for the Asset Version. Format: 'astv_' followed by alphanumeric characters.

Required string length: 1 - 99999

Example:

"astv_2jyk1xYhW4n0vVfHirU5eJeXsbw"

status

enum<string>

required

Represents the status of an Asset Version.

draft: An Asset Version that is being worked on and can be modified. This is the initial state for new Asset Version and cloned Asset Versions.
published: An Asset Version that is finalized and available for use. Published Asset Versions cannot be edited.
archived: An Asset Version unavailable for new uses but may still be accessible for historical purposes. It can be republished if needed.
deleted: An Asset Version that has been deleted from the system. This is a terminal state.

State transitions:

Draft Asset Versions can be published, archived, or deleted.
Published Asset Versions can only be archived or deleted.
Archived Asset Versions can be republished (becoming published) or deleted.
Deleted is a terminal state with no further transitions.

Notes:

Only one Asset Version can be in the published state at a time for a given Asset.
Publishing a new Asset Versions will automatically archive the previously published one, if there was one.
Cloning any non-deleted Asset Versions will create a new one in draft state.
Deletion is permanent and should be used with caution.

Available options:

draft,

published,

archived,

deleted

Example:

"draft"

contentType

string

required

MIME type of the Asset Version content. Indicates the format of the content (e.g., 'text/html', 'image/jpeg', 'application/pdf').

Required string length: 1 - 99999

Example:

"text/html"

contentLength

integer

required

Length of the Asset Version content in bytes. Useful for content management and transfer considerations.

Required range: -1 <= x <= 999999999

Example:

100

contentUrl

string

required

URL where the rendered content of this asset version can be accessed. Available after publishing.

Required string length: 1 - 99999

Example:

"https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content"

createdAt

string

required

The timestamp the resource was created at (UTC).

modifiedAt

string

required

The timestamp the resource was last modified at (UTC).

notes

string

Optional notes or comments about this specific Asset Version. Useful for tracking changes or providing context.

Maximum length: 255

Example:

"Initial version."

variableDefinitions

object[]

variableDefinitions.name

string

required

Name of the Variable. Used as the key for content personalization. Must be unique within the Asset Version. Example: firstName

Required string length: 1 - 64

Example:

"firstName"

variableDefinitions.type

enum<string>

default:value

Specifies the type of the Variable:

value: A string value (default Variable type when not specified)
asset: References another Asset by its Id
externalUrl: References content at an external URL (must be publicly available)

Available options:

value,

asset,

externalUrl

Example:

"value"

variableDefinitions.behavior

enum<string>

default:optional

Specifies how the Variable should be handled during rendering.

optional: The Variable is optional and may or may not be provided in a request (such as create letter). If allowEmpty is true you can pass an empty string as its value.
required: The Variable must be provided in a request (such as create letter). If allowEmpty is true you can pass an empty string as its value.
preset: The preset value will be used and the variable should not be included in the request (such as create letter). The presetValue must be defined when this behavior is used. allowEmpty is not applicable to this behavior.
overridablePreset: The preset value will be used, unless a value is explicitly passed in a request to override the preset value. The presetValue must be set when this behavior is used, and the variable can be included in a request if an override is necessary, otherwise the presetValue will be used. If allowEmpty is true you can pass an empty string as its value.

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Available options:

optional,

required,

preset,

overridablePreset

Example:

"optional"

variableDefinitions.allowEmpty

boolean

Determines whether an empty value is acceptable for this Variable.

Example empty string: { "name": "firstName", "value": "" }

Note: null is considered as no value, not an empty one.

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Example:

true

variableDefinitions.presetValue

string

Specifies a preset value for the Variable. This value may be used when:

the Variable is not provided
a value is provided but the behavior is set to presetValue

For detailed examples and edge cases on how behavior, allowEmpty, and presetValue interact, see the Assets Overview in our API reference.

Example: "ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

Maximum length: 512

Example:

"ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

variableDefinitions.exampleValue

string

Example: "Jane"

Maximum length: 512

Example:

"Jane"

List asset versions Get asset version

curl --request POST \
  --url https://api.posta.co/assets/{id}/versions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "id": "astv_2jyk1xYhW4n0vVfHirU5eJeXsbw",
  "status": "draft",
  "notes": "Minor changes to the footer.",
  "content": {
    "source": "inline",
    "type": "text/html",
    "content": "<html><body>Hello {{firstName}}</body></html>"
  },
  "variableDefinitions": [
    {
      "name": "name",
      "behavior": "required",
      "allowEmpty": false
    }
  ],
  "contentType": "text/html",
  "contentLength": 100,
  "contentUrl": "https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content",
  "publish": false,
  "createdAt": "2023-06-07T12:34:56Z",
  "modifiedAt": "2023-06-07T12:34:56Z"
}'

{
  "id": "astv_2jyk1xYhW4n0vVfHirU5eJeXsbw",
  "status": "draft",
  "notes": "Minor changes to the footer.",
  "content": {
    "source": "inline",
    "type": "text/html",
    "content": "<html><body>Hello {{firstName}}</body></html>"
  },
  "variableDefinitions": [
    {
      "name": "name",
      "behavior": "required",
      "allowEmpty": false
    }
  ],
  "contentType": "text/html",
  "contentLength": 100,
  "contentUrl": "https://api.posta.co/assets/astv_2jyk1xYhW4n0vVfHirU5eJeXsbw/content",
  "publish": false,
  "createdAt": "2023-06-07T12:34:56Z",
  "modifiedAt": "2023-06-07T12:34:56Z"
}

Getting started

Assets

Postal

Authorizations

Headers

Path Parameters

Body

Response