Versioning and compatibility

The /v1 contract

All public MailerDash API endpoints live under the /v1/ prefix. This prefix represents the stable public contract: once an endpoint is documented under /v1/, we commit to not introducing breaking changes without a deprecation cycle.

Examples of changes that are not considered breaking (they are backward-compatible):

• Adding new optional fields to existing responses.
• Adding new endpoints.
• Adding new possible values to enums in non-critical fields.
• Changing human-readable error messages (the message field).

Examples of changes that are breaking and would require /v2/:

• Removing or renaming existing response fields.
• Changing the type of a field (e.g. from string to array).
• Changing the semantics of an existing parameter.
• Modifying error codes (type, code) in an incompatible way.

---

When /v2 appears

A new /v2/ prefix is introduced only when breaking changes are necessary. There are no current plans to migrate to /v2/. When it happens, it will be announced in advance and both versions will coexist during the grace period.

---

Deprecation policy

When an endpoint needs to change its path or behavior in a non-backward-compatible way, we follow this process:

1. The new endpoint or behavior is published (with its new path or semantics).
2. The previous endpoint is kept as a legacy alias — it continues working exactly as before.
3. The alias is marked deprecated: true in the OpenAPI spec (openapi.yaml).
4. Clients are notified of the grace period before the alias is removed.

Note

While an endpoint is marked deprecated: true in the spec, it will continue to work. Only after the grace period expires and the removal is announced will that path stop returning responses.

---

Software version

You can check the exact version of the software currently running in production at any time:

GET https://api.mailerdash.com/version

Response:

{
  "version": "0.11.22"
}

This endpoint is outside the /v1/ prefix and does not require authentication. The version follows SemVer: MAJOR.MINOR.PATCH.

There is also a health check endpoint:

GET https://api.mailerdash.com/health

Returns 200 OK when the server is active and operating normally.

---

OpenAPI spec versioning

The openapi.yaml file is versioned alongside the software. You can access the interactive API reference at:

• /reference/transactional/ — transactional send endpoints
• /reference/bulk/ — campaign, contact, list, and sequence endpoints
• /reference/platform/ — keys, domains, webhooks, usage, suppressions

---

Summary

Concept	Policy
Stable prefix	/v1/ — does not change without a deprecation cycle
Breaking changes	Only under a new /v2/ prefix
Deprecation	Legacy alias + deprecated: true + grace period
Software version	GET /version (no auth)
Health check	GET /health (no auth)