Configure Outbound Email

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

You can edit the email service over REST at the config/external.email endpoint.

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
}
  1. 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 Identity Cloud.

    port

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

    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.

      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 emails from Identity Cloud.

    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.

  2. Submit the configuration over REST, for example:

    curl \
    --header "Authorization: Bearer *token*" \
    --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
    }' \
    "https://tenant-name.forgeblocks.com/openidm/config/external.email"
    Identity Cloud encrypts the password.

Send Mail Over REST

In a production environment, you typically send mail from a script. To test your configuration, you can use the REST API by sending an HTTP POST to /openidm/external/email. You pass the message parameters as part of the POST payload, URL encoding the content, as necessary.

The following example sends a test email using the REST API:

curl \
--header "Content-Type: application/json" \
--header "Authorization: Bearer *token*" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "from":"openidm@example.com",
  "to":"your_email@example.com",
  "subject":"Test",
  "body":"Test"}' \
"https://tenant-name.forgeblocks.com/openidm/external/email?_action=send"
{
  "status": "OK",
  "message": "Email sent"
}

By default, a response is returned only when the SMTP relay has completed. To return a response immediately, without waiting for the SMTP relay to finish, include the parameter waitForCompletion=false in the REST call. Use this option only if you do not need to verify that the email was accepted by the SMTP server. For example:

curl \
--header "Content-Type: application/json" \
--header "Authorization: Bearer *token*" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "from":"openidm@example.com",
  "to":"your_email@example.com",
  "subject":"Test",
  "body":"Test"}' \
"https://tenant-name.forgeblocks.com/openidm/external/email?_action=send&waitForCompletion=false"
{
  "status": "OK",
  "message": "Email submitted"
}

Send Mail From a Script

You can send email by using the resource API functions, with the external/email context. For more information about these functions, see Scripting Function Reference. In the following example, params is an object that contains the POST parameters:

var params =  new Object();
params.from = "openidm@example.com";
params.to = "your_email@example.com";
params.cc = "bjensen@example.com,scarter@example.com";
params.subject = "OpenIDM recon report";
params.type = "text/html";
params.body = "<html><body><p>Recon report follows...</p></body></html>";

openidm.action("external/email", "send", params);

Identity Cloud supports the following POST parameters.

from

Sender mail address

to

Comma-separated list of recipient mail addresses

cc

Optional comma-separated list of copy recipient mail addresses

bcc

Optional comma-separated list of blind copy recipient mail addresses

subject

Email subject

body

Email body text

type

Optional MIME type. One of "text/plain", "text/html", or "text/xml".

Email Rate Limiting

No rate limiting is applied to password reset emails, or any emails sent by the Identity Cloud server. This means that an attacker can potentially spam a known user account with an infinite number of emails, filling that user’s inbox. In the case of password reset, the spam attack can obscure an actual password reset attempt.

In a production environment, you must configure email rate limiting through the network infrastructure in which Identity Cloud runs. Configure the network infrastructure to detect and prevent frequent repeated requests to publicly accessible web pages, such as the password reset page. You can also handle rate limiting within your email server.