API reference

Email domains

Verify sending domains for email.

get/v1/email-domains

List sending domains

Permissionemail_domains:rNode.js SDKhonkio.domains.list()

Requires email_domains:r.

Responses

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.domains.list()
if (error) throw new Error(error.message)
for (const d of data.data) console.log(d.domain, d.status)

curl https://api.honkio.ca/v1/email-domains \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/email-domains

Add a sending domain

Permissionemail_domains:wNode.js SDKhonkio.domains.create()

Requires email_domains:w.

Request body

The domain to send from.

Field	Type	Description
`domain`required	string	A domain or subdomain you control, such as mail.yourdomain.ca. Publish the DNS records the response lists, then verify it. At least 1 characters At most 253 characters

Responses

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

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

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

get/v1/email-domains/{id}

Get a sending domain

Permissionemail_domains:rNode.js SDKhonkio.domains.get()

Requires email_domains:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.domains.get('DOMAIN_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.records)

curl https://api.honkio.ca/v1/email-domains/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

patch/v1/email-domains/{id}

Update a sending domain's open/click tracking or receiving

Permissionemail_domains:mNode.js SDKhonkio.domains.update()

Requires email_domains:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Request body

The settings to change: at least one of open_tracking, click_tracking or receiving.

Field	Type	Description
`open_tracking`	boolean	Track opens on this domain's email. Null restores the platform default. Can be null
`click_tracking`	boolean	Track clicks on this domain's email. Null restores the platform default. Can be null
`receiving`	boolean	Receive email at this domain. The domain must be verified for sending first; the response adds the inbound MX record to publish.

Responses

200The updated domain, with the DNS records to publish (the inbound MX while receiving is on).

Field	Type	Description
`id`required	string
`domain`required	string
`status`required	string	One of: pending \| verifying \| verified \| failed \| temporarily_failed
`region`required	string
`verified_at`required	string	Format: date-time Can be null
`last_checked_at`required	string	Format: date-time Can be null
`failure_reason`required	string	Can be null
`revalidation_failed_at`required	string	Format: date-time Can be null
`open_tracking`required	boolean	Can be null
`click_tracking`required	boolean	Can be null
`receiving_status`required	string	One of: off \| pending \| verified \| failed
`receiving_requested_at`required	string	Format: date-time Can be null
`receiving_verified_at`required	string	Format: date-time Can be null
`receiving_failure_reason`required	string	Can be null
`receiving_revalidation_failed_at`required	string	Format: date-time Can be null
`receiving_last_checked_at`required	string	When the inbound MX was last checked on its own; last_checked_at dates the sending check. Format: date-time Can be null
`receiving_warning`required	string	apex_mx while receiving is on at a likely registrable apex: an MX there takes over the domain's own mail. One of: apex_mx Can be null
`created_at`required	string	Format: date-time
`records[]`required	object[]
`type`required	string	One of: TXT \| MX
`name`required	string
`value`required	string
`purpose`required	string	One of: dkim \| mail_from \| spf \| dmarc_recommended \| inbound
`receiving_missing[]`required	object[]	The inbound MX, when this request just turned receiving on and it is not published yet; [] otherwise. A lookup only: POST /v1/email-domains/{id}/verify moves receiving_status.
`record`required	string
`expected`required	string

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403ACCOUNT_NOT_VERIFIED: turning receiving on for a live domain needs a verified owner mobile number. Turning receiving off, and every other field, is unaffected. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
409RECEIVING_REQUIRES_VERIFIED_DOMAIN: receiving can only be turned on for a domain verified for sending.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.domains.update('DOMAIN_ID', { clickTracking: false, receiving: true })
if (error) throw new Error(error.message)
console.log(data.receiving_status)

curl -X PATCH https://api.honkio.ca/v1/email-domains/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_tracking": false,
    "receiving": true
  }'

delete/v1/email-domains/{id}

Delete a sending domain

Permissionemail_domains:dNode.js SDKhonkio.domains.remove()

Requires email_domains:d.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { error } = await honkio.domains.remove('DOMAIN_ID')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/email-domains/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/email-domains/{id}/verify

Re-check DNS and SES verification status

Permissionemail_domains:wNode.js SDKhonkio.domains.verify()

Requires email_domains:w.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

200The result of the check. missing lists sending records not found; receiving_missing the inbound MX when receiving is on and it is not published.

Field	Type	Description
`id`required	string
`status`required	string	One of: pending \| verifying \| verified \| failed \| temporarily_failed
`verified`required	boolean
`missing[]`required	object[]
`record`required	string
`expected`required	string
`ses_status`required	string	Can be null
`mail_from_status`required	string	Can be null
`receiving_status`required	string	One of: off \| pending \| verified \| failed
`receiving_missing[]`required	object[]
`record`required	string
`expected`required	string
`receiving_warning`required	string	apex_mx while receiving is on at a likely registrable apex: an MX there takes over the domain's own mail. One of: apex_mx Can be null

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.domains.verify('DOMAIN_ID')
if (error) throw new Error(error.message)
console.log(data.verified, data.missing)

curl -X POST https://api.honkio.ca/v1/email-domains/ID/verify \
  -H "Authorization: Bearer mk_live_YOUR_KEY"