--- title: Outbound email service description: The outbound email service sends email from IDM using a script or the REST API. component: pingidm version: 8.1 page_id: pingidm:external-services-guide:email canonical_url: https://docs.pingidentity.com/pingidm/8.1/external-services-guide/email.html keywords: ["Email", "Rest", "REST API", "JSON", "Scripts"] 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 secret-rotation-email: Storing MS Azure credentials as a secret external.email.json: Sample email configuration external.email.properties: External email configuration properties section-mail-limiting2: Email rate limiting --- # Outbound email service 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 The outbound email service supports two email service configuration types: * SMTP - Email service that uses the Simple Mail Transfer Protocol. Can be configured using the UI or API. * MS Graph API - Email service that uses the [MS Graph API `sendMail`](https://learn.microsoft.com/en-us/graph/api/user-sendmail) endpoint. Can only be configured using the API. ### 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 * Filesystem ``` 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" ``` ``` cp /path/to/external.email.json /path/to/openidm/conf/ ``` | | | | - | -------------------------- | | | IDM encrypts the password. | ### Storing MS Azure credentials as a secret You can enable zero-downtime rotation of your `clientId` and `clientSecret` credentials by storing those values in a file system based secret store. To configure an existing IDM external email client with an existing MS Azure tenant to use a file system secret store: 1. Add a new secret in the Microsoft Azure portal. For more information, refer to [the Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-client-secret). 2. Create the `idm.email.msgraph.credentials` file in your [file system-based secret store](../security-guide/secret-stores.html). The file must contain a JSON object with your secret values, such as: ```json { "clientId": "myClient", "clientSecret": "mySecret" } ``` 3. Update the `auth` property in `conf/external.email.json` to read the `clientId` and `clientSecret` from the secret file using a purpose. You must set a `jsonPointer` property that identifies the matching field in the secret file: ```json { ... "auth": { "enable": true, "type": "oauth2", "clientId": { "$purpose": { "name" : "idm.email.msgraph.credentials", "jsonPointer" : "clientId" } }, "clientSecret" : { "$purpose" : { "name" : "idm.email.msgraph.credentials", "jsonPointer" : "clientSecret" } }, "tokenEndpoint" : "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token", "scope" : [ "https://graph.microsoft.com/.default" ], "scopeDelimiter" : " ", "grantType" : "client_credentials" } } ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------- | | | If you use a secret that only stores a password, you only need to update the `clientSecret` value in `conf/external.email.json`. | ### 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). To store as a secret, refer to [Storing MS Azure credentials as a secret](#secret-rotation-email). | Yes | | `clientSecret` | clientSecret used to request an access token from the token endpoint. Obtained during [Azure application creation](#note-clientSecret). To store as a secret, refer to [Storing MS Azure credentials as a secret](#secret-rotation-email). | 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. | ## 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.