API tokens & REST API
The REST API lets PSA / helpdesk tools and scripts search messages, release them, manage lists and read statistics.
Tokens (Manage › API tokens)
- Name
- What the token is for (e.g. "MyHelpDesk integration"). Appears in the audit log as
api:<name>. - Limit to organization
- An organization token only sees and changes that organization; "All organizations" tokens can do everything the API offers.
After Create the token is shown once - copy it then; only a hash is stored. The list shows each token's prefix, scope and last use. Revoke disables a token immediately.
Calling the API
Send the token as a bearer header. All responses are JSON.
curl -H "Authorization: Bearer obs_xxxxxxxx" https://mx1.example.com/api/v1/stats?hours=24Endpoints
- GET /api/v1/health
- Version and whether ClamAV answers.
- GET /api/v1/stats?hours=24
{"hours": 24, "by_verdict": {"clean": 812, "spam": 40, ...}}(up to 90 days).- GET /api/v1/messages
- Parameters:
q(sender or subject text),verdict(comma list),hours(default 24),limit(default 100, max 1000). Returns id, times, direction, from, subject, score, verdict, action, reason, Message-ID, recipients with status, and the AI verdict. - GET /api/v1/messages/{id}
- One message including every scan stage's details.
- POST /api/v1/messages/{id}/release
- Release to all quarantined recipients, or JSON body
{"rcpts": ["user@contoso.com"]}. Returns{"ok": true, "info": "..."}. - POST /api/v1/messages/{id}/delete
- Delete from quarantine.
- POST /api/v1/lists
- JSON
{"scope": "org", "org_id": 3, "kind": "block", "pattern": "@bad.example", "note": "ticket 1234"}. Organization tokens use their own organization;globalneeds an all-organizations token.
Errors return a JSON {"error": "..."} with status 401 (bad or missing token), 403 (out of scope) or 404.
The machine-readable schema is at /api/openapi.json.