OptimiDoc Server Help Center
OptimiDoc Server Help Center
Breadcrumbs

Mail Configuration (SMTP / OAuth)

Mail Configuration defines the single global SMTP identity OptimiDoc uses to send its own email — administrator alerts, scheduled reports, PIN and password messages, rule notifications and scan download links. It supports classic Login & Password authentication as well as OAuth 2.0 for Google Workspace and Microsoft 365, so it keeps working after providers disable basic authentication.

Overview

This is the server's outbound system mailbox. Everything OptimiDoc generates automatically is sent through it, using the Sender Email as the From address. The features that rely on it include:

  • Automatic report delivery — scheduled reports sent as an XLSX attachment.

  • Device monitoring notifications — alerts when a monitored device changes state.

  • User credential messages — PIN (re)sending, bulk PIN mailouts and password-reset links.

  • Rule email actions — the Send Email Notification and Send Email To actions of the Rules engine.

  • Scan-to-OptimiDoc links — the download-link email produced when a scan is delivered to a user's OptimiDoc storage.

  • System alerts — scan delivery-failure warnings to the admin and the low-OCR-volume warning.

Scan-to-Email is different. A scan template that emails documents to recipients does not use this global configuration — each Email scan destination carries its own SMTP (or mailbox) settings. Configure those on the destination itself. The global mail settings on this page are only for OptimiDoc's own system email.

Accessing Mail Configuration

  1. Open the React administration interface as an Admin user.

  2. Go to Settings in the left sidebar (route /config).

  3. Select the Mail tab (it is the default tab).

Server and Sender Settings

Setting

Description

SMTP Server

The hostname or IP address of the SMTP server (e.g. smtp.office365.com or smtp.gmail.com).

Port

The SMTP port. Common values: 587 (STARTTLS), 465 (SSL/TLS), 25 (unencrypted). Defaults to 587.

Use SSL/TLS

Enable encrypted communication with the SMTP server. Recommended for all production environments.

Sender Email

The From address stamped on every message OptimiDoc sends. In OAuth mode this address is also used as the authenticating SMTP account, so it must match the mailbox you authorise.

Admin Email

The recipient of administrator and system notifications (delivery failures, monitoring alerts, the configuration test message, and so on).

Authentication Methods

Choose one of three options from the Authentication Type dropdown. The extra fields on the tab change to match your choice.

Login and Password

Classic SMTP authentication with a Username and Password. This suits on-premises SMTP servers and any provider that still accepts basic authentication. The username is often the full email address.

Google OAuth

For Gmail and Google Workspace. OptimiDoc requests the https://mail.google.com/ scope.

  1. Select Google OAuth.

  2. Enter the Client ID and Client Secret from your Google Cloud Console OAuth client.

  3. Click Save, then Authorize. The browser navigates to Google's consent screen; after you grant access, Google returns through OptimiDoc's shared redirect proxy at oauth.optimidoc.com and the refresh token is stored on the server (encrypted).

  4. An OAuth authorized badge then appears on the tab.

Microsoft OAuth

For Microsoft 365 and Exchange Online. OptimiDoc requests offline_access and the https://outlook.office.com/SMTP.Send scope.

  1. Select Microsoft OAuth.

  2. Enter the Client ID and Client Secret from your Azure AD app registration.

  3. Click Save, then Authorize and complete Microsoft's consent, again returning through the shared proxy.

  4. The OAuth authorized badge confirms the connection.

Only a "has token" flag is ever sent back to the browser — the refresh token itself never leaves the server. Re-authorising simply replaces the stored token. The Authorize button navigates the whole window (not a popup), so save any other unsaved changes first.

Testing the Configuration

The Test Connection button does not merely open a socket — it sends a real email with the subject OptimiDoc Configuration Test to the Admin Email address. You therefore need SMTP Server, Sender Email and Admin Email filled in before testing, and a genuine SMTP failure is reported back with its error message.

If the test fails, check the following:

Issue

Resolution

Connection refused

Verify the SMTP server address and port. Check that the firewall allows outbound connections on that port.

Authentication failed

Verify the username and password. For OAuth, confirm the Sender Email matches the authorised mailbox and re-authorise.

SSL/TLS error

Ensure the SSL/TLS toggle matches the server's requirements. Port 587 typically uses STARTTLS.

Timeout

The SMTP server may be unreachable from the OptimiDoc server. Check network connectivity.

Tips

  • Microsoft 365 and Google have both disabled basic authentication for many tenants — prefer the OAuth options for long-term compatibility.

  • Because the Sender Email is the OAuth login, use a dedicated no-reply mailbox that you can authorise once and leave in place.

  • Re-run Test Connection after any change to the server, credentials or network path.

In Summary

Mail Configuration is the one place you define how OptimiDoc sends its own email. Set the server, choose an authentication method (basic or OAuth), point Sender Email at the mailbox you control and Admin Email at whoever should receive alerts, then send yourself the test message to confirm it works. Remember that scan-to-email templates carry their own SMTP settings and are unaffected by anything here.

Related articles