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`	Region for email sending (us, eu)

Example Request

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

Example Response

{
  "id": "domain_abc123xyz789",
  "name": "mail.example.com",
  "region": "us",
  "status": "pending",
  "created_at": "2026-03-21T10:30:00Z",
  "verified_at": null,
  "dns_records": [
    {
      "type": "SPF",
      "name": "mail.example.com",
      "value": "v=spf1 include:sendmail.txtly.io ~all"
    },
    {
      "type": "DKIM",
      "name": "default._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC..."
    },
    {
      "type": "DKIM",
      "name": "alt1._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC..."
    },
    {
      "type": "DKIM",
      "name": "alt2._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC..."
    },
    {
      "type": "Return-Path",
      "name": "_return.mail.example.com",
      "value": "mail.example.com.bounces.txtly.io"
    },
    {
      "type": "DMARC",
      "name": "_dmarc.mail.example.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@txtly.io"
    }
  ]
}

List Domains

GET

/v1/domains

List all domains for your account.

Example Response

{
  "domains": [
    {
      "id": "domain_abc123xyz789",
      "name": "mail.example.com",
      "region": "us",
      "status": "verified",
      "created_at": "2026-03-21T10:30:00Z",
      "verified_at": "2026-03-21T11:00:00Z"
    }
  ]
}

Get Domain

GET

/v1/domains/{id}

Retrieve a specific domain by ID.

Path Parameters

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

Update Domain

PATCH

/v1/domains/{id}

Update domain settings such as tracking configuration.

Parameters

Parameter	Type	Description
`click_tracking`	`boolean`	Enable click tracking for this domain
`open_tracking`	`boolean`	Enable open tracking for this domain
`tls`	`boolean`	Require TLS for outgoing connections
`custom_return_path`	`string`	Custom return path domain

Example Request

curl -X PATCH https://api.txtly.io/v1/domains/domain_abc123xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_tracking": true,
    "open_tracking": true
  }'

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

Verify a domain by checking for all required DNS records. Returns verification status.

Path Parameters

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

Example Response

{
  "id": "domain_abc123xyz789",
  "name": "mail.example.com",
  "status": "verified",
  "verified_at": "2026-03-21T11:00:00Z",
  "records": {
    "spf": {
      "status": "valid",
      "value": "v=spf1 include:sendmail.txtly.io ~all"
    },
    "dkim": {
      "status": "valid",
      "records": [
        { "selector": "default", "status": "valid" },
        { "selector": "alt1", "status": "valid" },
        { "selector": "alt2", "status": "valid" }
      ]
    },
    "dmarc": {
      "status": "valid",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@txtly.io"
    }
  }
}

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