Asset object

Represents a digital asset in Posta, primarily used for rendering documents.

Assets are version-controlled containers, where the actual content is stored in Asset Versions. This structure allows for efficient management, compliance tracking, and monitoring of changes over time.

Assets support HTML templates with variables for document personalization, as well as static content like images, fonts, and documents.

string

required

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

Required string length: 1 - 99999

status

enum<string>

required

Represents the overall status of an Asset, derived from the status(es) of its associated Asset Version(s).

draft: Indicates an Asset that is not yet published. This status applies when:
1. The Asset has no associated Asset Versions, or
2. At least one Asset Version is in draft status and no version is published.
published: Indicates that the Asset has a published Asset Version. The Asset is available for use.
archived: Indicates that all associated Asset Versions are archived. This status makes the Asset unavailable for new uses but may still be accessible for historical purposes.
deleted: Indicates that all associated Asset Versions have been deleted. This is a terminal status for the Asset.

Note:

Deleted Asset Versions are not considered when determining the Asset's status, except for the deleted status.
An Asset can transition from archived back to draft if a new Asset Version is created, or to published if a new or existing Asset Version is published.

Available options:

draft,

published,

archived,

deleted

type

enum<string>

required

Specifies the type of Asset, determining its content format and how it's processed in Posta. Each type has specific use cases and handling mechanisms.

Available options:

template,

image,

font,

document

name

string

required

Name of the Asset, used for display and organizational purposes.

Required string length: 1 - 255

versionCount

integer

required

Number of versions associated with the asset. Deleted asset versions are not counted.

Required range: 0 < x < 99999

createdAt

string

required

The timestamp the resource was created at (UTC).

modifiedAt

string

required

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

description

string

Optional description of the Asset. Provides additional context or details about its purpose or content.

Maximum length: 255

latestVersionId

string

The unique identifier of the latest version of the asset. Format: 'astv_' followed by alphanumeric characters.

Maximum length: 99999

statusVersionId

string

The unique identifier of the status version of the asset. Format: 'astv_' followed by alphanumeric characters.

Maximum length: 99999

statusVersion

object

The asset version that defines the status of the asset. Hierarchical order: published > draft > archived > deleted. Deleted versions are not considered.

statusVersion.id

string

required

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

Required string length: 1 - 99999

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

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

statusVersion.contentLength

integer

required

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

Required range: -1 < x < 999999999

statusVersion.contentUrl

string

required

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

Required string length: 1 - 99999

statusVersion.createdAt

string

required

The timestamp the resource was created at (UTC).

statusVersion.modifiedAt

string

required

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

statusVersion.notes

string

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

Maximum length: 255

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

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

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

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

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

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

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

metadata

object[] | null

A key-value store for custom metadata.

Limitations:

Up to 20 metadata key-value pairs
Key must be no more than 64 characters
Value must be no more than 512 characters

Getting started

Assets

Postal