curl --request PATCH \
--url https://api.openmail.sh/v1/domains/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"podId": "<string>"
}
'import requests
url = "https://api.openmail.sh/v1/domains/{id}"
payload = { "podId": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({podId: '<string>'})
};
fetch('https://api.openmail.sh/v1/domains/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.openmail.sh/v1/domains/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'podId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.openmail.sh/v1/domains/{id}"
payload := strings.NewReader("{\n \"podId\": \"<string>\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.openmail.sh/v1/domains/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"podId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openmail.sh/v1/domains/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"podId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"domain": "<string>",
"podId": "<string>",
"status": "pending",
"records": [
{
"type": "TXT",
"name": "<string>",
"value": "<string>",
"priority": 123,
"purpose": "spf",
"status": "missing"
}
],
"warnings": [
{
"code": "competing_mx",
"message": "<string>",
"hosts": [
"<string>"
]
}
],
"verifiedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Change custom domain pod scope
Change which pods can create inboxes on a custom domain. Pass podId: null to make it account-wide (always allowed), or a pod id to scope it to that pod — allowed only while every inbox on the domain already lives in that pod, since inboxes cannot move between pods. DNS records and verification are untouched. Requires an account-wide API key.
curl --request PATCH \
--url https://api.openmail.sh/v1/domains/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"podId": "<string>"
}
'import requests
url = "https://api.openmail.sh/v1/domains/{id}"
payload = { "podId": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({podId: '<string>'})
};
fetch('https://api.openmail.sh/v1/domains/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.openmail.sh/v1/domains/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'podId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.openmail.sh/v1/domains/{id}"
payload := strings.NewReader("{\n \"podId\": \"<string>\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.openmail.sh/v1/domains/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"podId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openmail.sh/v1/domains/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"podId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"domain": "<string>",
"podId": "<string>",
"status": "pending",
"records": [
{
"type": "TXT",
"name": "<string>",
"value": "<string>",
"priority": 123,
"purpose": "spf",
"status": "missing"
}
],
"warnings": [
{
"code": "competing_mx",
"message": "<string>",
"hosts": [
"<string>"
]
}
],
"verifiedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
Pod to scope the domain to (id or clientId). null makes the domain available to all pods.
Response
Scope changed; the returned domain reflects the new podId
Scope changed; the returned domain reflects the new podId
OpenMail domain ID
The domain or subdomain, e.g. example.com or agent-mail.example.com.
Pod this domain is scoped to, so only inboxes in that pod can use it, or null for an account-wide domain.
pending — added, records not yet published. verifying — being checked. verified — sending and receiving enabled. failed — records missing or wrong; publishing them and calling verify again is the fix. under_review — flagged as suspicious; DNS setup is blocked until approved.
pending, verifying, verified, failed, under_review The DNS records to publish for this domain. Returned even where the values are the same for every customer, so sending infrastructure can change without breaking clients.
Show child attributes
Show child attributes
Problems detected in the domain's DNS that do not block verification but do lose mail. Empty when none. Check this even when status is verified — every record can be correct and the zone still broken by something else in it.
Show child attributes
Show child attributes
Was this page helpful?