Obsidian SuiteDocumentation
Obsidian Email Security: all chapters

Docs / Obsidian Email Security / Connect your mail

API connectors

An API connector links your mail platform to Obsidian Email Security through its API. It keeps your user list current, lets people sign in with their work accounts, lets administrators claw back a delivered threat, and can scan mailboxes without any change to your MX records (API mode).

Add one on your organization page: API connectors > Add connector, then pick Microsoft 365, Google Workspace or Exchange Server. The credentials each platform needs are in its chapter: Microsoft 365, Google Workspace, Exchange Server.

Capabilities

Every connector has the same switches:

SwitchWhat it does
Connector enabledMaster switch.
Sync users and aliases every 4 hoursCreates a user for every mailbox in your organization's domains, keeps display names and aliases current, and disables users removed from your directory. Users that already exist in another organization, and administrators, are left alone. Sync users runs it now.
Allow clawback of delivered threatsLets administrators use Claw back on a message, and lets AI reviews in async mode pull a delivered threat out of the mailboxes.
API mode: scan new mailbox mail every 2 minutes (no MX change needed)New inbox mail in the scanned mailboxes is read, scanned and acted on inside the mailbox: mail that should be quarantined is moved out (and can be put back with Release), tagged spam is moved to Junk. Scan mailboxes runs it now. The first run only records a starting point; it does not rescan old mail.
Show Microsoft 365's own quarantine here (read every 5 minutes)(Microsoft 365, organizations whose Platform is Microsoft 365; on by default.) Mail that Microsoft's own filtering quarantined in your tenant is listed in Quarantine beside ours. Pull Microsoft quarantine runs it now. Needs the extra permission in Microsoft 365.
Let users sign in with their Microsoft / Google account(Microsoft 365 and Google Workspace.) Adds Continue with Microsoft or Continue with Google to the sign-in page. The person must already exist as a user in Obsidian Email Security; user sync takes care of that.

Save keeps your changes. Test connection checks the credentials and shows what it found; the result is kept as the connector's status, shown at the top of its page with its last activity. Remove connector deletes it and its stored credentials.

Credentials

Secret fields (client secrets, passwords, key files) are encrypted when stored and never shown again. A secret field shows stored when it has a value; leave it blank to keep that value.

Common errors

PlatformErrorCause
Microsoft 365401 / invalid_clientThe client secret expired or is wrong. Create a new one.
Microsoft 365403Admin consent was not granted for Mail.ReadWrite or User.Read.All.
Microsoft 365Exchange Online ... 401 / 403 (Microsoft quarantine)The app lacks Exchange.ManageAsApp or the Security Administrator role. See Microsoft 365.
Google Workspaceunauthorized_clientThe domain-wide delegation scopes are missing or mistyped.
Exchange ServerErrorImpersonateUserDeniedThe service account lacks the ApplicationImpersonation role.