REST API — everything the UI does.

Authentication

Two paths in parallel:

• Cookie session — when the UI itself talks to the API (browser-based, CSRF-protected)
• X-API-Key header — for external integrations (CI/CD, SIEM, monitoring, custom apps)

API keys have the format nmg_ + 64 hex characters. The full key is returned exactly once on creation — afterwards the database stores only the hash plus the first 20 characters for UI display. Lost-key recovery: not possible, create a new key and revoke the old one.

Per-key scopes

Configurable per key:

• read-only — all GET endpoints, no write operations (for monitoring/SIEM integration)
• quarantine-only — only quarantine actions (release, discard, retrain)
• domain-admin — all operations for one specific domain (for tenant self-service)
• full-admin — all operations, no scope limit (for operator CLI tools)

Rate limit

Configurable per key (default 100 requests/minute). Token-bucket scheme — bursts up to 10× the sustained rate are allowed, after that 429 Too Many Requests with a Retry-After header. This protects against:

• Accidental infinite loops in the integrating system
• Compromised API keys that suddenly hammer the cluster
• Performance regression on cluster nodes from an over-active integration

OpenAPI spec

Versioned contract in openapi.yaml, shipped with every release. Available at /api/v1/openapi.yaml. Versioned with each release tag — breaking changes only across major-version transitions, deprecation notices 6 months ahead.

Importable into Postman, Insomnia, OpenAPI generator (for client libraries in Go, Python, JavaScript, Java etc.).

Webhooks

For real-time integration. The operator configures a URL + secret HMAC token + event types. On every event MailGuard POSTs a JSON payload with a signed header (HMAC-SHA256). Available events:

• quarantine.added — mail moved to quarantine
• quarantine.released — mail released (operator or end user)
• quarantine.discarded — mail discarded
• reputation.threshold_crossed — sender IP reputation crossed a threshold
• license.changed — tier change or licence refresh
• cluster.node_joined / cluster.node_left — cluster events
• dkim.rotation_due — DKIM key rotation due (30-day pre-warning)
• cert.expiring — TLS certificate expiring soon

Audit log via API

Endpoint GET /api/v1/audit/logs with filter parameters (time range, actor, resource). JSON format. Cursor pagination — no limit on output size, no data loss on export. Ideal for SIEM integration — typically the SIEM forwarder polls every 5 minutes and persists events locally.

Response envelope

Uniform across all endpoints — no mix-pattern like at many cloud APIs:

{
  "data":    { ... } | [...] | null,
  "error":   null | "string",
  "message": "human-readable status"
}

API-first is not an upsell — it's architecture.

REST API and webhooks are included in the standard plan and 30-day trial — fully equipped for SIEM integration and CI integration.

See pricing