Versionado y compatibilidad

El contrato /v1

Todos los endpoints públicos de la API de MailerDash viven bajo el prefijo /v1/. Este prefijo representa el contrato público estable: una vez que un endpoint está documentado bajo /v1/, nos comprometemos a no introducir cambios que rompan la compatibilidad sin un ciclo de deprecación.

Ejemplos de cambios que no se consideran breaking (son retrocompatibles):

• Agregar nuevos campos opcionales a respuestas existentes.
• Agregar nuevos endpoints.
• Agregar nuevos valores posibles a enums en campos no críticos.
• Cambiar mensajes de error legibles por humanos (campo message).

Ejemplos de cambios que sí son breaking y requerirían /v2/:

• Eliminar o renombrar campos de respuesta existentes.
• Cambiar el tipo de un campo (p.ej. de string a array).
• Cambiar la semántica de un parámetro existente.
• Modificar los códigos de error (type, code) de forma incompatible.

---

Cuándo aparece /v2

Un nuevo prefijo /v2/ solo se introduce cuando sea necesario realizar cambios de ruptura de compatibilidad. No hay planes actuales de migrar a /v2/. Cuando ocurra, se anunciará con anticipación y ambas versiones coexistirán durante la ventana de gracia.

---

Política de deprecación

Cuando un endpoint necesita cambiar de path o comportamiento de forma no retrocompatible, seguimos este proceso:

1. El nuevo endpoint o comportamiento se publica (con su nuevo path o semántica).
2. El endpoint anterior se mantiene como alias legacy — sigue funcionando exactamente igual que antes.
3. El alias queda marcado como deprecated: true en el spec OpenAPI (openapi.yaml).
4. Los clientes son notificados de la ventana de gracia antes de que el alias sea removido.

Nota

Mientras un endpoint esté marcado como deprecated: true en el spec, seguirá funcionando. Solo después de que el período de gracia expire y se anuncie la remoción dejarás de recibir respuestas de ese path.

---

Versión del software

Puedes consultar la versión exacta del software que está corriendo en producción en cualquier momento:

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

Respuesta:

{
  "version": "0.11.22"
}

Este endpoint está fuera del prefijo /v1/ y no requiere autenticación. La versión sigue SemVer: MAJOR.MINOR.PATCH.

También hay un endpoint de health check:

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

Retorna 200 OK cuando el servidor está activo y en condiciones normales de operación.

---

Versionado del spec OpenAPI

El archivo openapi.yaml está versionado junto con el software. Puedes acceder a la referencia interactiva de la API en:

• /reference/transactional/ — endpoints de envío transaccional
• /reference/bulk/ — endpoints de campañas, contactos, listas y sequences
• /reference/platform/ — keys, dominios, webhooks, usage, suppressions

---

Resumen

Concepto	Política
Prefijo estable	/v1/ — no cambia sin ciclo de deprecación
Breaking changes	Solo bajo nuevo prefijo /v2/
Deprecación	Alias legacy + deprecated: true + ventana de gracia
Versión del software	GET /version (sin auth)
Health check	GET /health (sin auth)