Sending domains

What you publish

One record is required. The other two are returned for completeness and one of them is actively dangerous to paste over an existing value.

Add a domain

Generates a fresh 2048-bit DKIM key pair for this domain and returns the records to publish. The private half is encrypted at rest and never leaves the platform.

const domain = await posthaste.domains.create({ name: 'yourdomain.com' })

domain.id      // 'dom_9pXbNc7HrQ8T2Sf3kQAZLm'
domain.status  // 'pending'

// One required record: the DKIM key. SPF and DMARC come back too, marked
// optional, with a warning apiece about overwriting an existing record.
const dkim = domain.records.find((r) => r.required)
console.log(dkim.type, dkim.name, dkim.value)

Verify it

Looks the records up in DNS now and records the outcome. It asks the zone’s own nameservers first and falls back to public resolvers, so no intermediate cache gets to decide whether you can send — a negative cache entry has previously reported a correctly published record as missing.

Every check is reported, passing or not, so you can see exactly which record is wrong instead of being told “verification failed”. Only checks with required: true gate the result.

const result = await posthaste.domains.verify('dom_9pXbNc7HrQ8T2Sf3kQAZLm')

// Branch on `verified`, not on the checks: SPF and DMARC are reported but
// neither of them failing stops the domain being usable.
if (!result.verified) {
  for (const check of result.checks) {
    console.log(check.record, check.status, check.detail)
  }
}

List domains

Newest first, not paginated — an account has a handful of domains. Each row carries the records to publish, so a browser tab closed before the DKIM value was copied is not a dead end. Everything returned is derived from stored public data; no private key is involved.

const { data } = await posthaste.domains.list()

for (const domain of data) {
  domain.status        // 'pending' | 'verified' | 'failed' | 'disabled'
  domain.messagesSent  // non-zero is what makes deleting it refused
  domain.records       // on the LIST too, so closing that first tab loses nothing
}

Remove a domain

A domain that has never sent is deleted outright. One that has is refused, and that is a deliberate choice rather than a limitation: the delivery record is the product, and removing the domain would take its history with it. Stop sending from it instead — an unused domain costs nothing and keeps its records.

Inbound addresses on the domain go with it when the delete succeeds.

Setup guidance

Answers “who hosts this domain’s DNS, and can we do this for them in one click”. It is what the dashboard’s setup screen calls so it can offer the right path instead of showing everybody a token field. Two live DNS lookups, so expect it to take a moment.

Publish DKIM through Cloudflare

If the domain is on Cloudflare, hand us a scoped API token and we will write the DKIM record for you. Exactly one record is written — SPF and DMARC are left alone on purpose, for the reason above.

The token is verified before anything is stored, the zone is located by name, the record is written, and then normal verification runs. A response with verified: false usually just means propagation has not caught up.

Forget a stored token

Deletes the stored Cloudflare credential for the account. Always 204, whether one was stored or not — it is a statement about the end state, and reporting “there was nothing to delete” would tell a caller something about the account they may not have known.