--- title: Email provider description: PingOne Advanced Identity Cloud uses email provider configuration to support email-dependent end-user journeys. For example, registration and password reset end-user journeys usually include an email component. component: pingoneaic page_id: pingoneaic:tenants:email-provider canonical_url: https://docs.pingidentity.com/pingoneaic/tenants/email-provider.html keywords: ["Features", "Journeys", "REST API", "Setup & Configuration", "Tenants", "Users"] page_aliases: ["pingoneaic::email-overview.adoc", "tenants:email-service.adoc", "release-notes:rapid-channel/msgraph-email-rapid.adoc", "release-notes:rapid-channel/international-email.adoc"] section_ids: built-in-smtp-server: Built-in SMTP server external-email-services: External email services international-email: International email addresses configure-an-email-provider-across-your-tenant-environments: Configure an email provider across your tenant environments configure-a-mutable-environment-to-use-an-email-provider: Configure a mutable environment to use an email provider configure-email-ui: Using the admin console configure-email-REST: Using the API sample-email-configuration: Sample email configuration revert-the-email-provider-to-use-the-built-in-smtp-server: Revert the email provider to use the built-in SMTP server --- # Email provider PingOne Advanced Identity Cloud uses *email provider* configuration to support email-dependent end-user [journeys](../journeys/journeys.html). For example, [registration](../journeys/journeys.html#registration) and [password reset](../journeys/journeys.html#reset-password) end-user journeys usually include an email component. By default, Advanced Identity Cloud configures the email provider with default values to connect to a built-in SMTP server. At the start of your onboarding process, this lets you quickly create and test email-dependent journeys using the ready-to-use [email templates](email-templates.html). During your onboarding process, you need to update the email provider configuration to use your own [external email service](#external-email-services) in order to provide robust email delivery to your end users. Email provider configuration changes made in one realm are applied to both realms. ## Built-in SMTP server The built-in SMTP server is preconfigured in Advanced Identity Cloud and enabled by default in your tenant development and sandbox\[[1](#_footnotedef_1 "View footnote.")] environments. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The built-in SMTP server is for testing purposes only and has the following limitations:- Outbound email is rate-limited to 10 messages per minute. - All emails are sent from a standard address in the format `noreply@`, which overrides any sender address set in email templates or API calls. It provides consistent delivery and helps ensure messages are sent securely. - It doesn't support OTP Email Sender nodes in password journeys. - It doesn't support non-ASCII characters in email addresses.In your staging, UAT\[[2](#_footnotedef_2 "View footnote.")], and production tenant environments, you *must* update the email provider configuration to use your own external email provider. | ## External email services Advanced Identity Cloud supports two external email service types: * SMTP * Send emails through your own SMTP server or a third-party email service such as Amazon SES. * Can only be configured in mutable environments: * Use the admin console or API to set literal values for testing. * Use the API to set ESV placeholders to make the configuration compatible with promotion. * Use this configuration type for sending email to [international email addresses](#international-email). * MS Graph API * Send emails using the [MS Graph API `sendMail`](https://learn.microsoft.com/en-us/graph/api/user-sendmail) endpoint. * Can only be configured in mutable environments: * Not configurable using the admin console. * Use the API to set literal values for testing or set ESV placeholders to make the configuration compatible with promotion. ## 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` using the [REST API](#configure-email-REST) or the [UI](#configure-email-ui). Learn more in [`smtpProperties` sub-properties](email-provider-configuration-reference.html#smtp-sub-prop-table). ## Configure an email provider across your tenant environments The high-level process to set up an email provider across your tenant environments is as follows: 1. In your development environment: 1. [Create and test a journey](../journeys/journeys.html) that uses an email node. By default, the email provider uses the built-in SMTP server to test the email node. 2. When you're satisfied with your test results: 1. Configure the email provider configuration to use an SMTP or MS Graph API external email service. Use the instructions in [Configure a mutable environment to use an email provider](#configure-a-mutable-environment-to-use-an-email-provider). 2. Verify that your email templates work with the external email service. 3. When you're satisfied that your external email provider is working correctly: 1. [Insert ESV placeholders into the email provider configuration](configuration-placeholders-api.html#configure-tenant-email-provider) to make it compatible with the promotion process. 2. [Restart Advanced Identity Cloud services](configuration-placeholders.html#restart-identity-cloud-services). 3. Verify that your email templates work with the updated ESV configuration. 2. Determine the promotion order of your tenant environments. This will depend on whether you have a [standard promotion group of environments](self-service-promotions.html#standard-promotion-group-of-environments) or whether you also have [additional UAT environments](self-service-promotions.html#additional-uat-environments). 3. In promotion order, for each of the tenant environments in your promotion group, perform the following steps: 1. Create the same ESVs in the tenant environment as you created in step 1c. Ensure the ESV values are correct for the tenant environment. 2. Run a promotion to move the configuration changes to the tenant environment from its respective lower tenant environment. Learn more in: * [Manage self-service promotions using the admin console](self-service-promotions-ui.html) * [Manage self-service promotions using the API](self-service-promotions-api.html) 4. (Optional) If you have sandbox\[[1](#_footnotedef_1 "View footnote.")] environments, repeat steps 1b and 1c for each sandbox environment. ### Configure a mutable environment to use an email provider In your development or sandbox\[[1](#_footnotedef_1 "View footnote.")] tenant environments, configure the email provider to use your own [external email service](#external-email-services): * For SMTP, you can use the admin console or API. * For MS Graph API, you can only use the API. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | - To understand how the instructions in this section fit into the process of configuring the email provider across your tenant environments, refer to step 1b in the [high-level process](#configure-an-email-provider-across-your-tenant-environments). - For the complete list of API configuration options, learn more in [Email provider configuration reference](email-provider-configuration-reference.html). - For sample API email configurations, learn more in [Sample email configuration](#sample-email-configuration). - For instructions on configuring a Microsoft Azure tenant, learn more in [Configure a Microsoft Azure tenant for MS Graph API email client](email-provider-configure-microsoft-azure-tenant.html). | #### Using the admin console 1. In the Advanced Identity Cloud admin console, go to Email > Provider. 2. On the Email Provider page, enable Use my own email provider. 3. Enter details in the following fields: | | | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | From Address | Email address of the organization or individual sending the email.Example: `mycompany@example.com`. | | From Name | Name of sending organization. | | Host | Hostname or IP address of your SMTP server. | | Port | Port number of your SMTP server.Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.Default value is `587`. | | Username | Username for your SMTP server account. | | Password | Password for your SMTP server account. | 4. Click Show advanced settings, and edit the options and fields: | | | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Socket Connection Timeout (ms) | Elapsed time before Advanced Identity Cloud times out due to unsuccessful socket connection to the SMTP server. A setting of `0` disables this timeout.The default is `300000` ms (5 minutes). | | Socket Write Timeout (ms) | Elapsed time before Advanced Identity Cloud times out because client can't write to the SMTP server. A setting of `0` disables this timeout.The default is `300000` (5 minutes). | | Socket Timeout (ms) | Elapsed time before Advanced Identity Cloud times out due to inactivity. A setting of `0` disables this timeout.The default is `300000` (5 minutes). | | Use STARTTLS | * If enabled, and if the SMTP server supports the STARTTLS command, then Advanced Identity Cloud switches to a TLS-protected connection before issuing any login commands. * If the SMTP server does not support STARTTLS, the connection continues without the use of TLS.Enabled by default. | | Use SSL | If enabled, Advanced Identity Cloud uses SSL to connect to the SMTP server.Disabled by default. | | Allow UTF-8 | If enabled, adds support for UTF-8 (Non-ASCII) characters in the *local* part of email addresses (everything before the `@` character).Disabled by default. Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses. | 5. To test your configuration, click Send Test Email. 1. In the Send Test Email dialog box, enter your own email address. 2. Click Send. If the test is successful, you'll get a test email in your email inbox. 6. To save the email provider configuration, click Save. #### Using the API You can edit the email service over REST at the `openidm/config/external.email` endpoint. The following example submits an email configuration over REST: ``` curl \ --header "Authorization: Bearer " \(1) --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 }' \ "https:///openidm/config/external.email" ``` | | | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1** | Replace \ with an access token that has the `fr:idm:*` scope. Learn more in [Get an access token](https://developer.pingidentity.com/pingoneaic-api/authenticate-to-rest-api-with-access-token.html#get-an-access-token). | #### Sample email configuration This sample email configuration sets up the email provider: * 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", "mail.mime.allowutf8=true" ], "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 } ``` ### Revert the email provider to use the built-in SMTP server If you need to revert the email provider to use the built-in SMTP server: 1. In the Advanced Identity Cloud admin console, go to Email > Provider. 2. On the Email Provider page, disable Use my own email provider. 3. Click Save. | | | | - | ------------------------------------------------------------------------------------------------------------ | | | The built-in SMTP server is for testing purposes only and has the limitations noted at the top of this page. | *** [1](#_footnoteref_1). A [sandbox environment](environments-sandbox.html) is an [add-on capability](../product-information/add-on-capabilities.html).[2](#_footnoteref_2). A [user acceptance testing (UAT) environment](environments-uat.html) is an [add-on capability](../product-information/add-on-capabilities.html).