--- title: Outbound email description: Configure the PingIDM outbound email service using SMTP or MS Graph API, and send email using the REST API or scripts component: pingidm version: 7.5 page_id: pingidm:external-services-guide:email canonical_url: https://docs.pingidentity.com/pingidm/8.1/external-services-guide/email.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Email", "Rest", "REST API", "JSON", "Scripts"] superseded_by: https://docs.pingidentity.com/pingidm/8.1/external-services-guide/email.html section_ids: email-service-types: Email service configuration types international-email-address: International email addresses ms_graph_api_requirements: MS Graph API requirements configure_azure_for_ms_graph_api_mail_client: Configure Azure for MS Graph API mail client configure_outbound_email: Configure outbound email external.email.json: Sample email configuration external.email.properties: External email configuration properties send-mail-rest: Send mail 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-limiting: Email rate limiting --- # Outbound email The outbound email service sends email from IDM using a script or the REST API. You can edit the email service over REST at the `config/external.email` endpoint, or in the `external.email.json` file in your project's `conf` directory. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | IDM supports UTF-8 (non-ASCII/international) characters in email addresses, such as **zoë@example.com**. When sending emails to these type of addresses, the configured SMTP server must also support UTF-8. | ## Email service configuration types IDM supports two email service configuration types: * SMTP - Email service that uses the Simple Mail Transfer Protocol. * MS Graph API - Email service that uses the [MS Graph API `sendMail`](https://learn.microsoft.com/en-us/graph/api/user-sendmail) endpoint. ### International email addresses To use [international email addresses](https://en.wikipedia.org/wiki/International_email), you must: * Use SMTP as the provider type. * The SMTP provider must support international email addresses. * Configure `mail.mime.allowutf8=true`, which is only available using the REST API or the filesystem. For more information, refer to [`smtpProperties` sub-properties](#smtp-sub-prop-table). ## MS Graph API requirements Use of the MS Graph API email client requires a properly configured Microsoft Azure tenant. The basic steps for configuring an Azure tenant should be used as an outline, as the specific options, menus, and features may have changed. Microsoft Sandbox If you need a sandbox for *testing only*, check out the [Microsoft developer sandbox subscription](https://learn.microsoft.com/en-us/office/developer-program/microsoft-365-developer-program-get-started). Although the sandbox accepts `sendMail` requests, the Microsoft Exchange service prevents messages from being delivered. The messages do show up in the sender's "sent" box, which should be sufficient for manual testing purposes. ### Configure Azure for MS Graph API mail client 1. Navigate to [Azure Active Directory | App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps). 2. Create the IDM client application: 1. From the menu bar, click + New Registration. 2. On the Register an application page, enter the application Name, such as `idm-email-client`. 3. For Supported account types, select the applicable option for your organization. 4. Click Register. 5. On the idm-email-client page, in the main Essentials area, record the Application (client) ID. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This is the value for `clientId` in the `auth` settings of the email configuration *(tooltip: You can edit the email service over REST at the config/external.email endpoint, or in the external.email.json file in your project's conf directory.)*. Refer to [`oauth2` properties](#oath2-table). | 3. Add a client secret: 1. On the idm-email-client page, in the main Essentials area, click Add a certificate or secret. > **Collapse: Show Me** > > ![Azure app - add a secret link](_images/azureAppAddSecretLink.png) 2. On the Certificates & secrets page, select the Client secrets tab, and click + New client secret. > **Collapse: Show Me** > > ![Azure app - add a new client secret](_images/azureNewClientSecret.png) 3. In the Add a client secret window, enter the details, and click Add. 4. Copy the Value and Secret ID to a secure place *before* leaving the Certificates & secrets page. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Use the secret Value for `clientSecret` in the `auth` settings of the email configuration *(tooltip: You can edit the email service over REST at the config/external.email endpoint, or in the external.email.json file in your project's conf directory.)*. Refer to [`oauth2` properties](#oath2-table). | 4. Add API permissions: 1. From the side menu, click API permissions. 2. On the API permissions page, click + Add a permission. 3. In the Request API permissions windows, select the Microsft APIs tab, and click Microsoft Graph. 4. In the What type of permissions... area, click Application permissions. 5. In the Select permissions search bar, type `send`. 6. Expand the Mail node, and select Mail.Send. 7. Click Add permissions. > **Collapse: Show Me** > > ![Azure app - Request API permissions](_images/azureRequestAPIPermissions.png) ## Configure outbound email To configure the outbound email service using the admin UI, click Configure > Email Settings. 1. Edit the email configuration *(tooltip: You can edit the email service over REST at the config/external.email endpoint, or in the external.email.json file in your project's conf directory.)* with the mail server details and account. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * For the complete list of configuration options, refer to [External email configuration properties](#external.email.properties). * For sample email configurations, refer to [Sample email configuration](#external.email.json). | 2. Submit the configuration over REST or copy the file to your project's `conf/` directory. For example: REST ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "host" : "smtp.gmail.com", "port" : 587, "debug" : false, "auth" : { "enable" : true, "username" : "admin", "password" : "Passw0rd" }, "from" : "admin@example.com", "timeout" : 300000, "writetimeout" : 300000, "connectiontimeout" : 300000, "starttls" : { "enable" : true }, "ssl" : { "enable" : false }, "smtpProperties" : [ "mail.smtp.ssl.protocols=TLSv1.2", "mail.smtps.ssl.protocols=TLSv1.2", "mail.mime.allowutf8=true" ], "threadPoolSize" : 20 }' \ "http://localhost:8080/openidm/config/external.email" ``` Filesystem ``` cp /path/to/external.email.json /path/to/openidm/conf/ ``` | | | | - | -------------------------- | | | IDM encrypts the password. | ### Sample email configuration This sample email configuration *(tooltip: You can edit the email service over REST at the config/external.email endpoint, or in the external.email.json file in your project's conf directory.)* sets up the outbound email service: * SMTP * MS Graph API ```json { "host" : "smtp.gmail.com", "port" : 587, "debug" : false, "auth" : { "enable" : true, "username" : "xxxxxxxx", "password" : "xxxxxxxx" }, "timeout" : 300000, "writetimeout" : 300000, "connectiontimeout" : 300000, "starttls" : { "enable" : true }, "ssl" : { "enable" : false }, "smtpProperties" : [ "mail.smtp.ssl.protocols=TLSv1.2", "mail.smtps.ssl.protocols=TLSv1.2" ], "threadPoolSize" : 20 } ``` ```json { "type" : "msgraph", "mailEndpoint" : "https://graph.microsoft.com/v1.0/users/example@myTenant.onmicrosoft.com/sendMail", "from" : "example@myTenant.onmicrosoft.com", "auth" : { "enable" : true, "type" : "oauth2", "clientId" : "clientId", "clientSecret" : "clientSecret", "tokenEndpoint" : "https://login.microsoftonline.com/myTenant.onmicrosoft.com/oauth2/v2.0/token", "scope" : [ "https://graph.microsoft.com/.default" ] }, "timeout" : 300000, "writetimeout" : 300000, "connectiontimeout" : 300000, "threadPoolSize" : 20 } ``` ### External email configuration properties The `msgraph` type also supports the [External REST configuration properties](external-rest.html#external.rest.properties). **Properties** | Property | Description | Required? / Type Support | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `type` | The [email service type](#email-service-types), `smtp` or `msgraph`. When no type is specified, the default value is `smtp`. | No | | `mailEndpoint` | The URI for the MS Graph API `sendMail` endpoint.Typical format:```none https://graph.microsoft.com/v1.0/users/{user}@{tenant}.onmicrosoft.com/sendMail ``` | YesOnly for `msgraph` type. | | `host` | The host name or IP address of the SMTP server. This can be the `localhost`, if the mail server is on the same system as IDM. | YesOnly for `smtp` type. | | `port` | SMTP server port number, such as 25, 465, or 587. Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam. | YesOnly for `smtp` type. | | `debug` | When set to `true`, this option outputs diagnostic messages from the JavaMail library. Debug mode can be useful if you are having difficulty configuring the external email endpoint with your mail server. | NoOnly for `smtp` type. | | `from` | Specifies a default From: address which displays when users receive emails from IDM. Although from is optional in the email configuration, the email service requires this property to send email. If you do not specify a from address in the email configuration, you must provide one in another way, for example: From an email template. As a parameter in the email service request (from or \_from). | No | | `auth` | Contains authentication detail sub-properties. Refer to the [authentication sub-properties table](#auth-sub-prop-table) for all options. | YesRequired sub-properties vary based on `type`. | | `starttls` | If `"enable" : true`, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS. | NoOnly for `smtp` type. | | `ssl` | Set `"enable" : true` to use SSL to connect, and use the SSL port by default. | NoOnly for `smtp` type. | | `smtpProperties` | SMTP options. Refer to the [SMTP sub-properties table](#smtp-sub-prop-table) for all options. | NoOnly for `smtp` type. | | `threadPoolSize` | Emails are sent in separate threads managed by a thread pool. This property sets the number of concurrent emails that can be handled at a specific time. The default thread pool size (if none is specified) is `20`. | No | | `connectiontimeout` | The socket connection timeout, in milliseconds. The default connection timeout (if none is specified) is `300000` milliseconds, or 5 minutes. A setting of 0 disables this timeout. | No | | `timeout` | The socket read timeout, in milliseconds. The default read timeout (if none is specified) is `300000` milliseconds, or 5 minutes. A setting of 0 disables this timeout. | NoOnly for `smtp` type. | | `writetimeout` | The socket write timeout, in milliseconds. The default write timeout (if none is specified) is `300000` milliseconds, or 5 minutes. A setting of 0 disables this timeout. | NoOnly for `smtp` type. | **auth sub-properties** | Property | Description | Required? / Type Support | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `enable` | Whether you need login credentials to connect to the server/API. If "enable" : false,, you can leave the entries for "username" and "password" empty: "enable" : false, "username" : "", "password" : "" | Yes | | `username` | Account used to connect to the server/API. | No | | `password` | Password used to connect to the server/API. | No | | `type` | Authentication type used to connect to the server/API:- `basic`—basic authentication using a username and password. Default value. - `oauth2`—OAuth2 authentication. Requires additional `oauth2` properties. The `msgraph` configuration type only supports `oauth2`. | Yes | | `oauth2` propertiesThe following properties are only applicable when the `auth/type` is `oauth2`: | | | | `clientId` | *clientId* used to request an access token from the token endpoint. Obtained during [Azure application creation](#note-clientId). | Yes | | `clientSecret` | clientSecret used to request an access token from the token endpoint. Obtained during [Azure application creation](#note-clientSecret). | Yes | | `tokenEndpoint` | OAuth2 token endpoint.Typical format:```none https://login.microsoftonline.com/{tenant}.onmicrosoft.com/oauth2/v2.0/token ``` | Yes | | `scope` | Requested OAuth2 scopes in a JSON array of strings. | Yes | | `scopeDelimiter` | Scope delimiter to use. Defaults to space. | No | | `grantType` | The only supported grant type is `client_credentials`. | No | **smtpProperties sub-properties** | Property | Description | Required? / Type Support | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `mail.smtp.ssl.protocols` | The enabled SMTP SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2. | NoOnly for `smtp` type. | | `mail.smtps.ssl.protocols` | The enabled SMTPS SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2. | NoOnly for `smtp` type. | | `mail.mime.allowutf8` | Adds support for UTF8 (Non-ASCII) characters in the *local* part of email addresses (everything before the `@` character) if set to `true`. Do not set this property unless your SMTP provider supports UTF8 characters. Can only be configured using REST or the filesystem. | NoOnly for `smtp` type. | ## Send mail 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`. You 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 returned only 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"}' \ "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. For more information about these functions, refer to [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 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"; 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 * `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.