Sending domains

Sending domains

Add a domain or subdomain you control, then publish the records the API returns at your DNS host. Nothing goes on your root domain, so your own mail and SPF record are untouched.

const { data: domain, error } = await honkio.domains.create({ domain: 'mail.acme.ca' })
if (error) throw new Error(error.message)
for (const record of domain.records) console.log(record.type, record.name, record.value)

curl -X POST https://api.honkio.ca/v1/email-domains \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.acme.ca" }'

// Publish the returned records at your DNS host, then check them:
const { data, error } = await honkio.domains.verify('DOMAIN_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.verified, data.missing) // verified true []

# Publish the returned records at your DNS host, then check them:
curl -X POST https://api.honkio.ca/v1/email-domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
# → { "status": "verified", "verified": true, "missing": [] }

// Tracking per domain (null = the platform default):
const { data, error } = await honkio.domains.update('DOMAIN_ID', { openTracking: false, clickTracking: null })
if (error) throw new Error(error.message)
console.log(data.open_tracking, data.click_tracking)

# Tracking per domain (null = the platform default):
curl -X PATCH https://api.honkio.ca/v1/email-domains/DOMAIN_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "open_tracking": false, "click_tracking": null }'

A domain is pending until its records are found, verifying while they propagate, and verified once DKIM, the MX, SPF and the email provider all agree. It moves to failed once its records are still missing after 7 days or the email provider rejects the domain outright, and to temporarily failed on a transient provider failure or when an already-verified domain fails a re-check; call verify again once the records are fixed. Verification is checked again every day; a record that disappears gives the domain 72 hours to recover before it stops sending.

Call verify any time to check now. The response names any record that is still missing.

A domain belongs to whoever proves they control its DNS. Another account's verified domain can't be added; an unverified claim blocks others for 72 hours, and the 409 EMAIL_DOMAIN_IN_USE answer says when it lapses.

An account can hold 5 sending domains by default. A domain that failed verification does not count, and neither does a domain added with a test key. Ask support to raise the limit. At the limit the API answers 422 EMAIL_DOMAIN_LIMIT_REACHED to adding a domain, and to verifying a failed domain whose DNS is now correct (it stays failed).

Open and click tracking are off by default. Turn them on per domain with PATCH, or per email with the tracking field; null restores the platform default.

An API key can be restricted to specific sending domains when it is created. A restricted key can send only from its own domains, and can only reschedule or cancel an email that was sent from one of them; adding, verifying and managing domains themselves is unaffected and stays open to any key with the email_domains permission.