Domains API

Manage sending domains, DNS verification, inbound receiving flags, tracking preferences, TLS mode, one-click DNS apply, and DMARC/BIMI guidance.

Base URL: https://api.supersendtx.com

Auth:

Authorization: Bearer stx_...

Create a domain

POST /domains

curl -X POST https://api.supersendtx.com/domains \
  -H "Authorization: Bearer $SUPERSENDTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "example.com" }'

Success response:

{
  "domain": {
    "id": "d_123",
    "name": "example.com",
    "status": "pending",
    "created_at": "2026-07-26T00:00:00.000Z",
    "verified_at": null,
    "open_tracking": false,
    "click_tracking": false,
    "tls_mode": "opportunistic"
  },
  "records": [
    {
      "type": "TXT",
      "host": "_supersendtx.example.com",
      "value": "supersendtx-verify=...",
      "purpose": "Domain ownership"
    }
  ]
}

To request inbound receiving during creation, include "inbound_enabled": true. The response will also include inbound_records (MX) and inbound_note. Full receiving flow: docs/api/inbound.md.

Expected DNS records (after create syncs with the mail server):

ownership TXT: _supersendtx.example.com
DKIM TXT: Postal selector host such as ss-abc123._domainkey.example.com with Postal's real public key
return-path CNAME: rp.example.com → rp.core.superesp.com (DNS only / not proxied)
SPF include: include:spf.supersendtx.com
DMARC starter record

SuperSend TX registers the domain on the shared Postal TX server at create time and replaces placeholder DKIM with Postal's signing records before apply/verify.

Cross-team claim conflict

If the domain is already attached to another SuperSend TX team, the API returns 409 with claim instructions:

{
  "error": {
    "message": "Domain already belongs to another SuperSend TX team. Remove it from the current team or contact support to claim it.",
    "code": "conflict",
    "details": {
      "reason": "domain_claim_required",
      "domain": "example.com",
      "instructions": [
        "Ask the current SuperSend TX team admin to remove the domain if you still have access.",
        "If you own the domain but no longer control the original team, contact support and include proof of DNS control."
      ]
    }
  }
}

Get a domain

GET /domains/{id}

Returns the domain, required DNS records, inbound MX guidance, and best-effort DMARC/BIMI analysis:

{
  "domain": {
    "id": "d_123",
    "name": "example.com",
    "status": "verified",
    "created_at": "2026-07-26T00:00:00.000Z",
    "verified_at": "2026-07-26T00:05:00.000Z",
    "open_tracking": true,
    "click_tracking": false,
    "tls_mode": "enforced",
    "inbound_enabled": true,
    "inbound_status": "active",
    "inbound_error": null
  },
  "records": [],
  "inbound_records": [
    {
      "type": "MX",
      "host": "example.com",
      "value": "10 mx.core.superesp.com",
      "purpose": "Inbound receiving"
    }
  ],
  "inbound_note": "Inbound receiving requires pointing this hostname's MX record to SuperSend TX. That conflicts with any existing mailbox provider on the same hostname, so use a dedicated subdomain such as inbound.example.com when Google Workspace or Microsoft 365 should keep handling your main mailboxes.",
  "analysis": {
    "dmarc": {
      "host": "_dmarc.example.com",
      "configured": true,
      "record": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
      "policy": "quarantine",
      "rua": ["mailto:dmarc@example.com"],
      "guidance": "DMARC is enforced. Keep report mailboxes monitored and tighten alignment as you roll out BIMI."
    },
    "bimi": {
      "host": "default._bimi.example.com",
      "configured": false,
      "record": null,
      "location": null,
      "authority": null,
      "requires_dmarc_enforcement": false,
      "guidance": "Optional: add a BIMI record at default._bimi once your branded SVG logo and optional VMC are ready."
    }
  }
}

DMARC/BIMI notes

DMARC is recommended for every sending domain.
BIMI is optional, but most mailbox providers expect DMARC enforcement (p=quarantine or p=reject) before BIMI is effective.
analysis is advisory. It does not block sending, and it does not replace your own deliverability monitoring.

Verify DNS

POST /domains/{id}

{ "action": "verify" }

When ownership, SPF, Postal DKIM, and the return-path CNAME are visible in public DNS, SuperSend TX marks the domain verified and enables sending. DMARC is reported back but does not currently block verification.

Apply DNS

POST /domains/{id}

Cloudflare via stored dashboard token

{
  "action": "apply",
  "provider": "cloudflare"
}

Cloudflare via inline credentials

{
  "action": "apply",
  "provider": "cloudflare",
  "credentials": {
    "apiToken": "cf_...",
    "zoneId": "..."
  }
}

GoDaddy via one-time credentials

{
  "action": "apply",
  "provider": "godaddy",
  "credentials": {
    "apiKey": "gd_key",
    "apiSecret": "gd_secret"
  }
}

GoDaddy credentials are used for that request only and are not stored by SuperSend TX.

Response shape:

{
  "provider": "godaddy",
  "domain": "example.com",
  "results": [
    {
      "purpose": "SPF",
      "host": "example.com",
      "action": "merged",
      "detail": "v=spf1 include:spf.supersendtx.com ~all"
    }
  ]
}

Update tracking, inbound, and TLS preferences

PATCH /domains/{id}

curl -X PATCH https://api.supersendtx.com/domains/example.com \
  -H "Authorization: Bearer $SUPERSENDTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_enabled": true,
    "open_tracking": true,
    "click_tracking": true,
    "tls_mode": "enforced"
  }'

Aliases openTracking, clickTracking, tlsMode, and inboundEnabled are also accepted.

Inbound enablement

inbound_enabled: true marks the domain for receiving.
Before verification, inbound stays pending.
After verification, SuperSend TX activates inbound receiving and updates inbound_status to active or error.
See docs/api/inbound.md for received-email retrieval and email.received webhooks.

TLS modes

opportunistic — use TLS when the downstream mail path supports it.
enforced — require TLS for the downstream mail path.

Tracking and TLS preferences

open_tracking, click_tracking, and tls_mode are stored on the domain immediately when you update them.

When open or click tracking is enabled:

SuperSend TX provisions a Postal track domain for your hostname.
The domain detail response includes a tracking CNAME (ps.yourdomain.com → track.core.superesp.com).
Apply and verify DNS so Postal can rewrite links and inject open pixels.
tracking_dns.ok in GET /domains/{id} reports whether the CNAME is live.

If platform mail-server admin credentials are missing, settings are still saved but tracking_postal_error may be returned on PATCH.

SDK

import { SuperSendTX } from 'supersendtx'

const client = new SuperSendTX(process.env.SUPERSENDTX_API_KEY!)

await client.domains.create({ name: 'example.com' })
await client.domains.apply('example.com')
await client.domains.apply('example.com', {
  provider: 'godaddy',
  credentials: {
    apiKey: process.env.GODADDY_API_KEY!,
    apiSecret: process.env.GODADDY_API_SECRET!,
  },
})
await client.domains.verify('example.com')

const detail = await client.domains.get('example.com')
const updated = await client.domains.update('example.com', {
  open_tracking: true,
  tls_mode: 'enforced',
})

CLI

supersendtx domains add example.com
supersendtx domains apply example.com --provider cloudflare
GODADDY_API_KEY=... GODADDY_API_SECRET=... supersendtx domains apply example.com --provider godaddy
supersendtx domains verify example.com

Delete a domain

DELETE /domains/{id}

Removes the domain from your account and revokes sending authorization for that hostname.

supersendtx domains delete example.com

If upstream teardown fails, the domain is kept and the API returns 502.

Common errors

Status	Meaning
400	invalid domain, DNS not ready, missing provider credentials
401	missing or invalid auth
403	domain limit reached
404	domain not found
409	domain already exists or is already claimed
502	Domain registration, teardown, or DNS provider API failed

Full contract: openapi/supersendtx.yaml