OpenAPI-Spec¶

MailGuard liefert eine vollständige OpenAPI-3.1-Spec für die externe Integrations-API.

Spec abrufen¶

curl https://mailguard.example.com:3443/api/v1/openapi.yaml

Kein Auth nötig — die Spec ist öffentlich.

Importieren¶

Die Spec ist kompatibel mit:

Postman — Import → File → openapi.yaml. Erzeugt automatisch eine Collection mit allen Endpoints.
Insomnia — File → Import → openapi.yaml.
OpenAPI-Generator — generiert Client-Bibliotheken für Go, Python, JavaScript, Java, Rust, Ruby etc.
Swagger-UI / Redoc — Standalone-Viewer für die Spec.

Beispiel: Python-Client generieren

openapi-generator-cli generate \
  -i https://mailguard.example.com:3443/api/v1/openapi.yaml \
  -g python \
  -o ./mailguard-client-py

Versionierung¶

Die Spec ist semver-versioniert (siehe info.version im Spec-Header). Breaking-Changes nur in Major-Version-Übergängen, Deprecation-Notices 6 Monate vorher als deprecated: true auf den betroffenen Operationen.

Curated vs. Full¶

Die OpenAPI-Spec dokumentiert die stabilisierte externe Integrations-Surface — das sind die Endpoints, auf die externe Systeme verlässlich aufbauen können. Interne Admin-UI-Endpoints (replication, agent-only, cluster-internal mTLS) sind absichtlich nicht in der Spec, weil sie sich häufiger ändern.

Endpoints in der curated Spec¶

Tag	Endpoints
Auth	`GET /auth/me`
API keys	`GET/POST /auth/api-keys`, `DELETE /auth/api-keys/{id}`, `POST /auth/api-keys/{id}/revoke`
Mail domains	`GET/POST /domains`, `GET/PUT/DELETE /domains/{id}`
Quarantine	`GET /mail/quarantine`
Cluster	`GET /cluster/status`

Weitere Endpoints werden hier ergänzt sobald sie für externe Verwendung stabilisiert sind.