Domains

Manage sending domains, configure DNS records, and enable tracking features.

Create Domain

POST

/v1/domains

Create a new sending domain. The domain will generate DNS records for you to add to your DNS provider.

Parameters

Parameter	Type	Description
`name`required	`string`	Domain name (e.g., mail.example.com)
`region`	`string`	AWS region for email sending (default: us-east-1)

Example Request

curl -X POST https://api.txtly.com.au/v1/domains \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mail.example.com",
    "region": "us-east-1"
  }'

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "mail.example.com",
  "status": "not_started",
  "region": "us-east-1",
  "clickTracking": false,
  "openTracking": false,
  "tls": "opportunistic",
  "customReturnPath": null,
  "records": [
    {
      "type": "mx",
      "name": "mail.example.com",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10,
      "status": "pending"
    },
    {
      "type": "txt",
      "name": "mail.example.com",
      "value": "v=spf1 include:amazonses.com ~all",
      "priority": null,
      "status": "pending"
    },
    {
      "type": "cname",
      "name": "default._domainkey.mail.example.com",
      "value": "default.dkim.us-east-1.amazonses.com",
      "priority": null,
      "status": "pending"
    }
  ],
  "createdAt": "2026-03-21T10:30:00Z",
  "updatedAt": "2026-03-21T10:30:00Z"
}

List Domains

GET

/v1/domains

List all domains for your account.

Example Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "mail.example.com",
      "status": "verified",
      "region": "us-east-1",
      "createdAt": "2026-03-21T10:30:00Z"
    }
  ]
}

Get Domain

GET

/v1/domains/{id}

Retrieve a specific domain by ID, including DNS records and verification status.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Domain ID

Update Domain

PATCH

/v1/domains/{id}

Update domain settings such as tracking configuration and TLS mode.

Parameters

Parameter	Type	Description
`clickTracking`	`boolean`	Enable click tracking for this domain
`openTracking`	`boolean`	Enable open tracking for this domain
`tls`	`string`	TLS mode: opportunistic or enforced
`customReturnPath`	`string`	Custom return path domain

Example Request

curl -X PATCH https://api.txtly.com.au/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "clickTracking": true,
    "openTracking": true,
    "tls": "enforced"
  }'

Delete Domain

DELETE

/v1/domains/{id}

Delete a domain. Cannot be undone.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Domain ID

Verify Domain

POST

/v1/domains/{id}/verify

Trigger domain verification by checking DNS records. Returns the updated domain with record statuses.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Domain ID

Domain Status

Domains go through several states as they are created and verified.

Status Values

not_startedDomain created but verification not begun
pendingAwaiting DNS record verification
verifiedAll DNS records verified, domain ready to use
failedVerification failed, check DNS records
temporary_failureTemporary verification failure, will retry

DNS Record Types

Each domain generates DNS records that must be added to your DNS provider. Record types correspond to standard DNS types.

Record Types

txtUsed for SPF and DKIM verification
cnameUsed for DKIM keys and tracking subdomains
mxUsed for bounce handling and return path