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.

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

Example:

"draft"

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

Example:

"template"

name

string

required

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

Required string length: 1 - 255

Example:

"Right to Cure"

description

string

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

Maximum string length: 255

Example:

"A legal document that a mortgage lender sends to a borrower who has fallen behind on their payments."

statusVersion

object

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

Show child attributes

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

Example:

"draft"

statusVersion.notes

string

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

Maximum string length: 255

Example:

"Initial version."

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.

Maximum array length: 128

Show child attributes

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

Example:

"firstName"

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

Example:

"value"

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

Example:

"optional"

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.

Example:

true

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 string length: 512

Example:

"ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

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 string length: 512

Example:

"Jane"

Example:

{
  "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"
}

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

Show child attributes

metadata.key

string

required

Must be no more than 64 characters.

Example:

"salesforceId"

metadata.value

string | null

Must be no more than 512 characters.

Example:

"0013i00002YyVvSAAV"

Getting started

Assets

Postal