--- title: Send email description: Typically, PingOne Advanced Identity Cloud sends emails from journeys, scripts, or other backend processes. You can also send test emails using the REST API. component: pingoneaic page_id: pingoneaic:tenants:email-send canonical_url: https://docs.pingidentity.com/pingoneaic/tenants/email-send.html keywords: ["Features", "Journeys", "REST API", "Scripts", "Tenants", "Users"] section_ids: email-send-email: Send email without a template email-send-email-api: Send emails using the API email-send-email-script: Send emails using a script email-templates-send: Send email templates email-templates-send-api: Send email templates using the API email-templates-send-script: Send email templates using a script email-send-post-params: external/email POST parameters --- # 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 " \ --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:///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 " \ --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:///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](../idm-scripting/scripting-func-engine.html#function-action). In the following example, `params` is an object that contains the [POST parameters](#email-send-post-params): ```javascript 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": "

Recon report follows...

" }; openidm.action("external/email", "send", params); ``` ## Send email templates For consistent, branded, and localized communications, send an [email template](email-templates.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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`:```none https:///?realm=alpha#/email/templates/edit/forgottenUsername ``` | ### Send email templates using the API You can send an [email template](email-templates.html) using the `sendTemplate` action. The following example sends the `welcome` email template: ``` curl \ --header "Authorization: Bearer " \ --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:///openidm/external/email?_action=sendTemplate" { "status": "OK", "message": "Email sent" } ``` ### Send email templates using a script You can send an [email template](email-templates.html) from a script using the [openidm.action](../idm-scripting/scripting-func-engine.html#function-action) function with the `external/email` context and the `sendTemplate` action. Example 1: Send a basic template ```javascript 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 ```javascript 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 ```javascript 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](https://handlebarsjs.com/guide/) to reference object data dynamically. For example, to use the data from Example 3, you would add the following to your `myCustomEmail` template:```html

Here is your special offer!

Use promo code {{object.promoCode}} before {{object.expiryDate}}.

``` | ## `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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)). * `type` Optional MIME type. One of `"text/plain"`, `"text/html"`, or `"text/xml"`.