Configure Outbound Email

The outbound email service relies on a configuration object to identify the email account that is used to send messages. A sample configuration is provided in samples/example-configurations/conf/external.email.json. To set up the external email service, follow these steps. You do not have to shut down IDM:

1. Copy the sample email configuration to your conf/ directory. For example:

   cp /path/to/openidm/samples/example-configurations/conf/external.email.json /path/to/myproject/conf/

2. Edit external.email.json to reflect the account that is used to send messages, for example:

   {
       "host" : "smtp.gmail.com",
       "port" : 587,
       "debug" : false,
       "auth" : {
           "enable" : true,
           "username" : "admin",
           "password" : "Passw0rd"
       },
       "from" : "admin@example.com",
       "timeout" : 300000,
       "writetimeout" : 300000,
       "connectiontimeout" : 300000,
       "starttls" : {
           "enable" : true
       },
       "ssl" : {
           "enable" : false
       },
       "smtpProperties" : [
           "mail.smtp.ssl.protocols=TLSv1.2",
           "mail.smtps.ssl.protocols=TLSv1.2"
       ],
       "threadPoolSize" : 20
   }

   IDM encrypts the password when you restart the server (or if you configure outgoing email using the Admin UI).

   You can specify the following outbound email configuration properties:

   host

   The host name or IP address of the SMTP server. This can be the localhost, if the mail server is on the same system as IDM.

   port

   SMTP server port number, such as 25, 465, or 587.

   Note

   Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.

   debug

   When set to true, this option outputs diagnostic messages from the JavaMail library. Debug mode can be useful if you are having difficulty configuring the external email endpoint with your mail server.

   auth

   The authentication details for the mail account from which emails will be sent.

   • enable—indicates whether you need login credentials to connect to the SMTP server.

     Note

     If "enable" : false,, you can leave the entries for "username" and "password" empty:

     "enable" : false,
     "username" : "",
     "password" : ""

   • username—the account used to connect to the SMTP server.

   • password—the password used to connect to the SMTP server.

   starttls

   If "enable" : true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS.

   from

   (Optional) Specifies a default From: address that users see when they receive email from IDM.

   Important

   Although from is optional in the ${emailConfig}, the email service requires this property to send email. If you do not specify a from address in the ${emailConfig}, you must provide one in another way, for example:

   • From an email template.

   • As a parameter in the email service request (from or _from) .

   ssl

   Set "enable" : true to use SSL to connect, and to use the SSL port by default.

   smtpProperties

   Specifies the SSL protocols that will be enabled for SSL connections. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

   threadPoolSize

   (Optional) Emails are sent in separate threads managed by a thread pool. This property sets the number of concurrent emails that can be handled at a specific time. The default thread pool size (if none is specified) is 20.

   connectiontimeout (integer, optional)

   The socket connection timeout, in milliseconds. The default connection timeout (if none is specified) is 300000 milliseconds, or 5 minutes. A setting of 0 disables this timeout.

   timeout (integer, optional)

   The socket read timeout, in milliseconds. The default read timeout (if none is specified) is 300000 milliseconds, or 5 minutes. A setting of 0 disables this timeout.

   writetimeout (integer, optional)

   The socket write timeout, in milliseconds. The default write timeout (if none is specified) is 300000 milliseconds, or 5 minutes. A setting of 0 disables this timeout.

3. Restart IDM if it is not running.