API reference

Email

Mailboxes, forwarders, autoresponders, filters, routing, spam, deliverability; the mail server and its queue.

List mailboxes

GET/api/v1/accounts/{id}/email/accounts

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_accounts
Operation: listMail · ky call listMail

Parameters

Name	In
`id`	path
`refresh`	query

Responses

200 OK
Body
Field Type
items array of StoreMailAccount
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreMailAccount

Create a mailbox

POST/api/v1/accounts/{id}/email/accounts

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_accounts
Operation: createMail · ky call createMail

Parameters

Name	In
`id`	path

Request body

Field	Type
`domain_id`	string
`local_part`	string
`password`	string
`quota_mb`	integer

Responses

201 Created

Body

Field	Type
`account_id` always	string
`address` always	string
`autoresponder` always	boolean
`created_at` always	integer
`domain` always	string
`domain_id` always	string
`filters_count` always	integer
`id` always	string
`is_system` always	boolean
`local_part` always	string
`login_state` always	string
`quota_mb`	integer
`receive_state` always	string
`send_state` always	string
`used_bytes` always	integer
`used_updated_at`	integer

400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: limit-reached, validation
500 Internal Server Error: internal

Delete a mailbox

DELETE/api/v1/accounts/{id}/email/accounts/{mid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_accounts
Operation: deleteMail · ky call deleteMail

Parameters

Name	In
`id`	path
`mid`	path
`keep_data`	query

Responses

204 Done, no content
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: system-mailbox
500 Internal Server Error: internal

Change a mailbox's quota and restrictions

PUT/api/v1/accounts/{id}/email/accounts/{mid}

Changes quota and restrictions (suspend login / receiving / sending).

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_accounts
Operation: updateMail · ky call updateMail

Parameters

Name	In
`id`	path
`mid`	path

Request body

Field	Type
`login_state`	string
`quota_mb`	integer
`receive_state`	string
`send_state`	string
`unlimited`	boolean

Responses

200 OK

Body

Field	Type
`account_id` always	string
`address` always	string
`autoresponder` always	boolean
`created_at` always	integer
`domain` always	string
`domain_id` always	string
`filters_count` always	integer
`id` always	string
`is_system` always	boolean
`local_part` always	string
`login_state` always	string
`quota_mb`	integer
`receive_state` always	string
`send_state` always	string
`used_bytes` always	integer
`used_updated_at`	integer

400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Mail client settings of a mailbox

GET/api/v1/accounts/{id}/email/accounts/{mid}/client-settings

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: mail_client_config
Operation: clientSettings · ky call clientSettings

Parameters

Name	In
`id`	path
`mid`	path

Responses

200 OK

Body

Field Type

address always string

autoconfig_url always string

autodiscover_url always string

plain always

object

Field	Type
`imap` always	ServerEndpoint
`pop3` always	ServerEndpoint
`smtp` always	ServerEndpoint

secure always

object

Field	Type
`imap` always	ServerEndpoint
`pop3` always	ServerEndpoint
`smtp` always	ServerEndpoint

username always string

webmail_url always string

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Download the Apple mail profile

GET/api/v1/accounts/{id}/email/accounts/{mid}/mobileconfig

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: mail_client_config
Operation: mobileConfig · ky call mobileConfig

Parameters

Name	In
`id`	path
`mid`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Change a mailbox's password

PUT/api/v1/accounts/{id}/email/accounts/{mid}/password

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_accounts
Operation: mailPassword · ky call mailPassword

Parameters

Name	In
`id`	path
`mid`	path

Request body

Field	Type
`password`	string

Responses

204 Done, no content
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Open the webmail signed in

POST/api/v1/accounts/{id}/email/accounts/{mid}/webmail

Creates a direct sign-in link to the webmail (single use, 60 s).

Who: root, reseller (ACL: create-user-session); customer
API tokens: API tokens can't use this endpoint
Operation: webmailSSO · ky call webmailSSO

Parameters

Name	In
`id`	path
`mid`	path

Responses

200 OK
Body
Field Type
expires_in string
url string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: login-suspended
500 Internal Server Error: internal

Field	Type
`expires_in`	string
`url`	string

List autoresponders

GET/api/v1/accounts/{id}/email/autoresponders

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: autoresponders
Operation: getAccountsIdEmailAutoresponders · ky call getAccountsIdEmailAutoresponders

Parameters

Name	In
`id`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Create an autoresponder

POST/api/v1/accounts/{id}/email/autoresponders

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: autoresponders
Operation: postAccountsIdEmailAutoresponders · ky call postAccountsIdEmailAutoresponders

Parameters

Name	In
`id`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Delete an autoresponder

DELETE/api/v1/accounts/{id}/email/autoresponders/{aid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: autoresponders
Operation: deleteAccountsIdEmailAutorespondersAid · ky call deleteAccountsIdEmailAutorespondersAid

Parameters

Name	In
`id`	path
`aid`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Update an autoresponder

PUT/api/v1/accounts/{id}/email/autoresponders/{aid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: autoresponders
Operation: putAccountsIdEmailAutorespondersAid · ky call putAccountsIdEmailAutorespondersAid

Parameters

Name	In
`id`	path
`aid`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

List default addresses (catch-all)

GET/api/v1/accounts/{id}/email/default-addresses

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: default_address
Operation: listDefaultAddresses · ky call listDefaultAddresses

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
items array of DefaultAddressView
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of DefaultAddressView

Set a domain's default address

PUT/api/v1/accounts/{id}/email/default-addresses/{did}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: default_address
Operation: setDefaultAddress · ky call setDefaultAddress

Parameters

Name	In
`id`	path
`did`	path

Request body

Field	Type
`action`	string
`destination`	string
`fail_message`	string

Responses

200 OK
Body
Field Type
action always string
configured always boolean
destination string
domain always string
domain_id always string
fail_message string
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
422 Unprocessable Entity: rejected
500 Internal Server Error: internal

Field	Type
`action` always	string
`configured` always	boolean
`destination`	string
`domain` always	string
`domain_id` always	string
`fail_message`	string

Email deliverability of every domain

GET/api/v1/accounts/{id}/email/deliverability

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_deliverability
Operation: listDeliverability · ky call listDeliverability

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
items array of HostingDeliverabilityReport
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`items`	array of HostingDeliverabilityReport

Email deliverability of a domain (SPF, DKIM, DMARC, PTR)

GET/api/v1/accounts/{id}/email/deliverability/{did}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_deliverability
Operation: getDeliverability · ky call getDeliverability

Parameters

Name	In
`id`	path
`did`	path

Responses

200 OK
Body
Field Type
checked_at always integer
domain always string
domain_id always string
ok always boolean
records always array of HostingRecordCheck
spf_custom always StoreSPFCustom
zone_local always boolean
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`checked_at` always	integer
`domain` always	string
`domain_id` always	string
`ok` always	boolean
`records` always	array of HostingRecordCheck
`spf_custom` always	StoreSPFCustom
`zone_local` always	boolean

Install the suggested email DNS records

POST/api/v1/accounts/{id}/email/deliverability/{did}/repair

Installs the suggested records the domain's local zone is missing (or has wrong). Body {records:["spf","dkim","dmarc"]}; empty = every record that isn't valid in the zone.

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_deliverability
Operation: repairDeliverability · ky call repairDeliverability

Parameters

Name	In
`id`	path
`did`	path

Request body

Field	Type
`records`	array of string

Responses

200 OK
Body
Field Type
changed array of string
report HostingDeliverabilityReport
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: zone-not-local
500 Internal Server Error: internal

Field	Type
`changed`	array of string
`report`	HostingDeliverabilityReport

Customize and install the SPF record

PUT/api/v1/accounts/{id}/email/deliverability/{did}/spf

Saves the SPF customizer and, when the zone is local, installs the resulting record.

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_deliverability
Operation: putSPF · ky call putSPF

Parameters

Name	In
`id`	path
`did`	path

Request body

Field	Type
`all`	string
`hosts`	array of string
`includes`	array of string
`ip4`	array of string
`ip6`	array of string

Responses

200 OK
Body
Field Type
changed array of string
report HostingDeliverabilityReport
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`changed`	array of string
`report`	HostingDeliverabilityReport

Track delivery of the account's mail

GET/api/v1/accounts/{id}/email/deliveries

Is the customer's Track Delivery: mail the account sent, and mail to or from its domains.

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_trace
Operation: accountDeliveries · ky call accountDeliveries

Parameters

Name	In
`id`	path
`event`	query
`q`	query

Responses

200 OK
Body
Field Type
items array of StoreMailDelivery
retention_days integer
total integer
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreMailDelivery
`retention_days`	integer
`total`	integer

Remove a domain forwarder

DELETE/api/v1/accounts/{id}/email/domain-forwarders/{did}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_forwarders
Operation: deleteDomainForwarder · ky call deleteDomainForwarder

Parameters

Name	In
`id`	path
`did`	path

Responses

204 Done, no content
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Forward a whole domain

PUT/api/v1/accounts/{id}/email/domain-forwarders/{did}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_forwarders
Operation: setDomainForwarder · ky call setDomainForwarder

Parameters

Name	In
`id`	path
`did`	path

Request body

Field	Type
`to_domain`	string

Responses

200 OK
Body
Field Type
domain always string
domain_id always string
to_domain always string
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
422 Unprocessable Entity: rejected
500 Internal Server Error: internal

Field	Type
`domain` always	string
`domain_id` always	string
`to_domain` always	string

List the account's email filters

GET/api/v1/accounts/{id}/email/filters

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_filters
Operation: getAccountsIdEmailFilters · ky call getAccountsIdEmailFilters

Parameters

Name	In
`id`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Create an account email filter

POST/api/v1/accounts/{id}/email/filters

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_filters
Operation: postAccountsIdEmailFilters · ky call postAccountsIdEmailFilters

Parameters

Name	In
`id`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Reorder the account's email filters

PUT/api/v1/accounts/{id}/email/filters-order

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_filters
Operation: putAccountsIdEmailFiltersOrder · ky call putAccountsIdEmailFiltersOrder

Parameters

Name	In
`id`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Delete an account email filter

DELETE/api/v1/accounts/{id}/email/filters/{fid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_filters
Operation: deleteAccountsIdEmailFiltersFid · ky call deleteAccountsIdEmailFiltersFid

Parameters

Name	In
`id`	path
`fid`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Update an account email filter

PUT/api/v1/accounts/{id}/email/filters/{fid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_filters
Operation: putAccountsIdEmailFiltersFid · ky call putAccountsIdEmailFiltersFid

Parameters

Name	In
`id`	path
`fid`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

List forwarders

GET/api/v1/accounts/{id}/email/forwarders

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_forwarders
Operation: listForwarders · ky call listForwarders

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
domain_forwarders array of StoreDomainForward
items array of StoreForwarder
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`domain_forwarders`	array of StoreDomainForward
`items`	array of StoreForwarder

Add a forwarder

POST/api/v1/accounts/{id}/email/forwarders

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_forwarders
Operation: createForwarder · ky call createForwarder

Parameters

Name	In
`id`	path

Request body

Field	Type
`dest_type`	string
`destinations`	array of string
`domain_id`	string
`fail_message`	string
`local_part`	string

Responses

201 Created
Body
Field Type
items array of StoreForwarder
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
409 Conflict: validation
422 Unprocessable Entity: rejected
500 Internal Server Error: internal

Delete a forwarder

DELETE/api/v1/accounts/{id}/email/forwarders/{fid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_forwarders
Operation: deleteForwarder · ky call deleteForwarder

Parameters

Name	In
`id`	path
`fid`	path

Responses

204 Done, no content
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Email routing of every domain

GET/api/v1/accounts/{id}/email/routing

Who: root, reseller (ACL: edit-mx or create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_routing
Operation: listRouting · ky call listRouting

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
items array of Item
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Set a domain's email routing

PUT/api/v1/accounts/{id}/email/routing/{did}

Who: root, reseller (ACL: edit-mx or create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: email_routing
Operation: setRouting · ky call setRouting

Parameters

Name	In
`id`	path
`did`	path

Request body

Field	Type
`routing`	string

Responses

200 OK
Body
Field Type
domain string
domain_id string
routing string
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Get the spam filter settings

GET/api/v1/accounts/{id}/email/spam

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: spam_filters
Operation: getSpam · ky call getSpam

Parameters

Name	In
`id`	path

Responses

200 OK

Body

Field	Type
`allow_list`	array of string
`auto_delete`	boolean
`auto_delete_threshold`	number
`block_list`	array of string
`enabled`	boolean
`spam_box`	boolean
`subject_prefix`	string
`tag_subject`	boolean
`threshold`	number
`updated_at`	integer

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Save the spam filter settings

PUT/api/v1/accounts/{id}/email/spam

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: email
Feature: spam_filters
Operation: putSpam · ky call putSpam

Parameters

Name	In
`id`	path

Request body

Field	Type
`allow_list`	array of string
`auto_delete`	boolean
`auto_delete_threshold`	number
`block_list`	array of string
`enabled`	boolean
`spam_box`	boolean
`subject_prefix`	string
`tag_subject`	boolean
`threshold`	number
`updated_at`	integer

Responses

200 OK

Body

Field	Type
`allow_list`	array of string
`auto_delete`	boolean
`auto_delete_threshold`	number
`block_list`	array of string
`enabled`	boolean
`spam_box`	boolean
`subject_prefix`	string
`tag_subject`	boolean
`threshold`	number
`updated_at`	integer

400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
422 Unprocessable Entity: rejected
500 Internal Server Error: internal

Email deliverability of the server's hostname

GET/api/v1/server/mail/deliverability

Who: root
API tokens: admin token area: server
Operation: adminHostDeliverability · ky call adminHostDeliverability

Responses

200 OK
Body
Field Type
checked_at always integer
helo always string
hostname always string
ip always string
ok always boolean
records always array of HostingRecordCheck
zone_local string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Install the hostname's suggested email DNS records

POST/api/v1/server/mail/deliverability/repair

Who: root
API tokens: admin token area: server
Operation: adminHostDeliverabilityRepair · ky call adminHostDeliverabilityRepair

Request body

Field	Type
`kinds`	array of string

Responses

200 OK
Body
Field Type
repaired array of string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
409 Conflict: repair-failed

Track delivery on the whole server

GET/api/v1/server/mail/deliveries

Who: root
API tokens: admin token area: server
Operation: adminDeliveries · ky call adminDeliveries

Parameters

Name	In
`account_id`	query
`event`	query
`q`	query

Responses

200 OK
Body
Field Type
items array of StoreMailDelivery
retention_days integer
stats_24h map of integer
total integer
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Read new entries of the mail log now

POST/api/v1/server/mail/deliveries/refresh

Who: root
API tokens: admin token area: server
Operation: adminDeliveriesRefresh · ky call adminDeliveriesRefresh

Responses

200 OK
Body
Field Type
new_rows integer
400 Bad Request: rejected
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Hold outgoing mail of a domain or account

POST/api/v1/server/mail/holds

Who: root
API tokens: admin token area: server
Operation: adminHold · ky call adminHold

Request body

Field	Type
`account_id`	string
`reason`	string

Responses

201 Created
Body
Field Type
incident_id string
username string
400 Bad Request: rejected, validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Release held mail

DELETE/api/v1/server/mail/holds/{id}

Who: root
API tokens: admin token area: server
Operation: adminRelease · ky call adminRelease

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
resolved integer
400 Bad Request: rejected
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Outgoing mail limits and current counts

GET/api/v1/server/mail/limits

Who: root
API tokens: admin token area: server
Operation: adminMailLimits · ky call adminMailLimits

Responses

200 OK
Body
Field Type
held array of string
incidents array of StoreIncident
last_hour array of StoreSenderVolume
queue_count integer
settings HostingMailAdminSettings
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

List the mail queue

GET/api/v1/server/mail/queue

Who: root
API tokens: admin token area: server
Operation: adminQueue · ky call adminQueue

Parameters

Name	In
`q`	query
`server`	query
`state`	query

Responses

200 OK
Body
Field Type
items array of map of any
total integer
truncated boolean
400 Bad Request: rejected, wrong-server
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Get a queued message

GET/api/v1/server/mail/queue/{mid}

Who: root
API tokens: admin token area: server
Operation: adminQueueMessage · ky call adminQueueMessage

Parameters

Name	In
`mid`	path
`part`	query
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Deliver, freeze or delete queued messages

POST/api/v1/server/mail/queue/action

Who: root
API tokens: admin token area: server
Operation: adminQueueAction · ky call adminQueueAction

Parameters

Name	In
`server`	query

Request body

Field	Type
`action`	string
`ids`	array of string

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Mail routing of the server and its email nodes

GET/api/v1/server/mail/routing

Who: root
API tokens: admin token area: server
Operation: adminMailRouting · ky call adminMailRouting

Responses

200 OK
Body
Field Type
items array of StoreMailRoutingRow
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Save the mail server settings

PUT/api/v1/server/mail/settings

Who: root
API tokens: admin token area: server
Operation: adminMailSettings · ky call adminMailSettings

Request body

Field	Type
`auto_hold`	boolean
`default_max_per_hour`	integer
`retention_days`	integer
`unique_recipients_alert`	integer

Responses

200 OK
Body
Field Type
auto_hold boolean
default_max_per_hour integer
retention_days integer
unique_recipients_alert integer
400 Bad Request: rejected, validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Trace how an address would be delivered

POST/api/v1/server/mail/troubleshoot

Who: root
API tokens: admin token area: server
Operation: mailTroubleshoot · ky call mailTroubleshoot

Parameters

Name	In
`server`	query

Request body

Field	Type
`address`	string

Responses

200 OK
Body
map of any
400 Bad Request: rejected, validation, wrong-server
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`checked_at` always	integer
`helo` always	string
`hostname` always	string
`ip` always	string
`ok` always	boolean
`records` always	array of HostingRecordCheck
`zone_local`	string

Field	Type
`held`	array of string
`incidents`	array of StoreIncident
`last_hour`	array of StoreSenderVolume
`queue_count`	integer
`settings`	HostingMailAdminSettings

Email

#List mailboxes

Parameters

Responses

#Create a mailbox

Parameters

Request body

Responses

#Delete a mailbox

Parameters

Responses

#Change a mailbox's quota and restrictions

Parameters

Request body

Responses

#Mail client settings of a mailbox

Parameters

Responses

#Download the Apple mail profile

Parameters

Responses

#Change a mailbox's password

Parameters

Request body

Responses

#Open the webmail signed in

Parameters

Responses

#List autoresponders

Parameters

Responses

#Create an autoresponder

Parameters

Responses

#Delete an autoresponder

Parameters

Responses

#Update an autoresponder

Parameters

Responses

#List default addresses (catch-all)

Parameters

Responses

#Set a domain's default address

Parameters

Request body

Responses

#Email deliverability of every domain

Parameters

Responses

#Email deliverability of a domain (SPF, DKIM, DMARC, PTR)

Parameters

Responses

#Install the suggested email DNS records

Parameters

Request body

Responses

#Customize and install the SPF record

Parameters

Request body

Responses

#Track delivery of the account's mail

Parameters

Responses

#Remove a domain forwarder

Parameters

Responses

#Forward a whole domain

Parameters

Request body

Responses

#List the account's email filters

Parameters

Responses

#Create an account email filter

Parameters

Responses

#Reorder the account's email filters

Parameters

Responses

List mailboxes

Create a mailbox

Delete a mailbox

Change a mailbox's quota and restrictions

Mail client settings of a mailbox

Download the Apple mail profile

Change a mailbox's password

Open the webmail signed in

List autoresponders

Create an autoresponder

Delete an autoresponder

Update an autoresponder

List default addresses (catch-all)

Set a domain's default address

Email deliverability of every domain

Email deliverability of a domain (SPF, DKIM, DMARC, PTR)

Install the suggested email DNS records

Customize and install the SPF record

Track delivery of the account's mail

Remove a domain forwarder

Forward a whole domain

List the account's email filters

Create an account email filter

Reorder the account's email filters

Delete an account email filter

Update an account email filter

List forwarders

Add a forwarder

Delete a forwarder

Email routing of every domain

Set a domain's email routing

Get the spam filter settings

Save the spam filter settings

Email deliverability of the server's hostname

Install the hostname's suggested email DNS records

Track delivery on the whole server

Read new entries of the mail log now

Hold outgoing mail of a domain or account

Release held mail

Outgoing mail limits and current counts

List the mail queue

Get a queued message

Deliver, freeze or delete queued messages

Mail routing of the server and its email nodes

Save the mail server settings

Trace how an address would be delivered