Skip to main content

Versioning policy

This page documents how the BlueSender API contract evolves and what guarantees integrators can rely on.

Three things that version separately​

The metadata footer embedded in message carries an explicit schema version (v1). Within a major version:

  • Additive changes are permitted. New optional fields may appear. CRMs should ignore unknown fields rather than reject the payload.
  • Existing fields are not removed or renamed. chat_id, is_group, recipients, sender, etc. will keep their names and semantics for the lifetime of :v1.
  • Field types do not change. A field that's a string today won't become an object tomorrow within the same major version.

A breaking change to the schema would ship as bluesendr-metadata:v2. The transition would be staged: BlueSender would emit both :v1 and :v2 blocks side-by-side for a deprecation window, integrators would migrate at their own pace, and then :v1 would be dropped.

2. HTTP request and response shapes​

The POST /crm/webhook request body, the inbound delivery body (POST /conversations/messages/inbound), and the status-update body (PUT /conversations/messages/{messageId}/status) are versioned implicitly — there is no version suffix on the path.

  • New optional fields may appear without a contract version bump. CRMs should ignore fields they don't recognize rather than reject the payload.
  • Existing fields are not removed or renamed without notice. A field marked deprecated will run for a 90-day notice window before removal — see Deprecations.
  • Field shapes are stable. A field that's a string today won't become an object tomorrow within the current contract.

3. Error codes​

Error codes (the structured error.code on the status-update channel) are an open, free-form set:

  • New codes may be added at any time. CRMs should tolerate unknown codes — see Error code conventions.
  • Codes are stable once introduced. A documented code will not change meaning. A code may be deprecated and replaced (with notice), but the old form will not be reused for a different meaning.

Backwards compatibility — the integrator's contract​

When you build a BlueSender integration today, the following guarantees hold within bluesendr-metadata:v1:

  • Payloads you parse today will continue to parse tomorrow. New optional fields may appear; nothing existing will move or vanish.
  • Error codes you handle today will continue to fire under the same conditions. New codes may appear.

The corollary: never reject an HTTP payload for having an unknown field or an unknown enum value. Permissive parsing is the contract.

What's NOT covered by versioning​

  • Internal Mac-side behavior (e.g. how the Mac retries delayed iCloud downloads, how it queues outbound work). These are implementation details that may change without notice.
  • Default values for optional fields when omitted by the sender. Operators may tune these (e.g. rate-limit thresholds) per deployment.
  • Operator-tunable thresholds (rate limits, queue caps, timeouts). These are documented in pages like Rate limiting but their values are not contractual.