--- title: Create Custom Email Provider description: This example uses PUT {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings to create a custom email provider. component: pingone-api page_id: pingone-api:platform:notifications/email-delivery-settings/create_custom_email_provider canonical_url: https://developer.pingidentity.com/pingone-api/platform/notifications/email-delivery-settings/create_custom_email_provider.html section_ids: prerequisites: Prerequisites headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Create Custom Email Provider ## ```none PUT {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings ``` This example uses `PUT {{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings` to create a custom email provider. You can only have a single set of email delivery settings in an environment so when you run such a request, it will replace the existing email delivery settings, whether it be a custom SMTP mail server or an external email service. This example uses `BEARER` as the authentication method, so it includes the `authToken` parameter. If you use basic authentication, set `authentication.method` to `BASIC` and provide values for the `authentication.username` and `authentication.password` parameters. Note that the contents of `requests[].body` are used to construct the body of the API request for the email provider, so you must enclose the JSON object in quotation marks and escape all quotation marks within the string. ### Prerequisites * Refer to [Notifications](../../notifications.html) and [Email Delivery Settings](../email-delivery-settings.html) for important overview information. > **Collapse: Request Model** > > | Property | Type | Required? | > | --------------------------- | ------ | --------- | > | `authentication` | Object | Required | > | `authentication.method` | String | Required | > | `authentication.authToken` | String | Required | > | `from` | Object | Optional | > | `from.name` | String | Optional | > | `from.address` | String | Optional | > | `name` | String | Required | > | `protocol` | String | Required | > | `provider` | String | Required | > | `replyTo` | Object | Optional | > | `replyTo.name` | String | Optional | > | `replyTo.address` | String | Optional | > | `requests` | Array | Required | > | `requests[].body` | String | Required | > | `requests[].deliveryMethod` | String | Required | > | `requests[].headers` | Object | Required | > | `requests[].method` | String | Required | > | `requests[].url` | String | Required | > > Refer to the [Email delivery settings data model](../email-delivery-settings.html) for full property descriptions. ### Headers Authorization      Bearer {{accessToken}} Content-Type      application/json ### Body raw ( application/json ) ```json { "name": "CustomEmailProvider", "provider":"CUSTOM_PROVIDER", "authentication":{ "method":"BEARER", "authToken":"{{accessTokenForEmailProvider}}" }, "from":{ "name":"Example Corporation", "address":"notifications@example.com" }, "replyTo":{ "name":"Example Corporation Replies", "address":"replies@example.com" }, "protocol":"HTTP", "requests":[{ "body":"{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod":"EMAIL", "url":"{{urlForEmailProvider}}", "method":"POST", "headers":{ "content-type":"application/json" } }] } ``` ## ### Example Request * cURL * C# * Go * HTTP * Java * jQuery * NodeJS * Python * PHP * Ruby * Swift ```shell curl --location --globoff --request PUT '{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{accessToken}}' \ --data-raw '{ "name": "CustomEmailProvider", "provider":"CUSTOM_PROVIDER", "authentication":{ "method":"BEARER", "authToken":"{{accessTokenForEmailProvider}}" }, "from":{ "name":"Example Corporation", "address":"notifications@example.com" }, "replyTo":{ "name":"Example Corporation Replies", "address":"replies@example.com" }, "protocol":"HTTP", "requests":[{ "body":"{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod":"EMAIL", "url":"{{urlForEmailProvider}}", "method":"POST", "headers":{ "content-type":"application/json" } }] }' ``` ```csharp var options = new RestClientOptions("{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings") { MaxTimeout = -1, }; var client = new RestClient(options); var request = new RestRequest("", Method.Put); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "Bearer {{accessToken}}"); var body = @"{" + "\n" + @" ""name"": ""CustomEmailProvider""," + "\n" + @" ""provider"":""CUSTOM_PROVIDER""," + "\n" + @" ""authentication"":{" + "\n" + @" ""method"":""BEARER""," + "\n" + @" ""authToken"":""{{accessTokenForEmailProvider}}""" + "\n" + @" }," + "\n" + @" ""from"":{" + "\n" + @" ""name"":""Example Corporation""," + "\n" + @" ""address"":""notifications@example.com""" + "\n" + @" }," + "\n" + @" ""replyTo"":{" + "\n" + @" ""name"":""Example Corporation Replies""," + "\n" + @" ""address"":""replies@example.com""" + "\n" + @" }," + "\n" + @" ""protocol"":""HTTP""," + "\n" + @" ""requests"":[{" + "\n" + @" ""body"":""{\""From\"": \""${from}\"",\""To\"": \""${to}\"",\""message2\"": \""${message}\""}""," + "\n" + @" ""deliveryMethod"":""EMAIL""," + "\n" + @" ""url"":""{{urlForEmailProvider}}""," + "\n" + @" ""method"":""POST""," + "\n" + @" ""headers"":{" + "\n" + @" ""content-type"":""application/json""" + "\n" + @" }" + "\n" + @" }]" + "\n" + @"}" + "\n" + @""; request.AddStringBody(body, DataFormat.Json); RestResponse response = await client.ExecuteAsync(request); Console.WriteLine(response.Content); ``` ```golang package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings" method := "PUT" payload := strings.NewReader(`{ "name": "CustomEmailProvider", "provider":"CUSTOM_PROVIDER", "authentication":{ "method":"BEARER", "authToken":"{{accessTokenForEmailProvider}}" }, "from":{ "name":"Example Corporation", "address":"notifications@example.com" }, "replyTo":{ "name":"Example Corporation Replies", "address":"replies@example.com" }, "protocol":"HTTP", "requests":[{ "body":"{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod":"EMAIL", "url":"{{urlForEmailProvider}}", "method":"POST", "headers":{ "content-type":"application/json" } }] }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("Content-Type", "application/json") req.Header.Add("Authorization", "Bearer {{accessToken}}") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := io.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` ```http PUT /v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings HTTP/1.1 Host: {{apiPath}} Content-Type: application/json Authorization: Bearer {{accessToken}} { "name": "CustomEmailProvider", "provider":"CUSTOM_PROVIDER", "authentication":{ "method":"BEARER", "authToken":"{{accessTokenForEmailProvider}}" }, "from":{ "name":"Example Corporation", "address":"notifications@example.com" }, "replyTo":{ "name":"Example Corporation Replies", "address":"replies@example.com" }, "protocol":"HTTP", "requests":[{ "body":"{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod":"EMAIL", "url":"{{urlForEmailProvider}}", "method":"POST", "headers":{ "content-type":"application/json" } }] } ``` ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"name\": \"CustomEmailProvider\",\n \"provider\":\"CUSTOM_PROVIDER\",\n \"authentication\":{\n \"method\":\"BEARER\",\n \"authToken\":\"{{accessTokenForEmailProvider}}\"\n },\n \"from\":{\n \"name\":\"Example Corporation\",\n \"address\":\"notifications@example.com\"\n },\n \"replyTo\":{\n \"name\":\"Example Corporation Replies\",\n \"address\":\"replies@example.com\"\n },\n \"protocol\":\"HTTP\",\n \"requests\":[{\n \"body\":\"{\\\"From\\\": \\\"${from}\\\",\\\"To\\\": \\\"${to}\\\",\\\"message2\\\": \\\"${message}\\\"}\",\n \"deliveryMethod\":\"EMAIL\",\n \"url\":\"{{urlForEmailProvider}}\",\n \"method\":\"POST\",\n \"headers\":{\n \"content-type\":\"application/json\"\n }\n }]\n}\n"); Request request = new Request.Builder() .url("{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings") .method("PUT", body) .addHeader("Content-Type", "application/json") .addHeader("Authorization", "Bearer {{accessToken}}") .build(); Response response = client.newCall(request).execute(); ``` ```javascript var settings = { "url": "{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings", "method": "PUT", "timeout": 0, "headers": { "Content-Type": "application/json", "Authorization": "Bearer {{accessToken}}" }, "data": JSON.stringify({ "name": "CustomEmailProvider", "provider": "CUSTOM_PROVIDER", "authentication": { "method": "BEARER", "authToken": "{{accessTokenForEmailProvider}}" }, "from": { "name": "Example Corporation", "address": "notifications@example.com" }, "replyTo": { "name": "Example Corporation Replies", "address": "replies@example.com" }, "protocol": "HTTP", "requests": [ { "body": "{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod": "EMAIL", "url": "{{urlForEmailProvider}}", "method": "POST", "headers": { "content-type": "application/json" } } ] }), }; $.ajax(settings).done(function (response) { console.log(response); }); ``` ```javascript var request = require('request'); var options = { 'method': 'PUT', 'url': '{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings', 'headers': { 'Content-Type': 'application/json', 'Authorization': 'Bearer {{accessToken}}' }, body: JSON.stringify({ "name": "CustomEmailProvider", "provider": "CUSTOM_PROVIDER", "authentication": { "method": "BEARER", "authToken": "{{accessTokenForEmailProvider}}" }, "from": { "name": "Example Corporation", "address": "notifications@example.com" }, "replyTo": { "name": "Example Corporation Replies", "address": "replies@example.com" }, "protocol": "HTTP", "requests": [ { "body": "{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod": "EMAIL", "url": "{{urlForEmailProvider}}", "method": "POST", "headers": { "content-type": "application/json" } } ] }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` ```python import requests import json url = "{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings" payload = json.dumps({ "name": "CustomEmailProvider", "provider": "CUSTOM_PROVIDER", "authentication": { "method": "BEARER", "authToken": "{{accessTokenForEmailProvider}}" }, "from": { "name": "Example Corporation", "address": "notifications@example.com" }, "replyTo": { "name": "Example Corporation Replies", "address": "replies@example.com" }, "protocol": "HTTP", "requests": [ { "body": "{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "deliveryMethod": "EMAIL", "url": "{{urlForEmailProvider}}", "method": "POST", "headers": { "content-type": "application/json" } } ] }) headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer {{accessToken}}' } response = requests.request("PUT", url, headers=headers, data=payload) print(response.text) ``` ```php setUrl('{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings'); $request->setMethod(HTTP_Request2::METHOD_PUT); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'Content-Type' => 'application/json', 'Authorization' => 'Bearer {{accessToken}}' )); $request->setBody('{\n "name": "CustomEmailProvider",\n "provider":"CUSTOM_PROVIDER",\n "authentication":{\n "method":"BEARER",\n "authToken":"{{accessTokenForEmailProvider}}"\n },\n "from":{\n "name":"Example Corporation",\n "address":"notifications@example.com"\n },\n "replyTo":{\n "name":"Example Corporation Replies",\n "address":"replies@example.com"\n },\n "protocol":"HTTP",\n "requests":[{\n "body":"{\\"From\\": \\"${from}\\",\\"To\\": \\"${to}\\",\\"message2\\": \\"${message}\\"}",\n "deliveryMethod":"EMAIL",\n "url":"{{urlForEmailProvider}}",\n "method":"POST",\n "headers":{\n "content-type":"application/json"\n }\n }]\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` ```ruby require "uri" require "json" require "net/http" url = URI("{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings") http = Net::HTTP.new(url.host, url.port); request = Net::HTTP::Put.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "Bearer {{accessToken}}" request.body = JSON.dump({ "name": "CustomEmailProvider", "provider": "CUSTOM_PROVIDER", "authentication": { "method": "BEARER", "authToken": "{{accessTokenForEmailProvider}}" }, "from": { "name": "Example Corporation", "address": "notifications@example.com" }, "replyTo": { "name": "Example Corporation Replies", "address": "replies@example.com" }, "protocol": "HTTP", "requests": [ { "body": "{\"From\": \"\${from}\",\"To\": \"\${to}\",\"message2\": \"\${message}\"}", "deliveryMethod": "EMAIL", "url": "{{urlForEmailProvider}}", "method": "POST", "headers": { "content-type": "application/json" } } ] }) response = http.request(request) puts response.read_body ``` ```swift let parameters = "{\n \"name\": \"CustomEmailProvider\",\n \"provider\":\"CUSTOM_PROVIDER\",\n \"authentication\":{\n \"method\":\"BEARER\",\n \"authToken\":\"{{accessTokenForEmailProvider}}\"\n },\n \"from\":{\n \"name\":\"Example Corporation\",\n \"address\":\"notifications@example.com\"\n },\n \"replyTo\":{\n \"name\":\"Example Corporation Replies\",\n \"address\":\"replies@example.com\"\n },\n \"protocol\":\"HTTP\",\n \"requests\":[{\n \"body\":\"{\\\"From\\\": \\\"${from}\\\",\\\"To\\\": \\\"${to}\\\",\\\"message2\\\": \\\"${message}\\\"}\",\n \"deliveryMethod\":\"EMAIL\",\n \"url\":\"{{urlForEmailProvider}}\",\n \"method\":\"POST\",\n \"headers\":{\n \"content-type\":\"application/json\"\n }\n }]\n}" let postData = parameters.data(using: .utf8) var request = URLRequest(url: URL(string: "{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/emailDeliverySettings")!,timeoutInterval: Double.infinity) request.addValue("application/json", forHTTPHeaderField: "Content-Type") request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization") request.httpMethod = "PUT" request.httpBody = postData let task = URLSession.shared.dataTask(with: request) { data, response, error in guard let data = data else { print(String(describing: error)) return } print(String(data: data, encoding: .utf8)!) } task.resume() ``` ### Example Response 200 OK ```json { "_links": { "self": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/notificationsSettings/emailDeliverySettings" }, "environment": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" } }, "replyTo": { "name": "Example Corporation Replies", "address": "replies@example.com" }, "environment": { "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "updatedAt": "2024-09-22T11:41:44.733Z", "protocol": "HTTP", "from": { "name": "Example Corporation", "address": "notifications@example.com" }, "name": "CustomEmailProvider", "authentication": { "method": "BEARER" }, "requests": [ { "deliveryMethod": "EMAIL", "url": "https://api.sendgrid.com/v3/mail/send", "method": "POST", "body": "{\"From\": \"${from}\",\"To\": \"${to}\",\"message2\": \"${message}\"}", "headers": { "content-type": "application/json" } } ] } ```