> ## Documentation Index
> Fetch the complete documentation index at: https://docs.posta.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Understanding the core of Posta's content management system

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:

<Accordion title="Templates" icon="file-code">
  HTML template with support for variables for dynamic content generation.

  * Supports HTML5 with inline CSS and JavaScript
  * Use variables for content personalization
  * Render into print-ready formats
  * Allow complex layouts and styling
</Accordion>

<Accordion title="Images" icon="image">
  Image file for use in mail pieces.

  * Supported formats include PNG, JPEG, GIF, and SVG
  * Used for logos, graphics, or standalone image content
  * Can be referenced securely within templates
  * Stored privately, no public URLs needed
</Accordion>

<Accordion title="Fonts" icon="font-case">
  Font file for custom typography in mail pieces.

  * Supported formats include TTF, OTF, and WOFF2
  * Ensures consistent branding across communications
  * Can be referenced in templates
  * Securely stored and managed
</Accordion>

<Accordion title="Documents" icon="file-pdf">
  Static document, typically in PDF format.

  * Used for content that doesn't require personalization
  * Can be sent directly without variable content
  * Useful for standardized forms or disclosures
</Accordion>

<Note>
  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.
</Note>

### 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

<Card title="Asset object" icon="books" href="/api-reference/assets/assets/asset-schema" iconType="duotone" horizontal>
  For more details on Asset properties, refer to the Asset object schema
</Card>

<Card title="Asset Version object" icon="layer-group" href="/api-reference/assets/asset-versions/asset-version-schema" iconType="duotone" horizontal>
  For more details on Asset properties, refer to the Asset object schema
</Card>

### Lifecycle: Asset Version

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

<Accordion title="Asset Version status transitions" icon="arrow-progress">
  * `draft` → Published, Archived, or Deleted
  * `published` → Archived or Deleted
  * `archived` → Published or Deleted
</Accordion>

```mermaid theme={null}
stateDiagram-v2
    [*] --> Draft
    Draft --> Published
    Draft --> Archived
    Draft --> Deleted
    Published --> Archived
    Archived --> Published
    Published --> Deleted
    Archived --> Deleted
    Deleted --> [*]
```

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

<Accordion title="Asset status transitions" icon="arrow-progress">
  - `draft` → Published, Archived, or Deleted
  - `published` → Draft (if the published Asset Version is archived and a draft exists), Archived, or Deleted
  - `archived` → Draft (by creating a new draft Asset Version), Published (by publishing an Asset Version), or Deleted
</Accordion>

<Note>
  `published` and `archived` Assets can re-enter Draft status on the Asset but not on Asset version.
</Note>

## 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:

<ParamField query="variableDefinitions" type="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.

  <ParamField query="name" type="string" required>
    Name of the variable. Used as the key for content personalization.
    Must be unique within the Asset Version.
    Example: `firstName`
  </ParamField>

  <ParamField query="type" 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.
  </ParamField>

  <ParamField query="behavior" type="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.
  </ParamField>

  <ParamField query="allowEmpty" type="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.
  </ParamField>

  <ParamField query="presetValue" type="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"`
  </ParamField>

  <ParamField query="exampleValue" type="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"`
  </ParamField>
</ParamField>

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

## 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:

* Learn how to [create and manage Assets](/api-reference/assets/assets/create-asset)
* Explore [working with Asset Versions](/api-reference/assets/asset-versions/create-asset-version)

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](/api-reference/assets/assets) for detailed information on available endpoints and operations.