PingOne Platform APIs

Create MAIL FROM Domain

 

PUT {{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain

This example uses PUT {{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain to create a MAIL FROM domain for a trusted email domain that you have configured. Specifying a MAIL FROM domain results in SPF alignment with the FROM header, reducing the chances that the DMARC check will fail. This reduces the likelihood of PingOne notifications getting flagged as spam when you are using Ping Identity as the notification sender.

There is only one parameter that you must provide - the full name to use for the MAIL FROM domain, for example, p1notifications.example.com.

Note that the request will fail if you have not added the required TXT records for the trusted email domain to your DNS records.

After sending the PUT request, you must send a GET request to retrieve the MX record that you have to add to your DNS records in order to use the feature. The SPF record is also modified so you must also send a GET request with the {{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/spf endpoint to obtain the updated SPF record to put in your DNS.

If you want to change to a different subdomain for the MAIL FROM domain, just run the PUT request a second time, providing the new full domain as a parameter. After updating the name, you’ll again have to send a GET request to retrieve the MX record to add to your DNS and a GET request with the {{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/spf endpoint to obtain the updated SPF record to put in your DNS.

Prerequisites

Refer to Notifications and Trusted Email Domains for important overview information.

Request Model

Refer to the MAIL FROM domain data model for full property descriptions.

Property Type Required?

mailFrom.domain

String

Required

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
   "mailFrom": {
      "domain": "{{mailFromSubdomain}}"
   }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff --request PUT '{{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
   "mailFrom": {
      "domain": "{{mailFromSubdomain}}"
   }
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain")
{
  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" +
@"   ""mailFrom"": {" + "\n" +
@"      ""domain"": ""{{mailFromSubdomain}}""" + "\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}}/emailDomains/{{emailDomainID}}/mailFromDomain"
  method := "PUT"

  payload := strings.NewReader(`{
   "mailFrom": {
      "domain": "{{mailFromSubdomain}}"
   }
}`)

  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}}/emailDomains/{{emailDomainID}}/mailFromDomain HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
   "mailFrom": {
      "domain": "{{mailFromSubdomain}}"
   }
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{  \n   \"mailFrom\": {\n      \"domain\": \"{{mailFromSubdomain}}\"\n   }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain")
  .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}}/emailDomains/{{emailDomainID}}/mailFromDomain",
  "method": "PUT",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "mailFrom": {
      "domain": "{{mailFromSubdomain}}"
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'PUT',
  'url': '{{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "mailFrom": {
      "domain": "{{mailFromSubdomain}}"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain"

payload = json.dumps({
  "mailFrom": {
    "domain": "{{mailFromSubdomain}}"
  }
})
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}}/emailDomains/{{emailDomainID}}/mailFromDomain');
$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   "mailFrom": {\n      "domain": "{{mailFromSubdomain}}"\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}}/emailDomains/{{emailDomainID}}/mailFromDomain")

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({
  "mailFrom": {
    "domain": "{{mailFromSubdomain}}"
  }
})

response = http.request(request)
puts response.read_body
let parameters = "{  \n   \"mailFrom\": {\n      \"domain\": \"{{mailFromSubdomain}}\"\n   }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/emailDomains/{{emailDomainID}}/mailFromDomain")!,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.eu/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/emailDomains/4357ee3b-8e2e-4b67-8596-d4481e689024/mailFromDomain"
        },
        "environment": {
            "href": "https://api.pingone.eu/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "emailDomain": {
            "href": "https://api.pingone.eu/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/emailDomains/4357ee3b-8e2e-4b67-8596-d4481e689024"
        }
    },
    "mailFrom": {
        "domain": "{{mailFromSubdomain}}"
    }
}