Overview

Obsidian is an email security gateway. It checks every message for spam, viruses, phishing and business email compromise before it reaches Microsoft 365, Google Workspace or Exchange, and lets administrators and users manage what it holds back.

Install and set upFrom a blank Ubuntu 24.04 server to your first protected domain. Go-live checklistDNS, certificates, firewall and MX cut-over, in order. How filtering worksScores, verdicts, actions, holds - the model behind every screen. For end usersReviewing your quarantine, digests, sign-in and two-factor.

What it does

Internet→Connection check (Spamhaus ZEN)→Scan pipeline→Decision→Microsoft 365 / Google / Exchange

Connection filtering - known botnets and spam sources are dropped before they can send anything.
Sender authentication - SPF, DKIM, DMARC and ARC; spoofs of your own domains are caught.
Reputation - Spamhaus lists for IP addresses, domains, brand-new domains and file/address hashes.
Antivirus - ClamAV with additional phishing/scam signatures.
Attachments - dangerous file types, disguised executables, macros, encrypted archives, PDF scripts, HTML smuggling.
Links and impersonation - lookalike domains, fake display names, executive impersonation, link text that lies.
Content - phishing, payment fraud, scams, sextortion, QR-code and call-back lures.
Learning - a Bayesian filter that learns from "Report spam" / "Not spam".
AI - a local language model (on your own hardware) reviews borderline mail and explains its reasoning.
Remediation - quarantine, release, and "claw back" of mail already delivered to mailboxes.

Who uses which part

Role	Can do	Start at
MSP administrator (superadmin)	Everything: every organization, platform settings, system health, API tokens.	Setup, Settings
Organization administrator (admin)	Their own organization: messages, quarantine, domains, connectors, users, policies, lists, audit log.	Dashboard, Quarantine
User	Their own mailbox: quarantine, recent mail, personal allow/block lists, password and two-factor.	User portal

Two ways to protect a mailbox

Gateway mode - the domain's MX record points at Obsidian. Every message is scanned before delivery; spam can be refused outright. This is the strongest protection.

API mode - no DNS change. Obsidian reads new mail from the mailbox through the Microsoft Graph, Gmail or Exchange API every two minutes and moves threats out. Use it for pilots, for tenants you cannot re-route, or together with gateway mode for AI "claw back".

Both modes can run at the same time: mail that already passed the gateway is recognised by its X-Obsidian-ID header and not scanned twice.

Finding your way around

Every screen of the admin console has a page in this guide - follow the left-hand contents in order the first time. The rule reference explains every finding you will see on a message, and troubleshooting covers the problems people actually hit.