Obsidian SuiteDocumentation
Obsidian Email Security: all chapters

Docs / Obsidian Email Security / Reference

REST API

The REST API lets your PSA or helpdesk tools and your own scripts read statistics, search messages, release or delete quarantined mail, manage allow and block lists, and send secure messages.

Tokens

API tokens are issued by Integrators Resource: contact us with what the token is for. A token is scoped to your organization: it only sees and changes your organization's mail and lists. We give you the token once; only a hash of it is stored, so keep it safe. Its name appears in your audit log as api:<name> for every change it makes. Ask us to revoke a token you no longer need, or one that may have leaked; that takes effect immediately.

Calling the API

The base URL is https://portal.obsidiansuite.net/api/v1. Send the token as a bearer header. All responses are JSON.

curl -H "Authorization: Bearer obs_xxxxxxxx" "https://portal.obsidiansuite.net/api/v1/stats?hours=24"

The machine-readable schema is at https://portal.obsidiansuite.net/api/openapi.json.

Errors return {"error": "..."} (also as "detail") with status 400 (bad request), 401 (missing or invalid token), 403 (outside the token's scope) or 404 (not found, or not in your organization).

Endpoints

GET /api/v1/health

The service version and whether the virus scanner answers.

GET /api/v1/stats

Message counts per verdict. Parameter hours (default 24, up to 90 days).

{"hours": 24, "by_verdict": {"clean": 812, "spam": 40, "phish": 2}}

GET /api/v1/messages

Search messages. Parameters:

ParameterMeaning
qText in the sender or subject.
verdictOne verdict or a comma-separated list, for example phish,bec.
hoursHow far back to look. Default 24.
limitDefault 100, maximum 1000.

Each message has id, received_at, direction, from, mail_from, subject, score, verdict, action, reason, message_id, recipients (each with its status) and ai (the AI verdict, when the model reviewed it). Newest first.

GET /api/v1/messages/{id}

One message, with details: every scan stage's data.

POST /api/v1/messages/{id}/release

Releases to every quarantined recipient, or only to those in an optional JSON body {"rcpts": ["[email protected]"]}. Returns {"ok": true, "info": "..."}.

POST /api/v1/messages/{id}/delete

Deletes the message from quarantine. Returns {"ok": true, "info": "..."}.

POST /api/v1/lists

Adds an allow or block entry to your organization's list:

{"kind": "block", "pattern": "@bad.example", "note": "ticket 1234"}

kind is allow or block. pattern takes the list entry formats. Returns {"ok": true, "info": "..."}.

Connected apps (your users' own quarantine)

Obsidian Mail connects with each user's own sign-in, not with an API token, and sees only that user's quarantine (see User portal). The calls are documented here for completeness; you do not need them for the app.

The app opens https://portal.obsidiansuite.net/app/connect in the browser with redirect_uri (a loopback address on the device: http://127.0.0.1:<port>/<path> or http://localhost:<port>/<path>), state, a PKCE code_challenge with code_challenge_method=S256, mailbox (the address of the account the app has loaded; required), and the app and device names shown to the user. Allow is offered only when mailbox is one of the signed-in user's addresses. After Allow the browser returns to redirect_uri with code and state (or error=access_denied). The app then calls:

CallWhat it does
POST /api/v1/app/token{"code", "code_verifier"} gives {"token", "email", "display_name", "addresses", "mailbox", "portal"}. The code works once and for 5 minutes; anything wrong gives 400 invalid_grant.
GET /api/v1/meThe user's email, display_name, addresses, the mailbox this connection is for, the service version and brand.
GET /api/v1/me/quarantine{"items": [...], "count"}, newest first, limit up to 500 (default 200). Each item: id, received_at, from, from_name, mail_from, subject, verdict, score, reason, size, status, rcpts (the user's own addresses on it), admin_only, can_release, has_raw.
GET /api/v1/me/quarantine/{id}/rawThe message itself (message/rfc822). 403 when it is held for an administrator, 410 when it is no longer kept.
POST /api/v1/me/quarantine/{id}/release{"allow_sender": true} also adds the sender to the user's allow list. 403 when the policy keeps it for an administrator.
POST /api/v1/me/quarantine/{id}/deleteRemoves it from the user's quarantine.
POST /api/v1/me/quarantine/{id}/report{"label": "spam" or "ham", "block_sender": true} teaches the filter; spam with block_sender also blocks the sender for the user.
DELETE /api/v1/me/tokenThe app disconnects itself.

The token goes in the same Authorization: Bearer header. Errors carry {"detail": "..."}; 401 means the connection was disconnected, expired after 180 days unused, its mailbox is no longer the user's, or the user was deactivated; reconnect means it was made before connections were tied to a mailbox and must be made again.

Secure messages

For a mail client that sends a message encrypted for any recipient. The client encrypts the message itself with AES-256-GCM and a new 256-bit key per message. The envelope is base64(iv[12] || ciphertext || tag[16]) with the additional authenticated data obsidian-secure-v1. The plaintext is JSON: {"v": 1, "subject", "from", "text", "html", "sent", "attachments": [{"name", "type", "data"}]} (attachment data in base64); a reply is {"v": 1, "from", "text", "sent"}.

POST /api/v1/secure-messages

{"sender": "[email protected]", "sender_name": "Your Name", "recipients": ["[email protected]"], "ciphertext": "<base64>", "expires_days": 30}

Up to 25 MB of encrypted data and 50 recipients; expires_days defaults to 30 and is limited by the service maximum. Returns the message's id, link, expires_at and status. Send the recipients the link with #k=<key> appended, the key encoded as base64url without padding (43 characters). The key never goes to the server.

GET /api/v1/secure-messages/{id}

Status: expires_at, revoked, opened (who opened it, when) and the number of replies.

GET /api/v1/secure-messages/{id}/replies

The recipients' answers, encrypted with the message's key: {"replies": [{"id", "from", "created_at", "ciphertext"}]}.

DELETE /api/v1/secure-messages/{id}

Withdraws the message: nobody can open it any more, and its data is deleted.