API reference

Email suppressions

Manage email suppression lists.

get/v1/email-suppressions

List suppressed email addresses

Permissionemail_suppressions:rNode.js SDKhonkio.suppressions.list()

Newest first. Filter with reason (hard_bounce, complaint, unsubscribe or manual) and page with limit (default 50, up to 100) and cursor. Suppressions are kept per key mode: a test key lists, adds and removes test suppressions (its test emails' simulated bounces, complaints and unsubscribes, and its own blocks), which only test sends are checked against, and a live key the live ones.

Requires email_suppressions:r.

Responses

200A page of suppressions in the calling key's mode, newest first.

Field	Type	Description
`data[]`required	object[]
`email_address`required	string
`reason`required	string	One of: hard_bounce \| complaint \| unsubscribe \| manual
`source`required	string	What added it: ses_bounce, ses_complaint, unsubscribe or manual.
`metadata`required	any	What recorded it, such as the email id of a bounce; null for a manual block.
`created_at`required	string	Format: date-time
`livemode`required	boolean	false for a record made or read with a test key (a test-mode record), true for a live one.
`has_more`required	boolean
`next_cursor`required	string	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.
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.suppressions.list({ reason: 'hard_bounce' })
if (error) throw new Error(error.message)
for (const s of data.data) console.log(s.email_address, s.created_at)

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

post/v1/email-suppressions

Suppress an email address

Permissionemail_suppressions:wNode.js SDKhonkio.suppressions.create()

Adds the address to the suppression list with the reason manual, answering 201. An address the recipient already unsubscribed or complained from keeps that reason, and the call answers 200 with it. A send to a suppressed address is refused with EMAIL_SUPPRESSED. Suppressions are kept per key mode: a test key lists, adds and removes test suppressions (its test emails' simulated bounces, complaints and unsubscribes, and its own blocks), which only test sends are checked against, and a live key the live ones.

Requires email_suppressions:w.

Request body

The address to block.

Field	Type	Description
`email_address`required	string	The address. No email is sent to it again until you remove it. Format: email
`reason`required	string	Always manual: bounces, complaints and unsubscribes are added automatically. One of: manual

Responses

200The address was already suppressed by the recipient (an unsubscribe or a spam complaint): the row is kept as it is, with its own reason, and no manual block is added.

Field	Type	Description
`email_address`required	string
`reason`required	string	One of: unsubscribe \| complaint
`livemode`required	boolean	false for a record made or read with a test key (a test-mode record), true for a live one.

201The suppressed address, lowercased. A test key adds it to the test list, which only test sends are checked against.
Field Type Description
email_addressrequired string
reasonrequired string
One of: manual
livemoderequired boolean
false for a record made or read with a test key (a test-mode record), true for a live one.
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.
403FORBIDDEN: the key lacks the permission this operation requires, or the account is suspended or closed.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 { error } = await honkio.suppressions.create({ emailAddress: 'sam@example.com' })
if (error) throw new Error(error.message)

curl -X POST https://api.honkio.ca/v1/email-suppressions \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "sam@example.com",
    "reason": "manual"
  }'

delete/v1/email-suppressions/{address}

Remove an address from the suppression list

Permissionemail_suppressions:dNode.js SDKhonkio.suppressions.remove()

Removes a manual or hard_bounce suppression and answers 204, or 404 when the address is not suppressed. An unsubscribe or complaint suppression, or any suppression of an address with an email opt-out on record, is the recipient's own decision and is refused with 409 EMAIL_SUPPRESSION_NOT_REMOVABLE. Suppressions are kept per key mode: a test key lists, adds and removes test suppressions (its test emails' simulated bounces, complaints and unsubscribes, and its own blocks), which only test sends are checked against, and a live key the live ones.

Requires email_suppressions:d.

Parameters

Parameter	Type	Description
`address`requiredpath	string

Responses

204Removed: the address can receive email of the key's mode again.
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.
403FORBIDDEN: the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND (details.resource "email_suppression"): the address is not suppressed in the key's mode.The standard error body.
409EMAIL_SUPPRESSION_NOT_REMOVABLE: the recipient unsubscribed or reported your email as spam (the suppression's reason is unsubscribe or complaint, or the address has an email opt-out on record), which only the recipient can reverse. Other manual and hard_bounce suppressions can be removed.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.suppressions.remove('sam@example.com')
if (error) throw new Error(error.message)

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