Mailbox Configuration

Configure a SMTP and IMAP Relay (Mailbox Configuration)

The following section describes how to configure a SMTP for sending emails and IMAP for receiving and automatic processing provider in OpenIAM. It is called 'Mailbox Configuration' in OpenIAM. This step is a pre-requisite for sending out email notifications, one-time links for password reset, and one time passwords (OTP).

To configure your Mailbox, follow the steps described below:

  • Login to the Webconsole
  • Go to Administration -> Mailbox configuration.

Mailbox configuration menu

You will be redirected to the page with list of the predefined Mailbox Configurations. By default, there will be configuration related to the previously installed OpenIAM version or configuration related to the previous "System configuration" -> "SMTP Gateway" page.

On the left menu there are 4 options are available for the 'Super Security Admin' Role members. Mailbox configuration menu

There are:

  • Create Mailbox Configuration Template
  • Create Mailbox Configuration
  • Mailbox Configuration Templates
  • Mailbox Configurations

Mailbox Configurations

The default page which displays the list of all Mailbox Configurations available in the system. It is possible to search configurations by name using Search for Mailbox Configuration input.

Mailbox configuration menu

Mailbox Configuration Templates

The page which displays the list of all possible Mailbox Configuration Templates available in the system.

Mailbox configuration menu

There are 5 default templates, available in the system:

Template NameDescriptionReferences
Migrated from previous versionThe template from previous OpenIAM version.This one is used by default for back compatibility
G-Mail SMTP RelayUse G-Mail account to send and receive emails.More details
Office 365 SMTP RelayUse Office 365 account to send and receive emails.More details
SendGrid SMTP RelayUse SendGrid SMTP Relay to send only emails.How to configure SendGrid
SendInBlue SMTP RelayUse SendInBlue SMTP Relay to send only emails.How to configure SendInBlue

Create Mailbox Configuration Template

This page allows you to create new mailbox configuration template to connect with SMTP/IMAP Relay different from presented by default.


Fill the fields based on the settings provided by your SMTP/IMAP template configuration

Parameter nameDescriptionExample
NameThe user friendly name of the Configuration TemplateMy Company Mailbox
SMTP Host NameHost name of your SMTP
SMTP PortPort your SMTP host is receving messages on587
SMTP authAllows the OpenIAM mail client to log in using any authentication mechanism supported by the serverTrue
Start TLS enabledInitiates secure e-mail communicationTrue
Socket factory classInternal factory used to create objects for socket communication. Should always be
Socket factory portFallback port.587
Socket fallbackDetermines if fallback is enabledTrue
Incoming mail hostnameHost name from which incoming emails are
IMAP PortPort used by your mail server for IMAP993
Inbox folderInbox folder name in case OpenIAM is processing in coming emails
IMAP SSL EnabledFlag indicating if SSL is enable for IMAPTrue

The same page is displayed to edit mailbox Configuration Template as well. To delete the Template please be sure that there isn't any linked to it Mailbox Configurations, otherwise system will throw an error:

"Mailbox Configuration Template hasn't been deleted successfully because there are configurations which are related to it. Please delete Mailbox Configurations, related to the current Mailbox Configuration config firstly."

Create Mailbox Configuration

This page allows you to create new mailbox configuration to send emails from the Installation using SMTP and receive an emails for automatic processing.

mailbox-new-config.png Fill the fields based on the settings provided by your SMTP/IMAP template configuration

Parameter nameDescriptionExample
NameThe user friendly name of the ConfigurationMy Mailbox #1
Is ActiveShould this configuration be enabledtrue/false
Read Inbox?Should System read the inbox for this mailbox? This is used for automatic email processingtrue/false
Default sender (Usually the same as UserName):Sender which will be displayed to recipient. This is usually the same as username, due to SMTP Relay
Default subject prefixOptional value to set a prefix on the subject of all emails sent by OpenIAM[OpenIAM Dev server]
Optional Bcc addressE-mail addresses that you want to bcc for all communication
SMTP usernameUsername to authenticate to your
SMTP passwordPassword for your mailbox accountpassword-for-no-reply
Failover Mailbox ConfigurationThe mailbox Configuration in case of the current one will not be able to delivery and email. Even failover config with 'active' flag 'false' will be triggered.
Mailbox Configuration TemplateThe template that will be used for the current credentials and configurationsOffice 365 SMTP Relay
Script to customize MimeMessage messageAllows customizing MIME message by adding custom properties.Empty by default. Contains the address for a groovy script.

In case of multiple active mailbox configurations the round-robin algorithm will be applied to them, however active mailbox configurations that are set as failover for others will be called only in case of the failure of the 'main' mailbox configuration.

Customize MimeMessage messages

When creating or editing mailbox configuration, user can customiza a mail message by means of a groovy script. It can add custom attributes to header, subject, sender, date, and many more.

To customize message, do the following.

  1. Login to webconsole and got to Administration -> Mailbox Configurations.
  2. Select the configuration required and click edit or create a new configuration if needed.
  3. Fill in all the fields as specified above, and in Script to customize MimeMessage message field specify the path to a groovy script. Note: The field is empty by default.
  4. Click save.

The example of a groovy script to be used for this feature is given below.

package org.openiam.sync;
import javax.mail.internet.MimeMessage;
* Class used for customizing email message configuration.
class CustomizeMail implements CustomMailConfigHelper {
public void customizeMessage(MimeMessage message) {
// Example custom headers can be added to the message
message.setHeader("testHeader1", "testHeaderValue2");
// Set the sender (From) address
// Set the subject
message.setSubject("Your subject here");
// Set the body text
message.setText("Your message body here");
// Set the priority of the message
message.setHeader("X-Priority", "1"); // Highest priority
// Set the date of the message
message.setSentDate(new Date());

Understanding Mailbox-configuration rotation

Let's review the following mailboxes set:

Mailbox Config nameFailover Config nameIs Active

In case of the example above:

The round-robin algorithm will be applied to rotate the Mailbox configurations: MB2 and MB4, because they are active, and they are not set up as a failover configurations to others. MB1 is inactive, MB3 is a setup as a failover for MB2, MB5 is set as a failover for MB1. MB5 will be called in case of failure of MB1, MB3 will be called in case of failure of MB2 even in case MB3 is Inactive.