PingIDM 8.0.0

Send email

Typically, IDM sends emails from scripts and backend processes. Additionally, you can send test emails using the REST API.

Send email using 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. 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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "from": "openidm@example.com",
  "to": "your_email@example.com",
  "subject": "Test",
  "body": "Test"
}' \
"http://localhost:8080/openidm/external/email?_action=send"
{
  "status": "OK",
  "message": "Email sent"
}

By default, a response is only returned 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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "from": "openidm@example.com",
  "to": "your_email@example.com",
  "subject": "Test",
  "body": "Test"
}' \
"http://localhost:8080/openidm/external/email?_action=send&waitForCompletion=false"
{
  "status": "OK",
  "message": "Email submitted"
}

Mail templates

You can send an email template using the sendTemplate action. For example:

curl \
--header "Content-Type: application/json" \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "templateName": "welcome",
  "to": "your_email@example.com",
  "cc": "alt_email@example.com",
  "bcc": "bigBoss_email@example.com",
  "_locale": "fr"
}' \
"http://localhost:8080/openidm/external/email?_action=sendTemplate"
{
  "status": "OK",
  "message": "Email sent"
}

Email templates utilize Handlebar expressions to reference object data dynamically. For example, to reference the userName of an object:

{{object.userName}}

Send mail using a script

You can send email using the resource API functions, with the external/email context. Learn more about these functions in openidm.action. 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);

Mail templates

You can send an email template using the sendTemplate action. For example:

Example 1
var params =  new Object();
params.templateName = "welcome";
params.to = "your_email@example.com";
params.cc = "bjensen@example.com,scarter@example.com";
params.bcc = "bigBoss@example.com";
params._locale = "fr";

openidm.action("external/email", "sendTemplate", params);
Example 2
var params = new Object();
params.templateName = "myTemplate";
params.to = "hgale815@example.com";
params.object = { "givenName": newObject.givenName, "sn": newObject.sn, "mail": newObject.mail, "country": newObject.country };

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

Email templates utilize Handlebar expressions to reference object data dynamically. For example, to reference the userName of an object:

{{object.userName}}

external/email POST parameters

IDM 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

_locale

Takes precedence over defaultLocale but not preferredLocales specified in the Accept-Language header. If no preferred locales are set, uses the specified locale (ISO 639-1 language codes).

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 IDM 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 IDM 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.