PingOne Platform APIs

Create Custom Email Provider

 

PUT {{apiPath}}/environments/{{envID}}/notificationsSettings/emailDeliverySettings

This example uses PUT {{apiPath}}/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

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 for full property descriptions.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/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

curl --location --globoff --request PUT '{{apiPath}}/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"
        }
    }]
}'
var options = new RestClientOptions("{{apiPath}}/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);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/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))
}
PUT /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"
        }
    }]
}
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}}/environments/{{envID}}/notificationsSettings/emailDeliverySettings")
  .method("PUT", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/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);
});
var request = require('request');
var options = {
  'method': 'PUT',
  'url': '{{apiPath}}/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);
});
import requests
import json

url = "{{apiPath}}/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
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/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();
}
require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/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
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}}/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

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