Chapter 17. Sending Email
Prev		Next

Chapter 17. Sending Email

Table of Contents

17.1. Sending Mail Over REST
17.2. Sending Mail From a Script

This chapter shows you how to configure the outbound email service, so that you can send email through OpenIDM either by script or through the REST API.

Procedure 17.1. To Set Up Outbound Email

The outbound email service relies on a configuration object to identify the email account used to send messages.

Shut down OpenIDM.

Copy the sample configuration to openidm/conf.

$ cd /path/to/openidm/
$ cp samples/misc/external.email.json conf/

Edit external.email.json to reflect the account used to send messages.
```
{
        "host" : "smtp.example.com",
        "port" : "25",
        "username" : "openidm",
        "password" : "secret12",
        "mail.smtp.auth" : "true",
        "mail.smtp.starttls.enable" : "true"
}
```
OpenIDM encrypts the password you provide.
Follow these hints when editing the configuration.
"host"
SMTP server host name or IP address. This can be "localhost" if the server is on the same system as OpenIDM.
"port"
SMTP server port number such as 25, or 587
"username"
Mail account user name needed when "mail.smtp.auth" : "true"
"password"
Mail account user password needed when "mail.smtp.auth" : "true"
"mail.smtp.auth"
If "true", use SMTP authentication
"mail.smtp.starttls.enable"
If "true", use TLS
"from"
Optional default From: address
Start up OpenIDM.

Check that the email service is active.

-> scr list
...
[   6] [active       ] org.forgerock.openidm.external.email
...

17.1. Sending Mail Over REST

Although you are more likely to send mail from a script in production, you can send email using the REST API by sending an HTTP POST to /openidm/external/email in order to test that your configuration works. You pass the message parameters as POST parameters, URL encoding the content as necessary.

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

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 "http://localhost:8080/openidm/external/email?
 _from=openidm@example.com&_to=admin@example.com&
 _subject=Test&_body=Test"

17.2. Sending Mail From a Script

You can send email from using the resource API functions with the external/email context, as in the following example, where params is an object containing the POST parameters.

var params =  new Object();
params._from = "openidm@example.com";
params._to = "admin@example.com";
params._cc = "wally@example.com,dilbert@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", params);

OpenIDM 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".

Prev		Next
Chapter 16. Using Audit Logs	Home	Chapter 18. OpenIDM Project Best Practices