Administration Guide

Outgoing E-mail Settings

On this page

Alloy Navigator sends e-mail notifications through one mail service, which applies to the whole installation: no recipient, class, or job uses a different one. The Automation Server sends the messages from the notification queue. The default mail service is SMTP.

You set up the mail service, test it, and change the global notification settings in the Admin Center or in the Settings App. The Admin Center sets up SMTP, Exchange Online, and Google Mail; EWS and MAPI are set up only in the Settings App. For how notifications are authored and queued, see Notifications Overview.

Mail services

Service How it connects How it signs in Where you set it up
Simple Mail Transfer Protocol (SMTP) An SMTP server, port 25 by default None, or a user name and password, optionally with Secure Password Authentication Admin Center, Settings App
Exchange Online with OAuth authentication Exchange Online, through Microsoft Graph or the EWS API A Microsoft account Admin Center, Settings App
Google Mail (SMTP + OAuth) Google's SMTP server, over SSL/TLS, without rejecting invalid certificates A Google account Admin Center, Settings App
Exchange Web Services (EWS) Exchange Web Services, at a URL you enter or found by Autodiscover A user name and password Settings App
Messaging Application Programming Interface (MAPI) An Outlook profile on the Automation Server computer The Windows account the Automation Server runs under Settings App

Exchange Online and Google Mail do not store a password. Signing in to the account stores the credential that the mail service issues. For Exchange Online, when you choose the Alloy client instead of your own application, an application registered by Alloy is used and the tenant ID is ignored.

Before you begin

  • In the Admin Center, the E-mail Notifications and Global Settings pages require the notifications permission. In the Settings App, the Notifications group requires the same permission as the E-mail Processing group. See Permissions Reference.
  • Exchange Online requires .NET Framework 4.8 and the MSGraphEng.dll component on the Automation Server computer. Signing in to Exchange Online in the Settings App checks for them on the computer you work on as well. When either is missing, the product tells you to run the installer in Repair mode.
  • In the Admin Center, the Microsoft account sign-in needs a page that the browser treats as secure, such as one opened over HTTPS; otherwise the sign-in fails with an error.
  • For MAPI, the Outlook profile must be created using a 64-bit edition of Microsoft Outlook on the Automation Server computer, for the Windows account under which the Automation Server runs.
  • Sending a test message requires a running Automation Server.
  • Exchange Online and Google Mail sign in with an application that you prepare in Microsoft Entra ID or in Google Cloud. See Prepare Microsoft Entra ID for Exchange Online and Prepare Google Cloud for Google Mail.
  • 'From' address delegation requires the Send on behalf permission on the mailbox of every 'From' address. See Prepare Exchange for 'From' address delegation.

Prepare Microsoft Entra ID for Exchange Online

Exchange Online signs in with the client you choose under Client. Prepare that client in Microsoft Entra ID before you sign in to the account.

Use the Alloy Mail Connector client

Alloy Mail Connector (admin consent required) is a multi-tenant application registered by Alloy Software. It needs tenant-wide admin consent in your Microsoft Entra tenant. An administrator whose role allows granting consent on behalf of the organization, such as a Cloud Application Administrator or an Application Administrator, grants it. See Microsoft's Grant tenant-wide admin consent to an application.

Register your own application

  1. Sign in to the Microsoft Entra admin center, browse to Entra ID > App registrations, and select New registration. See Microsoft's How to register an app in Microsoft Entra ID.
  2. Enter a name for the application. Under Supported account types, choose a single-tenant or a multi-tenant application, then select Register.
  3. On the application's Overview page, copy the Application (client) ID. For a single-tenant application, also copy your tenant ID; see Microsoft's How to find your tenant ID.
  4. Under Manage, select Authentication, select Add Redirect URI, and choose the Mobile and desktop applications platform. See Microsoft's How to add a redirect URI to your application.
  5. Add two custom redirect URIs: the address of the Admin Center, which is the Web App address followed by admin-center/ (for example, https://example.com/wp/admin-center/), and http://localhost. Then select Configure.
  6. In Alloy Navigator, under Client, choose Custom application registered in your Azure portal. Enter the Application (client) ID in Client ID. For a single-tenant application, enter the tenant ID in Tenant ID; for a multi-tenant application, leave Tenant ID empty.

Prepare Google Cloud for Google Mail

Google Mail signs in with an OAuth client that you create in Google Cloud. You can use the same client as a Google Mail job of the Mail Connector; see Set Up Mail Connector Jobs.

  1. In the Google Cloud console, create a project or select an existing one.
  2. Browse to APIs & Services > Library, open Gmail API, and select Enable.
  3. Configure the consent screen in Google Auth Platform: enter the app information on Branding, and choose the user type on Audience. Choose Internal when the app is used only within your Google Workspace organization, or External; for External with the publishing status Testing, add the mailbox account as a test user. See Google's Configure the OAuth consent screen and choose scopes.
  4. Browse to Google Auth Platform > Clients and select Create Client. Choose Desktop app, or choose Web application and add http://127.0.0.1/authorize/, with the slash at the end, under Authorized redirect URIs. See Google's Create access credentials.
  5. Copy the client ID and the client secret of the new client.
  6. In Alloy Navigator, enter them in Client ID and Client Secret, and sign in with the mailbox account.

The sign-in needs access to the scope https://mail.google.com/, which Google requires for sending mail through its SMTP server with OAuth; see Google's OAuth 2.0 Mechanism. Grant it when Google asks.

NOTE: For a consent screen with the External user type and the publishing status Testing, Google issues refresh tokens that expire in 7 days, unless the only scopes requested are name, e-mail address, and user profile. See Refresh token expiration.

Prepare Exchange for 'From' address delegation

With 'From' address delegation, MAPI, EWS, and Exchange Online send notifications on behalf of another user. For this, the mailbox of every address used as a 'From' address must grant the Send on behalf permission to the account that sends the notifications:

  • MAPI: the Exchange account of the Outlook profile that the Automation Server uses, the one chosen under Mail Profile or the default profile.
  • EWS: the account entered in Username.
  • Exchange Online: the Microsoft account you signed in with.

The permission gives the sending account no access to the folders of the mailbox. Recipients see both addresses in the From line, as sending account on behalf of 'From' address, and replies go to the 'From' address.

To grant the permission in the Exchange admin center of Exchange Online:

  1. In the Exchange admin center, select Recipients > Mailboxes, and select the mailbox of the 'From' address.
  2. Select Mailbox delegation. Under Send on behalf, select Edit, and then select Add members.
  3. Select the sending account, and then select Save > Confirm.
  4. Repeat these steps for every 'From' address.

See Microsoft's Manage permissions for recipients in Exchange Online, which also gives the PowerShell route: the GrantSendOnBehalfTo parameter of Set-Mailbox. The Exchange admin center does not offer Send on behalf for a shared mailbox; use PowerShell for one.

You can grant the same permission in other ways:

  • In the Microsoft 365 admin center, open Users > Active users, select the user of the 'From' address, and on the Mail tab select Send on behalf of permissions > Add permissions. See Microsoft's Give mailbox permissions to another user. The change can take up to 60 minutes to take effect.
  • On Exchange Server 2016, 2019, or Subscription Edition, in the Exchange admin center of the server, select Recipients > Mailboxes, edit the mailbox of the 'From' address, and in Mailbox delegation add the sending account under Send on Behalf, then select Save. See Microsoft's Manage permissions for recipients.
  • The person who owns the 'From' mailbox adds the sending account as a delegate in Outlook, with no access to any folder. See Microsoft's About delegates: Allow someone to manage your mail and calendar in Outlook.

NOTE: Send on behalf does not work for a mailbox that is hidden from address lists. If the sending account also has the Send as permission on the mailbox, Exchange uses Send as, and the From line shows only the 'From' address.

In the Admin Center

Set up the mail service

  1. Open Notifications > E-mail Notifications.
  2. Under Choose e-mail service, select the service. For EWS and MAPI, the page shows only the warning "This feature is not yet available in the Admin Center. Please use the desktop Settings App." and no Message options or Test Settings.
  3. Enter the settings of the service, as described below.
  4. Under Message options, enter the 'From' address, and set Character set, Send all e-mail messages in plain text format, and the attachment limit. Character set offers 22 character sets for SMTP, UTF-8 by default. For Exchange Online and Google Mail it is read-only and set to UTF-8.
  5. Click Save. The page checks the 'From' address, the user name and password when SMTP authentication is on, the server and port for SMTP, and the account for Exchange Online and Google Mail. If any is missing, a warning starts with "You have not specified the following parameter(s):", lists each missing value, and asks "Alloy Navigator might not be able to send e-mail notifications. Do you want to save notification settings anyway?" Yes saves, No does not.

In Cloud, the attachment limit is on, fixed at 1 MB, and its controls are disabled; see Administering Alloy Navigator Cloud. An Exchange Online or Google Mail setup saved without a signed-in account shows Configuration incomplete, with "Click Sign in to authenticate with your Microsoft work account and complete the configuration.", with Google in place of Microsoft for Google Mail.

SMTP

  • Outgoing mail server and the port, from 1 to 65535. The port's hint reads "Default: 25", or "Default: 465" under SSL/TLS.
  • My outgoing (SMTP) server requires authentication enables Username, Password, and Require Secure Password Authentication (SPA).
  • Secure connection, None when nothing is stored, and Reject invalid certificates. Reject invalid certificates is disabled while Secure connection is None. Once you edit the form, choosing SSL/TLS changes port 25 to 465, and leaving it changes 465 back to 25.

Exchange Online with OAuth authentication

  • API: Microsoft Graph, preselected when nothing is stored, or Exchange Web Services (EWS).
  • Client: Alloy Mail Connector (admin consent required) or Custom application registered in your Azure portal. For the Alloy client, Your organization uses Microsoft Cloud for US Government, Client ID, and Tenant ID are disabled. The hint of Tenant ID reads "Leave empty for a multi-tenant application".
  • Account: sign in with the Microsoft account in the sign-in window that opens. The sign-in requests Mail.ReadWrite, Mail.Send, openid, profile, and offline_access for Microsoft Graph, or EWS.AccessAsUser.All, openid, profile, and offline_access for EWS. The account is required. Once you edit the form, changing Client ID, Tenant ID, the client, or the API clears the signed-in account, and the field then shows the account name followed by "is no longer signed in".
  • 'From' address delegation.

Google Mail (SMTP + OAuth)

  • The server and the port are disabled. The server is smtp.gmail.com, or the stored server when Google Mail is the saved service. The port is set to 465 once you edit the form; choosing Google Mail counts as an edit.
  • Enter Client ID and Client Secret, then sign in under Account. Account is enabled once both are filled in. Once you edit the form, changing Client ID or Client Secret clears the signed-in account in the same way.

Send a test message

  1. On Notifications > E-mail Notifications, click Test Settings. The button is disabled while a required value is missing. It is also disabled while the Automation Server is not active, and the page then says "The Automation Server is unavailable. Make sure it is configured and running."
  2. If you have unsaved changes, you are asked "You must save your changes before proceeding. Do you want to save the changes now?"
  3. In the Send Test Message dialog, enter the address to send the test message to, and send it. The message is sent from the form's 'From' address. Your browser remembers the address for the next test.

On success the page says "Test message has been sent." On failure it shows the first message the mail engine returned, or "Failed with no messages".

Change the global notification settings

  1. Open Notifications > Global Settings.
  2. Under Common notification options, set:
    • Check notification queue every n second(s).
    • Do not send notifications to users who trigger them.
    • Under When attempting to send a notification with no recipient specified:, Mark the notification as failed and leave it in the queue or Delete the notification from the queue.
  3. Click Save. Save and Cancel appear once you edit the form.

In the Settings App

Set up the mail service

  1. Open Notifications > E-mail Notifications > Settings. The page reads "You will need to enter valid settings here before you can use e-mail notifications."
  2. Under Choose e-mail service:, select the service. The settings of that service replace the pane below. Choosing MAPI shows the warning "MAPI support is being deprecated and will not be available in future versions. Please use EWS for Exchange on-premises or migrate your mailbox to Exchange Online."
  3. Enter the settings of the service, as described below.
  4. Under Message options, set 'From' e-mail address:, Character set: (shown for SMTP only; the other services use Unicode (UTF-8)), Send all e-mail messages in plain text format, and Limit the total size of attachments to n MB. In Cloud, the Limit the total size of attachments to check box and its size box are disabled; see Administering Alloy Navigator Cloud.
  5. Apply your changes. If a value the service needs is missing, a message starts with "You have not specified the following parameter(s):", lists what is missing, and asks "Alloy Navigator might not be able to send e-mail notifications. Do you want to save the notification settings anyway?" No discards your edits; Cancel returns to the page.

A successful save sends the Automation Server a command to reload its settings, so the running service uses the new settings without a restart. When you apply changes while a page other than Settings is shown, including Global Settings and HTML Templates, a blank MessageID Tag prefix or suffix stops the save.

SMTP

  • Outgoing mail server: and Outgoing mail server port:, with the hint "Default: 25".
  • My outgoing (SMTP) server requires authentication enables Username:, Password:, and Require Secure Password Authentication (SPA).
  • Secure connection: None, STARTTLS, if available, STARTTLS, or SSL/TLS. Reject invalid certificates is enabled only when the mode is not None. Choosing SSL/TLS changes the hint to "Default: 465" and a port of 25 to 465; leaving it changes 465 back to 25. Any other port is left as it is.
  • The SMTP server name, the port, and the 'From' address are needed to save without a warning.

Google Mail (SMTP + OAuth)

  • The server smtp.gmail.com and port 465 are filled in and cannot be changed, and the connection uses SSL/TLS.
  • Under Use OAuth authentication:, enter the Client ID and the Client Secret, and sign in with the Google account. Without them, the sign-in stops with "The Client ID is not specified" or "The Client Secret is not specified".
  • The sign-in happens in a browser window: sign in with a Google Account and grant the client permissions; the credentials are then saved automatically. Cancel in the progress dialog stops the sign-in. If Google does not grant the requested access, a message says that authorization failed and asks you to sign in again.
  • The account is needed to save without a warning.

Exchange Online with OAuth authentication

  • Choose the API, Microsoft Graph or EWS.
  • Choose the client: Alloy Mail Connector (admin consent required), selected by default, or Custom application registered in your Azure portal. Choosing the Alloy client clears the tenant ID.
  • Client ID and Tenant ID. Your organization uses Microsoft Cloud for US Government is enabled only for a custom application, and takes effect only when the Client ID is filled in.
  • Sign in with the account. The account is needed to save without a warning.
  • 'From' address delegation.

Exchange Web Services (EWS)

  • Under EWS connection details, choose Specify the Exchange Web Services URL or server name: and fill in EWS:, or choose Autodiscover the Exchange Web Services URL using this address: and fill in E-mail Address:. Only the chosen box is enabled. If you type a URL without ://, the page proposes https://<what you typed>/EWS/Exchange.asmx and asks "Do you want to use this Exchange Web Services URL?"; Cancel returns to the field.
  • Username: and Password:.
  • Version:: Autodetect the version of Microsoft Exchange Server, the default, or a specific Exchange Server version from 2007 Service Pack 1 to 2013 or later.
  • Reject invalid certificates and 'From' address delegation.
  • The user name and the URL or Autodiscover address are needed to save without a warning.

Messaging Application Programming Interface (MAPI)

  • Under Microsoft Exchange, choose the Mail Profile:, or select Use default profile. The profile list comes from the Automation Server, not from the computer you work on. If the list cannot be fetched, the page says "Cannot send request to the Automation Server. Make sure the Automation Server is configured and started." In some failures, the page instead shows "Since your Settings App and the Automation Server are installed on separate computers, it may take some time to test your settings. Please wait until the job has completed, and then check the session log to make sure that it runs as expected."
  • 'From' address delegation.

For MAPI, EWS, and Exchange Online, 'From' address delegation allows sending notifications on behalf of another user. You must set up delegate access for every 'From' address; see Prepare Exchange for 'From' address delegation.

Send a test message

  1. On the Settings page, click Test Settings. The button is enabled when the service's key values are filled in: for SMTP, the server and the port; for MAPI, a profile or Use default profile; for EWS, the user name and the URL or Autodiscover address; for Exchange Online and Google Mail, a signed-in account.
  2. If you have unsaved changes, you are asked "You must save your changes before proceeding. Do you want to save the changes now?"
  3. In the Send Test Message window, enter a valid address in To:. The window reads "Enter an e-mail address where you want the test message sent. This must be a valid e-mail address so you can review the result."

The Settings App queues a message with the subject "Test e-mail message -" followed by the product and version, and has the Automation Server send it at once. The body reads "This test message has been sent from" followed by the application name and "to confirm successful configuration of e-mail settings." The test message is plain text. The result is one of:

  • "Test message has been sent."
  • "The Automation Server is running, however the message couldn't be sent.", followed by the mail engine's text. The test message is then removed from the queue.
  • "Since your Settings App and the Automation Server are installed on separate computers, it may take some time to test your settings. Please wait, a test message will be sent shortly."
  • "The test message cannot be sent. Make sure the Automation Server is configured and started." Nothing is queued in this case.

When the Automation Server checks the queue, it skips a new test message for at least 30 seconds, so that the message is not sent with the mail settings the Automation Server held before your change.

Change the global notification settings

NOTE: Before you change these settings, make sure that Prefix: and Suffix: on the MessageID Tag page under E-mail Processing are filled in. While either is blank, the Settings App refuses to apply changes made on Global Settings.

  1. Open Notifications > Global Settings.
  2. Under Common notification options, set:
    • Check notification queue every n second(s).
    • Do not send notifications to users who trigger them.
    • Under When attempting to send a notification with no recipient specified:, Mark the notification as failed and leave it in the queue or Delete the notification from the queue.
  3. Apply your changes.

How the settings work

  • 'From' address: The default sender of outgoing notifications.
  • Plain text: With Send all e-mail messages in plain text format selected, HTML messages are converted to plain text before they are sent, and embedded images travel as ordinary attachments instead of inline images. The option is off by default.
  • Attachment limit: Outgoing notifications have an attachment size limit of their own, separate from the general attachment limit. It is off by default, and its size is 1 MB by default. In Cloud, the limit's controls are disabled in the Admin Center and in the Settings App, and a save in the Admin Center stores the limit as on at 1 MB; see Administering Alloy Navigator Cloud.
  • Secure connection: SMTP offers None, STARTTLS, if available, STARTTLS, and SSL/TLS. A secured SMTP connection uses TLS 1.0, 1.1, or 1.2, and SSL/TLS also allows SSL 3.0. Under STARTTLS, if available, a connection whose TLS handshake fails is retried without encryption; under STARTTLS, it fails. With Reject invalid certificates cleared, an invalid certificate name or date, an unknown authority, revocation, and a wrong usage are ignored.
  • Queue check interval: Check notification queue every sets how often the Automation Server checks the queue, from 1 to 65535 seconds, 10 seconds by default. In Cloud, the Admin Center and the Settings App do not accept a value below 60 seconds, a save in the Admin Center raises a lower value to 60 seconds, and the Automation Server and the Settings App use 60 seconds when no value is stored; see Administering Alloy Navigator Cloud.
  • Notifications to the user who triggers them: With Do not send notifications to users who trigger them selected, the acting user's own address is removed from the To list. CC and BCC still reach that user. If no recipient is left, the message is not queued at all. The box is clear by default.
  • Notifications with no recipient: By default, such a notification is marked as failed and left in the queue. You can choose to delete it from the queue instead.
  • MessageID tag: When a notification is queued for a record, the record's ID is added to the subject as a MessageID tag, unless the subject already contains it or automatic insertion is turned off. By default the tag is added at the end, with the prefix MessageID: and the suffix #. The tag is what makes replies land on the right record. You set its prefix, suffix, and position, or turn automatic insertion off, on the MessageID Tag page under E-mail Processing in the Admin Center or the Settings App; see Set the MessageID tag.