Docs / Obsidian Mail Server / Mail flow
Obsidian Email Security
Obsidian Email Security is the filtering gateway that sits in front of this server: your MX record points at it, it checks every message for spam, viruses and phishing, holds what is dangerous in its quarantine, and hands the rest to this server. Both work without each other; connected, they work as one. Everything here is under Email Security.
What connecting gives you
- Spam goes to Junk Email. Mail Email Security delivers with the verdict spam (header
X-Obsidian-Spam: Yes) lands in the person's Junk Email folder instead of the Inbox, and skips their inbox rules and automatic replies. Bulk mail (newsletters, marketing,X-Obsidian-Bulk: Yes) can go there too: tick Also put bulk mail in Junk Email. - Verdicts nobody can forge. Once the gateway's address is set,
X-Obsidian-...headers count only from it. The same headers on mail from anyone else are removed as the mail arrives, so a sender cannot make spam look checked. - A status card with Email Security's version, whether its antivirus runs, and how much mail it checked in the last 24 hours, by verdict, plus a button that opens its portal.
- Email Security knows your people. Its Obsidian Mail Server connector reads this organization's mailboxes, groups and their addresses, so it accepts mail only for addresses that exist, and people sign in to its portal (their quarantine, their reports) with the password they use here.
- Take back what got through. When Email Security learns later that a delivered message was dangerous (its AI review, or an administrator), it can pull it out of the mailbox. The message goes to Recoverable Items, out of the person's sight, exactly where Exchange puts it; Restore in Email Security puts it back where it was.
Connect
- In Email Security, make an API token: Settings > API tokens, for this organization.
- Here, open Email Security, enter the Portal address (for example
https://portal.obsidiansuite.net) and paste the token, then Connect. The status card appears and should say Connected. The token is kept encrypted on this server. - Under Spam filing, set the gateway's address: the list Servers that delivered mail here shows who sends mail to this server; Email Security is normally at the top. Choose Use as gateway next to it and Save addresses. Global administrators set this, for the whole server. Use the address this server sees, which is the gateway's own address on your network when both are on it.
If Email Security delivers from several addresses (two gateways, or a range), list them all, one per line, or as a range like 10.0.0.24/29.
The connector in Email Security
- Under Connector for Email Security, choose Create key. The server address and the key are shown once: copy both.
- In Email Security: Organizations > your organization > Add connector > Obsidian Mail Server. Paste the server address and the key and save.
- Choose Test, then Sync users. Your mailboxes, shared mailboxes, rooms, groups and public folders appear in Email Security with all their addresses; disabled accounts come along marked as disabled (they still receive mail, but cannot sign in to the portal).
The connector signs in with the key only, never with a person's password, and sees only its own organization. Each use shows under Last used with the address it came from. Revoke stops a key at once; make a new one and paste it into the connector to carry on.
If Email Security cannot reach this server by its public name from where it runs, enter this server's address in the connector's Connect to address field; the name is still used for the certificate.
What the connector may do
| What | How |
|---|---|
| Read people, groups and addresses | Mailboxes, groups and mail-enabled public folders, with every address. Contacts are left out (their addresses live elsewhere). |
| Check a portal password | Like a sign-in to webmail, including Active Directory passwords. Failed attempts count toward the account's sign-in throttle. |
| Find a delivered message | By its Message-ID, in one person's mailbox. |
| Take a message back | Moves it to Recoverable Items (hidden; kept for 14 days, longer under a hold). |
| Move a message to Junk Email | When Email Security marks it as spam after delivery. |
| Restore | Back from Recoverable Items to the folder it came from, or from Junk Email to the Inbox. |
| Read new Inbox mail | Mail that arrived in the last day, for Email Security's mailbox scanning (mail it already checked on the way in is skipped). |
What the connector changes in a mailbox is in the Mailbox audit log as an administrator action by Email Security (key name), over Email Security. Making and revoking keys is in Change history.
Without Email Security
Nothing changes until you connect: mail marked X-Obsidian-Spam: Yes still goes to Junk Email (from any sender, since no gateway address is set), and no key exists, so nothing can use the connector API.