Send email

Typically, PingOne Advanced Identity Cloud sends emails from journeys, scripts, or other backend processes. You can also send test emails using the REST API.

Send email without a template

You can send a simple, raw email for basic notifications that don’t require a template.

Send emails using the API

To test your configuration, use the REST API, 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 "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--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-env-fqdn>/openidm/external/email?_action=send"
{
  "status": "OK",
  "message": "Email sent"
}

By default, a response is returned only when the email relay has completed. To return a response immediately, without waiting for the email 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 "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--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-env-fqdn>/openidm/external/email?_action=send&waitForCompletion=false"
{
  "status": "OK",
  "message": "Email submitted"
}

Send emails 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 = {
    "from": "openidm@example.com",
    "to": "your_email@example.com",
    "cc": "bjensen@example.com,scarter@example.com",
    "subject": "OpenIDM recon report",
    "type": "text/html",
    "body": "<html><body><p>Recon report follows...</p></body></html>"
};
openidm.action("external/email", "send", params);

Send email templates

For consistent, branded, and localized communications, send an email template.

When sending an email template, you must use the templateName parameter. The value for this parameter is the template’s unique ID, which is generated from the template’s original name and converted to camelCase. This ID is immutable, meaning it won’t change even if you rename the template later.

You can find the template ID in the Advanced Identity Cloud admin console URL when editing the template. For example, the template ID for the Forgotten Username template is forgottenUsername:

https://<tenant-env-fqdn>/?realm=alpha#/email/templates/edit/forgottenUsername

Send email templates using the API

You can send an email template using the sendTemplate action.

The following example sends the welcome email template:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--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",
  "object": {
    "givenName": "Barbara",
    "sn": "Jensen"
  },
  "_locale": "fr"
}' \
"https://<tenant-env-fqdn>/openidm/external/email?_action=sendTemplate"
{
  "status": "OK",
  "message": "Email sent"
}

Send email templates using a script

You can send an email template from a script using the openidm.action function with the external/email context and the sendTemplate action.

Example 1: Send a basic template

var params = {
    "templateName": "welcome",
    "to": "your_email@example.com",
    "cc": "bjensen@example.com,scarter@example.com",
    "bcc": "bigBoss@example.com",
    "_locale": "fr"
};
openidm.action("external/email", "sendTemplate", params);

Example 2: Send user profile data

var params = {
    templateName: "myTemplate",
    to: "hgale815@example.com",
    cc: "bjensen@example.com,scarter@example.com",
    bcc: "bigBoss@example.com",
    object: {"givenName": newObject.givenName, "sn": newObject.sn, "mail": newObject.mail, "country": newObject.country},
    _locale: "fr"
};
openidm.action("external/email", "sendTemplate", params);

Example 3: Send a custom data object

var params = {
   templateName: "myCustomEmail",
   to: user.mail,
   object: {
        "promoCode": "SAVE26",
        "expiryDate": "2026-01-30"
       }
};
openidm.action("external/email", "sendTemplate", params);

Email templates use Handlebars expressions to reference object data dynamically. For example, to use the data from Example 3, you would add the following to your myCustomEmail template:

<p>Here is your special offer!</p>
<p>Use promo code <b>{{object.promoCode}}</b> before {{object.expiryDate}}.</p>

`external/email` POST parameters

Advanced 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
_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".

PingOne Advanced Identity Cloud