Posta uses a date-based versioning system to ensure stability and backwards compatibility. This guide explains how our versioning works and how to specify the API version in your requests.

​
Version selection process

The following flowchart demonstrates how the API version is selected for each request:

This diagram illustrates that:

  • If no version is specified, we use the latest stable version.
  • Specified versions are checked for support and deprecation status.
  • Unsupported versions result in an error.
  • Deprecated versions are used with a warning.

​
Current version

The current version of the Posta API is 2024-07-30.

​
Specifying the API version

To use a specific version of the API, include the X-Api-Version header in your requests:

X-Api-Version: 2024-07-30

We strongly recommend always specifying the version to ensure consistent behavior. If you don’t specify one, your request will use the latest stable version of the API.

​
Version format

Our versions are formatted as YYYY-MM-DD. This date represents the day the version was released.

​
Backwards compatibility

Future versions are always backwards compatible with older ones. However, we may deprecate certain features or endpoints over time. We will provide ample notice before removing any deprecated functionality.

​
Version lifecycle

  1. Active: The current version and recent previous versions.
  2. Deprecated: Older versions that are still supported but may be removed in the future.
  3. Sunset: Versions that are no longer supported and will return an error.

We recommend using the latest API version to access all features and improvements. Check our API changelog regularly for updates.

​
Deprecation warnings

When using a deprecated version of the API, a deprecation warning will be included in the response headers, following the best practices outlined in RFC 7231, Section 6.6.2. This approach ensures that clients are properly informed about deprecated API versions and the timeline for their deprecation.

Deprecation: API version 2024-06-15 is deprecated and will be sunset on 2025-06-14. Please upgrade to the latest version.

​
Testing new versions

Before upgrading to a new API version in production:

  1. Use the new version with your test API keys.
  2. Review our changelog for any breaking changes.
  3. Update your integration as necessary.

​
Version support policy

We aim to support each version for at least 12 months after a new version is released. When a version is approaching the end of its support period, we will notify affected customers.

Using a sunset version will result in a 400 Bad Request status code. Ensure you’re always using a supported version of the API.

AuthenticationPagination