--- title: Send email description: Typically, IDM sends emails from scripts and backend processes. Additionally, you can send test emails using the REST API. component: pingidm version: 8.1 page_id: pingidm:external-services-guide:email-send canonical_url: https://docs.pingidentity.com/pingidm/8.1/external-services-guide/email-send.html section_ids: send-mail-rest: Send email using REST mail_templates: Mail templates send-mail-script: Send mail using a script mail_templates_2: Mail templates externalemail_post_parameters: external/email POST parameters section-mail-limiting1: Email rate limiting --- # 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](email-templates.html) 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](https://handlebarsjs.com/guide/) to reference object data dynamically. For example, to reference the `userName` of an object:```html {{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](../scripting-guide/scripting-func-ref.html#function-action). In the following example, `params` is an object that contains the POST parameters: ```javascript 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 = "

Recon report follows...

"; openidm.action("external/email", "send", params); ``` ### Mail templates You can send an [email template](email-templates.html) using the `sendTemplate` action. For example: Example 1 ```javascript 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 ```javascript 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](https://handlebarsjs.com/guide/) to reference object data dynamically. For example, to reference the `userName` of an object:```html {{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](https://en.wikipedia.org/wiki/List_of_ISO_639_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.