Communications

Start verified email domain setup

Derives the base domain from the organization saved From address and creates the prefix subdomain, default mg with us region. Public mailbox domains are rejected. Setup is idempotent for the same subdomain; a normal receipt returns 201 even when reusing an existing setup. Add the returned sending DNS records, then check verification. An ambiguous provider outcome returns 202 with code/data and can reconcile later; existing externally claimed domains return 409 with a suggested prefix. Existing active/ready setup must be removed before changing prefixes. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.

POST

admin

settings

sending-domains

Start verified email domain setup

curl --request POST \
  --url https://api.gratona.com/v1/admin/email/settings/sending-domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "region": "us",
  "prefix": "mg"
}
'

import requests

url = "https://api.gratona.com/v1/admin/email/settings/sending-domains"

payload = {
    "region": "us",
    "prefix": "mg"
}
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({region: 'us', prefix: 'mg'})
};

fetch('https://api.gratona.com/v1/admin/email/settings/sending-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.gratona.com/v1/admin/email/settings/sending-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([
    'region' => 'us',
    'prefix' => 'mg'
  ]),
  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.gratona.com/v1/admin/email/settings/sending-domains"

	payload := strings.NewReader("{\n  \"region\": \"us\",\n  \"prefix\": \"mg\"\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.gratona.com/v1/admin/email/settings/sending-domains")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"region\": \"us\",\n  \"prefix\": \"mg\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/email/settings/sending-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  \"region\": \"us\",\n  \"prefix\": \"mg\"\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  }
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

Authorizations

Authorization

string

header

required

Passport bearer token authentication for legacy admin sessions.

Body

application/json

Validated request fields for this operation.

region

enum<string>

default:us

Available options:

us,

eu

Example:

"us"

prefix

string

default:mg

One subdomain label; trimmed and lowercased. Letters, digits and internal hyphens only.

Required string length: 1 - 63

Pattern: ^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$

Example:

"mg"

Response

Operation result.

message

string

data

object

Safe domain verification/delivery state. Credentials, provider account ids and transport snapshots are not returned. active alone does not guarantee transport_ready.

Show child attributes

Start verified email domain setup

curl --request POST \
  --url https://api.gratona.com/v1/admin/email/settings/sending-domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "region": "us",
  "prefix": "mg"
}
'

import requests

url = "https://api.gratona.com/v1/admin/email/settings/sending-domains"

payload = {
    "region": "us",
    "prefix": "mg"
}
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({region: 'us', prefix: 'mg'})
};

fetch('https://api.gratona.com/v1/admin/email/settings/sending-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.gratona.com/v1/admin/email/settings/sending-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([
    'region' => 'us',
    'prefix' => 'mg'
  ]),
  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.gratona.com/v1/admin/email/settings/sending-domains"

	payload := strings.NewReader("{\n  \"region\": \"us\",\n  \"prefix\": \"mg\"\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.gratona.com/v1/admin/email/settings/sending-domains")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"region\": \"us\",\n  \"prefix\": \"mg\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/email/settings/sending-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  \"region\": \"us\",\n  \"prefix\": \"mg\"\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  }
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}

{
  "message": "Finish DNS verification before activating verified sending.",
  "code": "domain_not_verified",
  "data": {
    "id": 42,
    "domain": "mg.example.org",
    "from_domain": "example.org",
    "region": "us",
    "status": "pending_dns",
    "provisioning_status": "ready",
    "suggested_prefix": "send",
    "provider_state": "unverified",
    "active": true,
    "dns_records": [
      {
        "type": "TXT",
        "name": "mg.example.org",
        "value": "v=spf1 include:mailgun.org ~all",
        "priority": "<string>",
        "valid": true,
        "validity": "valid"
      }
    ],
    "last_error": "<string>",
    "last_error_code": "<string>",
    "next_reconcile_at": "2026-10-20T12:00:00Z",
    "last_checked_at": "2026-10-20T12:00:00Z",
    "verified_at": "2026-10-20T12:00:00Z",
    "tested_at": "2026-10-20T12:00:00Z",
    "activated_at": "2026-10-20T12:00:00Z",
    "transport_ready": true,
    "other_domain_senders": {
      "items": [
        {
          "id": 42,
          "name": "Education updates",
          "from": "updates@other.example.org"
        }
      ],
      "total": 1
    }
  },
  "suggested_prefix": "send"
}