---
title: Manage email providers using the API
description: Configure email provider settings though the REST API
component: pingoneaic
page_id: pingoneaic:tenants:email-provider-api
canonical_url: https://docs.pingidentity.com/pingoneaic/tenants/email-provider-api.html
llms_txt: https://docs.pingidentity.com/pingoneaic/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
section_ids:
  configure-email-api: Configure an email provider using the API
  sample-email-configuration: Sample email provider configuration
---

# 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](email-provider.html).

## 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](https://developer.pingidentity.com/pingoneaic-api/authenticate-to-rest-api-with-access-token.html#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](#sample-email-configuration). For a complete list of supported properties, learn more in [Email provider configuration reference](email-provider-configuration-reference.html). |

### 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](esvs.html) placeholders. Learn more in [Insert ESV placeholders into tenant email provider configuration](configuration-placeholders-api.html#configure-tenant-email-provider). |

* SMTP

* Microsoft Graph

```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
}
```

**Prerequisite:** To use the Microsoft Graph email provider, you must first [configure a Microsoft Azure tenant for the Microsoft Graph email provider](email-provider-configure-microsoft-azure-tenant.html) to obtain your client ID and client secret.

```json
{
    "_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
}
```