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? |
|---|---|---|
|
String |
Required |
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}}"
}
}