Lumail
Sign up

Versioning and Deprecation Policy

How Lumail versions its REST API, what can change inside a version, and how deprecation and sunset are announced.

Lumail versions the REST API with a major version in the URL path: /api/v1 and /api/v2. The same lum_ Bearer token works on both.

Current versions

VersionStatusUse it for
/api/v2ActiveEvery new integration. See API v2.
/api/v1FrozenExisting integrations only. No new features, no scheduled sunset date yet.

To move an existing integration, follow Migration to V2.

What can change inside a version

Inside a major version, Lumail only ships additive changes:

  • new endpoints
  • new optional request fields
  • new response fields
  • new error codes documented in the OpenAPI specification

Clients should ignore unknown response fields. Removing or renaming a field, changing a type, or making an optional field required only happens in a new major version.

How deprecation and sunset are announced

Before a version or an endpoint is retired, Lumail:

  1. Announces the deprecation and the retirement date in the changelog and on this page.
  2. Returns a Deprecation header (RFC 9745) on every response from the deprecated surface, with a Link to this policy (rel="deprecation").
  3. Adds a Sunset header (RFC 8594) with the retirement date once it is scheduled.

Monitor these headers in your client to detect deprecations automatically. /api/v1 does not return them today because it has no retirement date.

PreviousRate LimitsNextSMTP Endpoint