Get a Domain
curl --request GET \
--url https://api.thepurplebox.io/v1/domains \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: <content-type>'import requests
url = "https://api.thepurplebox.io/v1/domains"
headers = {
"Content-Type": "<content-type>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'Content-Type': '<content-type>', Authorization: 'Bearer <token>'}
};
fetch('https://api.thepurplebox.io/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.thepurplebox.io/v1/domains",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.thepurplebox.io/v1/domains"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Content-Type", "<content-type>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.thepurplebox.io/v1/domains")
.header("Content-Type", "<content-type>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.thepurplebox.io/v1/domains")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"status": 200,
"message": "domain retrieved successfully.",
"data": {
"id": "xxxxx",
"value": "yourdomain.com",
"team_id": "xxxxx",
"status": "not_started",
"identity_type": "domain",
"created_at": "2025-11-21T10:23:14.737725Z",
"verified_at": null,
"attributes": {
"dkim_attributes": {
"name": "thepurplebox._domainkey.yourdomain",
"record_type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
"ttl": "auto",
"status": "not_started"
},
"mail_from_attributes": [
{
"name": "send.yourdomain",
"record_type": "TXT",
"value": "xxxx",
"ttl": "60",
"status": "not_started"
},
{
"name": "bounce.yourdomain",
"record_type": "CNAME",
"value": "xxxxx",
"ttl": "60",
"status": "not_started"
}
],
"dmarc_attributes": {
"name": "_dmarc",
"record_type": "TXT",
"value": "v=DMARC1;p=none;",
"ttl": "auto",
"status": ""
},
"verification_status": "not_started",
"verified_for_sending_status": false,
"error_type": ""
},
"last_status_checked_at": "2025-11-21T10:23:14.737725Z"
}
}
Domains
Get a Domain
Retrieve details and DNS configuration for a domain identity.
GET
/
v1
/
domains
Get a Domain
curl --request GET \
--url https://api.thepurplebox.io/v1/domains \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: <content-type>'import requests
url = "https://api.thepurplebox.io/v1/domains"
headers = {
"Content-Type": "<content-type>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'Content-Type': '<content-type>', Authorization: 'Bearer <token>'}
};
fetch('https://api.thepurplebox.io/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.thepurplebox.io/v1/domains",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: <content-type>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.thepurplebox.io/v1/domains"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Content-Type", "<content-type>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.thepurplebox.io/v1/domains")
.header("Content-Type", "<content-type>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.thepurplebox.io/v1/domains")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"status": 200,
"message": "domain retrieved successfully.",
"data": {
"id": "xxxxx",
"value": "yourdomain.com",
"team_id": "xxxxx",
"status": "not_started",
"identity_type": "domain",
"created_at": "2025-11-21T10:23:14.737725Z",
"verified_at": null,
"attributes": {
"dkim_attributes": {
"name": "thepurplebox._domainkey.yourdomain",
"record_type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
"ttl": "auto",
"status": "not_started"
},
"mail_from_attributes": [
{
"name": "send.yourdomain",
"record_type": "TXT",
"value": "xxxx",
"ttl": "60",
"status": "not_started"
},
{
"name": "bounce.yourdomain",
"record_type": "CNAME",
"value": "xxxxx",
"ttl": "60",
"status": "not_started"
}
],
"dmarc_attributes": {
"name": "_dmarc",
"record_type": "TXT",
"value": "v=DMARC1;p=none;",
"ttl": "auto",
"status": ""
},
"verification_status": "not_started",
"verified_for_sending_status": false,
"error_type": ""
},
"last_status_checked_at": "2025-11-21T10:23:14.737725Z"
}
}
Headers
string
required
application/jsonQuery Parameters
string
required
The domain name to retrieve (e.g.,
yourdomain.com).Response
number
HTTP status code. Returns
200 when the domain is retrieved successfully.string
A human-readable message describing the result of the operation.
object
Contains the domain identity configuration and DNS records required for verification.
Show properties
Show properties
string
Unique identifier for the domain identity.
string
The domain name that was added.
string
The team ID that owns this domain identity.
string
Current status of the domain. Possible values:
not_started, pending, success, failed, temporary_failure.string
Type of identity. Always
domain for domain identities.string
ISO 8601 timestamp when the domain identity was created.
string | null
ISO 8601 timestamp when the domain was verified. Null if not yet verified.
object
DNS configuration attributes required for domain verification.
Show properties
Show properties
object
DKIM (DomainKeys Identified Mail) record configuration for email authentication.
Show properties
Show properties
string
The DNS record name for the DKIM selector (e.g.,
thepurplebox._domainkey.yourdomain).string
The DNS record type. Always
TXT for DKIM records.string
The DKIM public key value to add to your DNS records. Starts with
v=DKIM1; k=rsa; p=.string
Time to Live for the DNS record. Can be
auto or a specific value in seconds.string
Verification status of the DKIM record. Possible values:
not_started, pending, success, failed.array
Array of DNS records required for configuring the MAIL FROM domain.
Show properties
Show properties
string
The subdomain name for the mail record (e.g.,
send.yourdomain or bounce.yourdomain).string
The DNS record type. Can be
TXT or CNAME.string
The DNS record value. For TXT records, contains SPF policy. For CNAME records, points to the bounce handler.
string
Time to Live for the DNS record in seconds (e.g.,
60).string
Verification status of the record. Possible values:
not_started, pending, success, failed.object
DMARC (Domain-based Message Authentication, Reporting, and Conformance) record configuration.
Show properties
Show properties
string
Overall verification status of the domain. Possible values:
not_started, pending, success, failed, temporary_failure.boolean
Indicates whether the domain is verified and ready to send emails. Returns
true when all DNS records are verified.string
Error type if verification fails. Empty string when no errors are present.
string
ISO 8601 timestamp of the last verification status check.
{
"status": 200,
"message": "domain retrieved successfully.",
"data": {
"id": "xxxxx",
"value": "yourdomain.com",
"team_id": "xxxxx",
"status": "not_started",
"identity_type": "domain",
"created_at": "2025-11-21T10:23:14.737725Z",
"verified_at": null,
"attributes": {
"dkim_attributes": {
"name": "thepurplebox._domainkey.yourdomain",
"record_type": "TXT",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
"ttl": "auto",
"status": "not_started"
},
"mail_from_attributes": [
{
"name": "send.yourdomain",
"record_type": "TXT",
"value": "xxxx",
"ttl": "60",
"status": "not_started"
},
{
"name": "bounce.yourdomain",
"record_type": "CNAME",
"value": "xxxxx",
"ttl": "60",
"status": "not_started"
}
],
"dmarc_attributes": {
"name": "_dmarc",
"record_type": "TXT",
"value": "v=DMARC1;p=none;",
"ttl": "auto",
"status": ""
},
"verification_status": "not_started",
"verified_for_sending_status": false,
"error_type": ""
},
"last_status_checked_at": "2025-11-21T10:23:14.737725Z"
}
}
⌘I