Metadata allows you to attach custom key-value pairs to Posta API objects, enabling better organization, filtering, and integration with your internal systems.

​
Using metadata

When creating or updating Posta objects, you can include key-value pairs of custom metadata. This feature is particularly useful for:

  • Categorizing objects
  • Tracking internal identifiers
  • Adding custom flags
  • Linking to external systems

​
Metadata structure

Metadata in the Posta API is structured as an array of key-value pairs:

"metadata": [
  {
    "key": "<string>",
    "value": "<string>"
  },
  {
    "key": "<string>",
    "value": "<string>"
  }
]

​
Metadata examples

Here are some examples of how you might use metadata:

"metadata": [
  {
    "key": "campaign",
    "value": "winter2024"
  },
  {
    "key": "salesforceId",
    "value": "0063i00000JrMehAAF"
  },
  {
    "key": "costCenter",
    "value": "servicing"
  },
  {
    "key": "highPriority",
    "value": ""
  },
  {
    "key": "compliance",
    "value": "PHI"
  }
]

You can specify a key without a value, as shown in the “highPriority” example above. This can be useful for boolean-like flags where the presence of the key indicates true.

​
Metadata limitations

  • You can attach up to 20 metadata key-value pairs to an object.
  • Each metadata key must be less than 64 characters long.
  • Metadata values must be less than 512 characters.
  • Metadata does not support nested objects.
  • Empty string values are allowed and can be useful for flag-like metadata.

​
Best practices

  1. Use consistent key names across your integration for easier querying and organization.
  2. Consider prefixing keys to avoid conflicts (e.g., internalId instead of id).
  3. Use metadata for filtering and organization, not for storing sensitive data.
  4. Leverage empty values for boolean-like flags.
  5. Document your metadata schema within your organization to ensure consistent usage.
  6. Keep metadata concise and relevant to maintain performance.

Metadata is searchable and can be used to organize and filter your Posta objects efficiently. However, it’s not intended for storing sensitive information.

​
Working with metadata

While the specific endpoints for working with metadata may vary depending on the object type, here are general principles for interacting with metadata:

​
Adding metadata

When creating or updating an object, include the metadata array in your request body:

​
Retrieving metadata

When you fetch an object, its metadata will be included in the response.

​
Updating metadata

You can update metadata on existing objects using the update endpoints. This will replace the entire metadata array.

​
Filtering with metadata

Many list endpoints support filtering objects based on metadata. See each endpoint’s documentation for details.

Remember to refer to the specific API endpoint documentation for detailed information on how to interact with metadata for each object type.

Avoid using metadata for data that changes frequently, as this can impact performance. For frequently changing data, consider using a dedicated field or a separate system.

Rate limitingErrors