PingOne Advanced Identity Cloud

Manage email providers using the API

You can configure a custom SMTP or Microsoft Graph email provider over REST by making a PUT request to the openidm/config/external.email endpoint.

Learn more about email providers in Email provider.

Configure an email provider using the API

The following example submits an email configuration over REST:

$ curl \
--header "Authorization: Bearer <access-token>" \(1)
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '<email-provider-configuration>' \(2)
"https://<tenant-env-fqdn>/openidm/config/external.email"
1 Replace <access-token> with an access token that has the fr:idm:* scope. Learn more in Get an access token.
2 Replace <email-provider-configuration> with your email provider JSON payload. Find information on the required properties based on your provider type in Sample email provider configuration. For a complete list of supported properties, learn more in Email provider configuration reference.

Sample email provider configuration

This sample email configuration sets up the email provider.

The following examples use static values, which are suitable for testing in development or sandbox environments.

To make your configuration compatible with environment promotion, replace literal values with ESV placeholders. Learn more in Insert ESV placeholders into tenant email provider configuration.

  • SMTP

  • Microsoft Graph

{
    "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
}

Prerequisite: To use the Microsoft Graph email provider, you must first configure a Microsoft Azure tenant for the Microsoft Graph email provider to obtain your client ID and client secret.

{
    "_id": "external.email",
    "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"
        ],
        "scopeDelimiter": " ",
        "grantType": "client_credentials"
    },
    "connectiontimeout": 300000,
    "threadPoolSize": 20
}