Skip to main content

Versioning

The API is served at https://api.epostix.com/v1. There is one version and we intend there never to be a second.

That is a design commitment rather than an aspiration. A new major version splits the community, doubles the documentation and strands every integration that stops being maintained. We would rather constrain what we are allowed to change.

What we may add​

These can appear at any time, without notice, and your integration must tolerate them:

  • New endpoints.
  • New optional fields on a request.
  • New fields on a response.
  • New values in an existing enum, including new status values, new event types, and new error type values.
  • New response headers.

What we will not do​

  • Remove or rename a field.
  • Change a field's type.
  • Make an optional request field required.
  • Tighten an existing validation rule so that a request which used to succeed now fails.
  • Repurpose an existing enum value to mean something else.
  • Remove an endpoint.

What this asks of your client​

Two habits, and they matter more than they sound.

Ignore fields you do not recognise. Do not fail on an unexpected key in a response. If you deserialise into a strict type, configure it to skip unknown fields.

Treat an unknown enum value as a default, not a crash. This is the one that bites. A generated client with an exhaustive switch over error types compiles today and breaks the first time we add one, even though nothing about the wire format changed. Always have a fallback branch.

switch (error.type) {
  case "rate_limit_exceeded": return backOff(error);
  case "validation_error":    return report(error.details);
  default:                    return treatAsGenericFailure(error);
}

The same applies to a message status you have not seen before, and to a webhook event type you have not subscribed to handling.

Deprecation​

If a field ever stops being useful we will keep returning it and document that it is no longer maintained. We will not remove it. Nothing in the API is scheduled for removal.

The spec​

The OpenAPI description is published at https://docs.epostix.com/openapi/v1.yaml and is the same document our own server is built from. Generate a client from it, import it into an HTTP client, or diff it between releases to see exactly what changed.