Domain-Endpoints¶

REST-API für Domain-Verwaltung. Änderungen replizieren automatisch per mTLS-Fan-Out auf alle Cluster-Nodes.

`GET /domains`¶

Liste aller geschützten Domains.

curl -H 'X-API-Key: nmg_<...>' \
     https://mailguard.example.com:3443/api/v1/domains

Response:

{
  "data": [
    {
      "id": 7,
      "name": "example.com",
      "direction": "inbound",
      "active": true,
      "backend_servers": ["mail.example.com:25"],
      "quarantine_threshold": 12.0,
      "reject_threshold": 18.0,
      "dkim_active": true,
      "dmarc_reporting": true,
      "tenant_id": null,
      "created_at": "2026-04-12T09:15:00Z",
      "updated_at": "2026-04-30T14:42:00Z"
    }
  ],
  "error": null,
  "message": "OK"
}

`POST /domains`¶

Domain anlegen.

curl -X POST -H 'X-API-Key: nmg_<...>' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "kunde.de",
       "direction": "inbound",
       "backend_servers": ["mailbackend.kunde.de:25"],
       "quarantine_threshold": 10.0,
       "reject_threshold": 18.0,
       "dkim_active": true
     }' \
     https://mailguard.example.com:3443/api/v1/domains

Response 201:

{
  "data": {
    "id": 8,
    "name": "kunde.de",
    ...
  },
  "error": null,
  "message": "Created"
}

`GET /domains/{id}`¶

Detail einer einzelnen Domain.

curl -H 'X-API-Key: nmg_<...>' \
     https://mailguard.example.com:3443/api/v1/domains/8

`PUT /domains/{id}`¶

Domain aktualisieren. Komplettes Domain-Objekt im Body — partielle Updates werden über JSON-Merge-Patch (siehe RFC 7396) unterstützt aber nicht erforderlich.

curl -X PUT -H 'X-API-Key: nmg_<...>' \
     -H 'Content-Type: application/json' \
     -d '{ "quarantine_threshold": 8.0 }' \
     https://mailguard.example.com:3443/api/v1/domains/8

`DELETE /domains/{id}`¶

Domain entfernen. Hard-Delete — alle zugehörigen Konfigurations-Daten (DKIM-Keys, Mail-Filter mit Domain-Scope) werden mit gelöscht. Quarantäne-Mails der Domain bleiben in der Hold-Queue bis zur normalen Retention.

curl -X DELETE -H 'X-API-Key: nmg_<...>' \
     https://mailguard.example.com:3443/api/v1/domains/8

Multi-Domain-Verhalten¶

MailGuard ist Single-Tenant — alle API-Keys mit full-admin-Scope sehen alle Domains des Clusters. API-Keys mit domain-admin-Scope können pro Key auf eine spezifische Domain eingeschränkt werden, der Backend-Filter setzt das durch. Es gibt keine technische Tenant-Isolation auf DB-Ebene als Architektur-Feature.

Domain-Endpoints¶

GET /domains¶

POST /domains¶

GET /domains/{id}¶

PUT /domains/{id}¶

DELETE /domains/{id}¶