curl --request POST \
--url https://api.openmail.sh/v1/domains \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domain": "<string>",
"podId": "<string>"
}
'import requests
url = "https://api.openmail.sh/v1/domains"
payload = {
"domain": "<string>",
"podId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({domain: '<string>', podId: '<string>'})
};
fetch('https://api.openmail.sh/v1/domains', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'domain' => '<string>',
'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"
payload := strings.NewReader("{\n \"domain\": \"<string>\",\n \"podId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.openmail.sh/v1/domains")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"domain\": \"<string>\",\n \"podId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openmail.sh/v1/domains")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"domain\": \"<string>\",\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"
}
],
"verifiedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"id": "<string>",
"domain": "<string>",
"podId": "<string>",
"status": "pending",
"records": [
{
"type": "TXT",
"name": "<string>",
"value": "<string>",
"priority": 123,
"purpose": "spf",
"status": "missing"
}
],
"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>"
}{
"error": "<string>",
"message": "<string>"
}Add custom domain
Add a custom domain to your account. The response includes the DNS records to publish (records). Once you publish them, the domain verifies automatically within a couple of minutes — poll GET /v1/domains/{id} until status is verified, then create inboxes on it. A pod-scoped API key creates the domain scoped to its own pod; inbox-scoped keys cannot manage domains.
curl --request POST \
--url https://api.openmail.sh/v1/domains \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domain": "<string>",
"podId": "<string>"
}
'import requests
url = "https://api.openmail.sh/v1/domains"
payload = {
"domain": "<string>",
"podId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({domain: '<string>', podId: '<string>'})
};
fetch('https://api.openmail.sh/v1/domains', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'domain' => '<string>',
'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"
payload := strings.NewReader("{\n \"domain\": \"<string>\",\n \"podId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.openmail.sh/v1/domains")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"domain\": \"<string>\",\n \"podId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openmail.sh/v1/domains")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"domain\": \"<string>\",\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"
}
],
"verifiedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"id": "<string>",
"domain": "<string>",
"podId": "<string>",
"status": "pending",
"records": [
{
"type": "TXT",
"name": "<string>",
"value": "<string>",
"priority": 123,
"purpose": "spf",
"status": "missing"
}
],
"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>"
}{
"error": "<string>",
"message": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The domain to add, e.g. mail.acme.com. A subdomain is easiest to set up without affecting your existing mail.
4 - 253Pod to scope the domain to. Omit or null for an account-wide domain usable by any pod. A pod-scoped API key may only pass its own pod.
Response
Domain added; publish the DNS records to verify it
Domain added; publish the DNS records to verify it
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
Was this page helpful?