Configure Outbound Email

The outbound email service sends email from IDM, using a script or the REST API.

You can edit the email service over REST at the config/external.email endpoint, or in the external.email.json file in your project's conf directory.

To configure the outbound email service in the Admin UI, select Configure > Email Settings.

This sample email configuration sets up the outbound email service:

Sample Email Configuration

{
    "host" : "smtp.gmail.com",
    "port" : 587,
    "debug" : false,
    "auth" : {
        "enable" : true,
        "username" : "xxxxxxxx",
        "password" : "xxxxxxxx"
    },
    "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
}

Edit the email configuration to reflect the mail server details and the account that is used to send messages. The complete list of configuration properties is as follows:
External 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 email configuration, the email service requires this property to send email. If you do not specify a from address in the email configuration, 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.

Submit the configuration over REST or copy the file to your project's conf/ directory. For example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
    "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
}' \
"http://localhost:8080/openidm/config/external.email"

Note

IDM encrypts the password.

Configure Outbound Email

Note

Note

Important

Note