Posta’s content management system is built around Assets and Asset Versions. This structure enables efficient content management, version control, and seamless updates to your mail communications.

​
Asset and Asset Version

An Asset serves as a container for your mailing content, providing a stable reference point. Asset Versions contain the actual content, allowing you to iterate while maintaining a history of changes.

​
Types

Posta supports four types of Assets:

Images and fonts can be used in templates as variables by referencing their assetId. This ensures these assets are available for rendering while keeping them secure without public exposure.

​
Statuses

Both Assets and Asset Versions share the same set of statuses, but with different transition rules:

  1. draft - In development and modifiable.
  2. published - Finalized and available for use.
  3. archived - No longer active but retained for reference.
  4. deleted - Removed from the system.

​
Schemas

Asset object

For more details on Asset properties, refer to the Asset object schema

Asset Version object

For more details on Asset properties, refer to the Asset object schema

​
Lifecycle: Asset Version

Only one Asset Version can be published at a time. Publishing a new version automatically archives the previously published one.

​
Lifecycle: Asset

The status of an Asset is derived from its Asset Version(s) but follows its own transition rules:

  • published - Has a published Asset Version.
  • draft - Has no published Asset Version, but at least one draft.
  • archived - All Asset Versions are archived.
  • deleted - All Asset Versions are deleted.

published and archived Assets can re-enter Draft status on the Asset but not on Asset version.

​
Variables

Template Assets support variables for dynamic content personalization. Defining variables is optional and doing it can provide a lot more control to ensure consistent and predictable rendering.

Variables are defined in Asset Versions with the following properties:

​
variableDefinitions
array

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.

​
name
string
required

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

​
type
string

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.

​
behavior
string

Specifies how the variable should be handled during rendering:

  • optional: The variable is optional and may or may not be provided.
  • required: The variable must be provided.
  • preset: The preset value will be used. The presetValue must be set when this behavior is used. If a value is specified, the rendering of the document will fail.
  • overridablePreset: The preset value will be used, unless a different value is explicitly set to override the preset value. The presetValue must be set when this behavior is used.
​
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.

​
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 preset

Example: "ast_2k1UXnFem92yBFKxtTkQQYhVWyr"

​
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"

Use asset type variables for reusable content blocks or images, and be cautious with externalUrl variables as they depend on external resources.

​
Best Practices

  1. Create new Asset Versions for significant changes to maintain a clear content history.
  2. Use descriptive names and metadata for easy Asset management.
  3. Regularly audit and clean up unused Assets to keep your library manageable.
  4. Design variables with reusability in mind, using consistent naming conventions across templates.

By leveraging these concepts and best practices, you can create an efficient content management workflow using Posta’s Asset and Asset Version system.

​
Next steps

Now that you have an overview of our Asset system, you can:

By leveraging the power of Assets, Asset Versions, and variables, you can create highly dynamic and personalized content for your users. Remember to refer to our API reference for detailed information on available endpoints and operations.

ErrorsAsset object