cPanel UAPI

WebPros International, LLC: [email protected] URL: https://cpanel.net/support/ License: cPanel License Terms of Service

UAPI accesses the cPanel interface's features. Use this API to access and modify cPanel account data and settings.

API Token Management

API Development Tools / API Token Management

Create cPanel API token

This function creates a new API token with full access to all of a cPanel account's features.

Note:

The token only grants access to the features that the account has access to. For example, if you disable the File Manager feature, the token can't access it.

Authorizations:

BasicAuth

query Parameters

expires_at	integer <unix_timestamp> Example: expires_at=1609372800 The API token's expiration time. Important: When an API token expires the system does not delete it. You must manually delete expired API tokens. If you do not use this parameter, the API token will not expire.
name required	string <= 50 characters Example: name=example The API token's name. Note: The name may only contain alphanumeric characters, dashes (`-`), and underscores (`_`).

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Tokens \
  create_full_access \
  name='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_full_access",
"module": "Tokens",
"result": {"data": {"create_time": 1549467298,
"token": "JPQNSRU0DH448UJLGXH7KVJECC5QN9N9"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel API tokens

This function returns a list of a cPanel account's API tokens.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Tokens \
  list

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list",
"module": "Tokens",
"result": {"data": [{"create_time": 1549471343,
"expires_at": 1609372800,
"features": [ ],
"has_full_access": 1,
"name": "exampletoken"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update cPanel API token's name

This function renames a cPanel account's existing API token.

Authorizations:

BasicAuth

query Parameters

name required	string Example: name=example The API token's name.
new_name required	string <= 50 characters Example: new_name=newexample The new name for the API token. Note: The name may only contain alphanumeric characters, dashes (`-`), and underscores (`_`).

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Tokens \
  rename \
  name='example' \
  new_name='newexample'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rename",
"module": "Tokens",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove cPanel API token

This function removes an API token from a cPanel account.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=example

The API token to remove.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Tokens \
  revoke \
  name='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "revoke",
"module": "Tokens",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Batch

The Batch module for UAPI.

Run multiple UAPI functions in order

This function combines calls for multiple UAPI functions and performs them in order.

Note:

If a function call in the list fails, the Batch::strict function does not run further function calls in the list.
Due to the potential length of calls of this function, we recommend that you use the HTTP POST method for extremely long batch commands.

Authorizations:

BasicAuth

query Parameters

required

Array of strings or objects [ 2 .. 3 ] items

A UAPI function call, encoded as a JSON array with two or three items:

The UAPI module.
The UAPI function.
A JSON object containing the parameters to pass to this function. You can omit this value if you do not pass any parameters to the function.

To submit multiple commands, duplicate the parameter name, or index all parameter names and increment the index for each one.

When using the cPanel LiveAPI PHP Library, you must increment the parameter name when you submit the arguments in an associative array. For example: use command-0, command-1, and command-2.
When using the cPanel LiveAPI Perl Library, you must increment the parameter name when you submit the arguments in a hash. For example: use command-0, command-1, and command-2.
You do not need to add an index to command parameters for query string calls of this function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username Batch strict command-0='[ "PasswdStrength", "get_required_strength", { "app": "webdisk"} ]' command-1='["SSH","get_port"]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "strict",
"module": "Batch",
"result": {"data": [{"data": {"strength": 65
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
},
{"data": {"port": 22
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

SSE Task Management

API Development Tools / SSE Task Management

Remove item from task queue

This function deletes a process from the user task queue.

Each cPanel account uses a separate user task queue in order to ensure that processes for one user do not impede another user on the server.

For example, the Git Version Control interface (cPanel >> Home >> Files >> Git Version Control) uses the user task queue to clone repositories (via the VersionControl::create function).
For more information, read our Task Queue Monitor documentation.

Authorizations:

BasicAuth

query Parameters

id

required

string

Example: id=00000000\/5a9ec8dd4c345d

The task's ID number.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username UserTasks delete id='00000000\/5a9ec8dd4c345d'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete",
"module": "UserTasks",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return task queue information

This function retrieves a cPanel account's user task queue information.

Each cPanel account uses a separate user task queue in order to ensure that processes for one user do not impede another user on the server.

For example, the Git Version Control interface (cPanel >> Home >> Files >> Git Version Control) uses the user task queue to clone repositories (via the VersionControl::create function).
For more information, read our Task Queue Monitor documentation.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserTasks \
  retrieve

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "retrieve",
"module": "UserTasks",
"result": {"data": [{"action": "create",
"args": { },
"id": "00000000\\/5a9ec8dd4c345d",
"subsystem": "VersionControl"
},
{"action": "create",
"args": {"repository_root": "/home/user/public_html/example"
},
"id": "00000000/h39dnn27suc13l",
"subsystem": "VersionControl"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

URL Parsing

API Development Tools / URL Parsing

Return integrated application URL

This function returns the URL for an integrated application.

Authorizations:

BasicAuth

query Parameters

app

required

string

Example: app=applicationname

The application's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Integration \
  fetch_url \
  app='applicationname'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_url",
"module": "Integration",
"result": {"data": {"redirect_url": "http://application.example.com/application",
"url": "http://application.example.com/"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return session relative URI

This function reports the first file's URI, relative to the cPanel base directory.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Parser \
  firstfile_relative_uri

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "firstfile_relative_uri",
"module": "Parser",
"result": {"data": {"uri": "/usr/local/cpanel/base/favicon.ico"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

External Authentication

Authentication / External Authentication

Add external authentication link

This function adds an External Authentication authorization link to an account.

Authorizations:

BasicAuth

query Parameters

preferred_username required	string Example: preferred_username=Example The preferred username of the account on the identity provider.
provider_id required	string Example: provider_id=google The name of the identity provider.
subject_unique_identifier required	string Example: subject_unique_identifier=123456789012345678901 The unique identifier for the user at the identity provider.
username required	string <username> Example: username=example The username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ExternalAuthentication \
  add_authn_link \
  username='example' \
  provider_id='google' \
  subject_unique_identifier='123456789012345678901' \
  preferred_username='Example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_authn_link",
"module": "ExternalAuthentication",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return server's external authentication providers

This function lists the display information for your server's available and configured external authentication identity provider modules.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ExternalAuthentication \
  configured_modules

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "configured_modules",
"module": "ExternalAuthentication",
"result": {"data": [{"color": "00aef0",
"display_name": "cPanel ID",
"documentation_url": "https://go.cpanel.net/OpenIDConnect",
"icon": "iVBORw0KGgoAAAANSUhEUgAAACMAAAAhCAYAAABTERJSAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDoxMTNFRUVGMzIyODUxMUU1OUM1RERGODcwRjIwNTQ4MCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDoxMTNFRUVGNDIyODUxMUU1OUM1RERGODcwRjIwNTQ4MCI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOjExM0VFRUYxMjI4NTExRTU5QzVEREY4NzBGMjA1NDgwIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOjExM0VFRUYyMjI4NTExRTU5QzVEREY4NzBGMjA1NDgwIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+oa0v2AAAA3VJREFUeNrsWM1uFEcQruqent3Z9Y43DmuD2YT1LoIICSIgEULKC+SaF8gr5JAnyD3XKCcChxxyyhNYiFMU5ZRTzE8UuGCQY8DGeGd3Zqrydc/ajiWjBHCEpWxLPf1T01VfV/d09TesqnRUUuQfN+5tUzMylAsRM9EOPlTJV0V9qWQg3BgLXek4+mUtpxKy+bqhAvIcLxVSlT4FHVAQITegO7Z8vGFpqeW4P+N40Iy434rNR23Hcd3ymV0wL00TNIJH6UsY2syVsrICuTlWGFJyAJlYrtVj7jUi9gZhzPQSS4tJRO+1nF1C/aThoHFfgp7n+zzjZ+GNjUWDB7yHRPYAQQnV8MCMOu04ughvPEbzztV599UHbXvOGe7OwHhsKH3jZdrKiZwhgrtcYs0ilJ6A4ffhytMpZtmAa/3s4OYuQFhg/m75IX1xtm2/XKjbw90zn3Zr19+p81W4dr5mqP0vxslkOx3+Bu6n9jOsROttf02GjlCagpmCmYI5VDD8GuP0tYYdHP72HXq3N4prTcfHEA6ev8ir2OSjLwK0jkvRoRAjNmlkFG1aGAktPxrK6NZq/o3lwh1POPtkIQ4ncqm7Y2lcqua4o4zKKr4h66ggLrSSo2zinfUrnXgPzM9r+c0P51wySE22NhTBNUEQnVGqbuZSrm6LXJhzMkit/JmVdfT/vl1QcXej+H4r91cLyrtNW/ZmrG4AydORytMRyrHXpfJgq5TL70Zy+Vgs97JCnwS5yhOgRD3fAUP+coW8qa+Q4Kxr3/72Il0dFqEtPsuubLctupdflqSyHXBEkzvFq26AfYGS/7b4hg/YDNNPewpmCuZ/DwYn5I/rI7mLY/7ZW2eUy6ujz/0ZBZoSz8a8CB50ohkRqIo57QkZiNhS6mw/qaiKwYHmySXzfwGmorZKw1LGOjb3s7K8r8o/CRXhIPXZU9Sa5Q441aVByz5CoMtXnpVfyyydQ4DtQt4DzXkjhsE+JvzwRxZ4smeToKehHpgtVzxbAuPUwDwR2Oj8XES/rueB5nbqDJCeBJo6xvZmQG8bEQ1mY3Mqifgk+jzb9H3dgzzp6S3603/m2hOv+OwmRDnFTQHLFdaphWAL8h68mpWSbRW08lBoxf8I8IQfohCrEu9VLD1Yqmel/TQOSz5oxfzxrDN2h5TyUfolcqQ+7b8EGACd0Ob6pUnq9QAAAABJRU5ErkJggg==",
"icon_type": "image/svg+xml",
"label": "Log in with a cPanel ID Account",
"link": "https://hostname.example.com:2083/openid_connect/cpanelid",
"provider_name": "cpanelid",
"textcolor": "FFFFFF"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return external authentication user status

This function determines whether the user enabled external authentication modules.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ExternalAuthentication \
  has_external_auth_modules_configured

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_external_auth_modules_configured",
"module": "ExternalAuthentication",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove external authentication link

This function removes a link to an account at an external authentication identity provider.

Authorizations:

BasicAuth

query Parameters

provider required	string Example: provider=cpanelid The name of the identity provider.
subject_unique_identifier required	string Example: subject_unique_identifier=123456789012345678901 The unique identifier for the user at the identity provider.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ExternalAuthentication \
  remove_authn_link \
  provider='cpanelid' \
  subject_unique_identifier='123456789012345678901'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_authn_link",
"module": "ExternalAuthentication",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return external authentication links

This function lists the external authentication links to the current cPanel account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ExternalAuthentication \
  get_authn_links

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_authn_links",
"module": "ExternalAuthentication",
"result": {"data": [{"link_time": 1443124604,
"preferred_username": "[email protected]",
"provider_id": "google",
"provider_protocol": "openid_connect",
"subject_unique_identifier": 123456789012346
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Two-Factor Settings

Authentication / Two-Factor Settings

Create 2FA authentication code

This function generates an authentication code to enable configuration of two-factor authentication.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  TwoFactorAuth \
  generate_user_configuration

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "generate_user_configuration",
"module": "TwoFactorAuth",
"result": {"data": {"otpauth_str": "otpauth://totp/Example%20cPanel%20L.L.C.:fakedomain?secret=S3I4WUY7MTHRMMWN&issuer=Example%20cPanel%20L.L.C.",
"secret": "S3I4WUY7MTHRMMWN"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return team user 2FA config

This function retrieves a team user's configuration settings for two-factor authentication.

Authorizations:

BasicAuth

query Parameters

team_user

required

string

Example: [email protected]

The team user's username.

Note:

The username will always precede the cPanel account's primary domain.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  TwoFactorAuth \
  get_team_user_configuration \
  team_user=teamuser

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_team_user_configuration",
"module": "TwoFactorAuth",
"result": {"data": {"is_enabled": 1,
"issuer": "Example WebPros International, LLC"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account 2FA config

This function retrieves the cPanel account user's configuration settings for two-factor authentication.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  TwoFactorAuth \
  get_user_configuration

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_user_configuration",
"module": "TwoFactorAuth",
"result": {"data": {"is_enabled": 1,
"issuer": "Example WebPros International, LLC"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove 2FA config

This function removes the user from the two-factor authentication userdata file.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  TwoFactorAuth \
  remove_user_configuration

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_user_configuration",
"module": "TwoFactorAuth",
"result": {"data": {"tfa_removed": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Save 2FA config

This function configures the two-factor authentication settings for an account.

Authorizations:

BasicAuth

query Parameters

secret required	string <= 16 characters Example: secret=JBSWY3DPEHPK3PXP The 16-character string that UAPI's `TwoFactorAuth::generate_user_configuration` function generates.
tfa_token required	integer <= 6 characters Example: tfa_token=528112 The six-digit security code that the time-based one-time password (TOTP) authentication app generates.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  TwoFactorAuth \
  set_user_configuration \
  secret='JBSWY3DPEHPK3PXP' \
  tfa_token='528112'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_user_configuration",
"module": "TwoFactorAuth",
"result": {"data": {"tfa_configured": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Block IP

Block Ip Addresses / Block IP

Add IP address to cPanel account's block list

This function blocks IP addresses from accessing the domains on a cPanel account.

Important

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

ip

required

string

Examples:

ip=192.168.0.1/16 - CIDR Format IPv4
ip=2001:db8::/32 - CIDR Format IPv6
ip=example.com - Add by resolving hostname
ip=192.168.0.1-58 - Implied Range
ip=192.168.0.1-192.168.0.58 - IPv4 Range
ip=2001:db8::1-2001:db8::3 - IPv6 Range
ip=192.0.2.0 - Single IPv4 Address
ip=2001:db8::1 - Single IPv6 Address
ip=10. - Subnet Range - Matches 10.*.*.*

The IP address or IP address range that you wish to block.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BlockIP \
  add_ip \
  ip='192.168.0.1/16'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_ip",
"module": "BlockIP",
"result": {"data": ["1.1.1.1"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Remove IP address from cPanel account's block list

This function unblocks IP addresses from accessing domains on a cPanel account.

Important

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

ip

required

string

Examples:

ip=192.168.0.1/16 - CIDR Format IPv4
ip=2001:db8::/32 - CIDR Format IPv6
ip=example.com - Add by resolving hostname
ip=192.168.0.1-58 - Implied Range
ip=192.168.0.1-192.168.0.58 - IPv4 Range
ip=2001:db8::1-2001:db8::3 - IPv6 Range
ip=192.0.2.0 - Single IPv4 Address
ip=2001:db8::1 - Single IPv6 Address
ip=10. - Subnet Range - Matches 10.*.*.*

The IP address or IP address range that you wish to unblock.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BlockIP \
  remove_ip \
  ip='192.168.0.1/16'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_ip",
"module": "BlockIP",
"result": {"data": ["1.1.1.1"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Market Integration

Commerce Integration / Market Integration

Return provider's available products

This function lists all products available through all enabled cPanel Market providers.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_all_products

Response samples

200

Content type

application/json

product_group=ssl_certificate

{"apiversion": 3,
"func": "get_all_products",
"module": "Market",
"result": {"data": [{"base_name": "",
"billing_type": "one-time",
"description": "An extended-validated (EV) SSL certificate signed by COMODO.",
"display_name": "Comodo EV SSL Certificate",
"enabled": 1,
"icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
"icon_mime_type": "image/svg+xml",
"license_term": 0,
"max_users": null,
"maximum_server_price": null,
"minimum_server_price": null,
"price": null,
"price_unit": "USD",
"product": "Comodo EV Certificate",
"product_category": "N/A",
"product_group": "ssl_certificate",
"product_id": 155,
"provider_display_name": "cPanel Store",
"provider_name": "cPStore",
"recommended": 0,
"requires_ip": 0,
"x_certificate_term": [1,
"year"
],
"x_identity_verification": [{"label": "Organization Name",
"name": "organizationName"
},
{"is_optional": 1,
"label": "Department Name",
"name": "organizationalUnitName"
},
{"description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
"is_optional": 1,
"label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
"name": "duns_number",
"pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
},
{"label": "Street Address",
"name": "streetAddress"
},
{"label": "City",
"name": "localityName"
},
{"label": "State or Province",
"name": "stateOrProvinceName"
},
{"label": "Postal Code",
"name": "postalCode"
},
{"label": "Country Code",
"name": "countryName",
"type": "country_code"
},
{"label": "Representative’s Given (First) Name",
"name": "rep_forename"
},
{"label": "Representative’s Surname (Last Name)",
"name": "rep_surname"
},
{"label": "Representative’s Email Address",
"name": "rep_email_address",
"type": "email"
},
{"description": "This should be one of the organization’s publicly-listed telephone numbers.",
"is_optional": 1,
"label": "Representative’s Telephone Number",
"name": "rep_telephone",
"type": "tel"
},
{"description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
"label": "Business Category",
"name": "business_category",
"options": [["b",
"Incorporated Business (“Private Organization”)"
],
["d",
"Non-incorporated Business (“Business Entity”)"
],
["c",
"Government Entity (“Government Entity”)"
]
],
"type": "choose_one"
},
{"is_optional": 1,
"label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
"name": "joi_locality_name"
},
{"is_optional": 1,
"label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
"name": "joi_state_or_province_name"
},
{"label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
"name": "joi_country_name",
"type": "country_code"
},
{"is_optional": 1,
"label": "Date of Incorporation",
"name": "date_of_incorporation",
"type": "date"
},
{"is_optional": 1,
"label": "Assumed Name (DBA (Doing Business As))",
"name": "assumed_name"
}
],
"x_max_http_redirects": 0,
"x_payment_trigger": "checkout",
"x_price_per_domain": 108,
"x_price_per_domain_maximum": 1080,
"x_price_per_domain_minimum": 108,
"x_ssl_per_domain_pricing": 1,
"x_supports_dns_dcv": 1,
"x_validation_type": "ev",
"x_warn_after": 604800
},
{"base_name": "",
"billing_type": "one-time",
"description": "An organization-validated (OV) SSL certificate signed by COMODO.",
"display_name": "Comodo OV SSL Certificate",
"enabled": 1,
"icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
"icon_mime_type": "image/svg+xml",
"license_term": 0,
"max_users": null,
"maximum_server_price": null,
"minimum_server_price": null,
"price": null,
"price_unit": "USD",
"product": "Comodo OV Certificate",
"product_category": "N/A",
"product_group": "ssl_certificate",
"product_id": 217,
"provider_display_name": "cPanel Store",
"provider_name": "cPStore",
"recommended": 0,
"requires_ip": 0,
"x_certificate_term": [1,
"year"
],
"x_identity_verification": [{"label": "Organization Name",
"name": "organizationName"
},
{"is_optional": 1,
"label": "Department Name",
"name": "organizationalUnitName"
},
{"description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
"is_optional": 1,
"label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
"name": "duns_number",
"pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
},
{"label": "Street Address",
"name": "streetAddress"
},
{"label": "City",
"name": "localityName"
},
{"label": "State or Province",
"name": "stateOrProvinceName"
},
{"label": "Postal Code",
"name": "postalCode"
},
{"label": "Country Code",
"name": "countryName",
"type": "country_code"
},
{"label": "Representative’s Given (First) Name",
"name": "rep_forename"
},
{"label": "Representative’s Surname (Last Name)",
"name": "rep_surname"
},
{"label": "Representative’s Email Address",
"name": "rep_email_address",
"type": "email"
},
{"description": "This should be one of the organization’s publicly-listed telephone numbers.",
"is_optional": 1,
"label": "Representative’s Telephone Number",
"name": "rep_telephone",
"type": "tel"
}
],
"x_max_http_redirects": 0,
"x_payment_trigger": "checkout",
"x_price_per_domain": 36,
"x_price_per_domain_maximum": 360,
"x_price_per_domain_minimum": 36,
"x_price_per_wildcard_domain": "150.00",
"x_price_per_wildcard_domain_maximum": "1500.00",
"x_price_per_wildcard_domain_minimum": "150.00",
"x_ssl_per_domain_pricing": 1,
"x_supports_dns_dcv": 1,
"x_validation_type": "ov",
"x_warn_after": 604800,
"x_wildcard_parent_domain_free": 1
},
{"base_name": "",
"billing_type": "one-time",
"description": "A domain-validated (DV) SSL certificate signed by cPanel.",
"display_name": "cPanel DV SSL Certificate",
"enabled": 1,
"icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
"icon_mime_type": "image/svg+xml",
"license_term": 0,
"max_users": null,
"maximum_server_price": null,
"minimum_server_price": null,
"price": null,
"price_unit": "USD",
"product": "cPanel DV Certificate",
"product_category": "N/A",
"product_group": "ssl_certificate",
"product_id": 159,
"provider_display_name": "cPanel Store",
"provider_name": "cPStore",
"recommended": 0,
"requires_ip": 0,
"x_certificate_term": [1,
"year"
],
"x_identity_verification": null,
"x_max_http_redirects": 0,
"x_payment_trigger": "issuance",
"x_price_per_domain": 9,
"x_price_per_domain_maximum": 30,
"x_price_per_domain_minimum": 3,
"x_price_per_wildcard_domain": "75.00",
"x_price_per_wildcard_domain_maximum": "750.00",
"x_price_per_wildcard_domain_minimum": "75.00",
"x_ssl_per_domain_pricing": 1,
"x_supports_dns_dcv": 1,
"x_validation_type": "dv",
"x_warn_after": 604800,
"x_wildcard_parent_domain_free": 1
},
{"base_name": "",
"billing_type": "one-time",
"description": "An organization-validated (OV) SSL certificate signed by cPanel.",
"display_name": "cPanel OV SSL Certificate",
"enabled": 1,
"icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
"icon_mime_type": "image/svg+xml",
"license_term": 0,
"max_users": null,
"maximum_server_price": null,
"minimum_server_price": null,
"price": null,
"price_unit": "USD",
"product": "cPanel OV Certificate",
"product_category": "N/A",
"product_group": "ssl_certificate",
"product_id": 213,
"provider_display_name": "cPanel Store",
"provider_name": "cPStore",
"recommended": 0,
"requires_ip": 0,
"x_certificate_term": [1,
"year"
],
"x_identity_verification": [{"label": "Organization Name",
"name": "organizationName"
},
{"is_optional": 1,
"label": "Department Name",
"name": "organizationalUnitName"
},
{"description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
"is_optional": 1,
"label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
"name": "duns_number",
"pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
},
{"label": "Street Address",
"name": "streetAddress"
},
{"label": "City",
"name": "localityName"
},
{"label": "State or Province",
"name": "stateOrProvinceName"
},
{"label": "Postal Code",
"name": "postalCode"
},
{"label": "Country Code",
"name": "countryName",
"type": "country_code"
},
{"label": "Representative’s Given (First) Name",
"name": "rep_forename"
},
{"label": "Representative’s Surname (Last Name)",
"name": "rep_surname"
},
{"label": "Representative’s Email Address",
"name": "rep_email_address",
"type": "email"
},
{"description": "This should be one of the organization’s publicly-listed telephone numbers.",
"is_optional": 1,
"label": "Representative’s Telephone Number",
"name": "rep_telephone",
"type": "tel"
}
],
"x_max_http_redirects": 0,
"x_payment_trigger": "checkout",
"x_price_per_domain": 30,
"x_price_per_domain_maximum": 300,
"x_price_per_domain_minimum": 30,
"x_price_per_wildcard_domain": "99.00",
"x_price_per_wildcard_domain_maximum": "990.00",
"x_price_per_wildcard_domain_minimum": "99.00",
"x_ssl_per_domain_pricing": 1,
"x_supports_dns_dcv": 1,
"x_validation_type": "ov",
"x_warn_after": 604800,
"x_wildcard_parent_domain_free": 1
},
{"base_name": "",
"billing_type": "one-time",
"description": "A domain-validated (DV) SSL certificate signed by COMODO.",
"display_name": "Comodo DV SSL Certificate",
"enabled": 1,
"icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNTUwIiB3aWR0aD0iNDE3LjE2Ij48ZyBmaWxsPSIjMzViNTZjIj48cGF0aCBkPSJNNDE0LjM5NiAyNmM3LTExIDAtMjYtMTMtMjZIMTg3LjM5NWMtNDUgMC04MSAxMi0xMDcgMzZzLTQyIDU4LTQ2IDEwM2wtMTAgMTE2Yy00IDQ1IDUgNzkgMjggMTAzIDIyIDI0IDU2IDM2IDEwMSAzNmg0OXYtMWM5LjAwMS0xIDE1LjAwMS03IDE2LjAwMS0xN2w1LTU3YzAtMTEtNy0xOS0xOC4wMDEtMTloLTI3Yy0xNyAwLTMwLTQtMzctMTItNy03LTEwLTIwLTgtMzlsOS0xMDRjMi0xOCA3LTMxIDE1LTM5czIxLTEyIDM5LTEyaDE0NC4wMDFjMTcgMCAzNC05IDQ0LTIzbDMwLTQ1Ii8+PHBhdGggZD0iTTMuMzk1IDUyNGMtOCAxMS0xIDI2IDEyIDI2aDIxNy4wMDFjNDUgMCA4MS0xMiAxMDgtMzYgMjYtMjQgNDEtNTggNDUtMTAybDExLTExN2MzLTQ1LTYtNzktMjgtMTAzLTIzLTI0LTU2LTM2LTEwMS0zNmgtNDl2MWMtMTAuMDAxIDEtMTUuMDAxIDctMTYuMDAxIDE3bC01IDU4Yy0xIDEwIDcgMTggMTcuMDAxIDE4aDI3YzE4IDAgMzAgNCAzNyAxMnMxMCAyMSA5IDM5bC0xMCAxMDRjLTEgMTktNiAzMi0xNCAzOS05IDgtMjIgMTItNDAgMTJINzYuMzk1Yy0xNyAwLTMzIDktNDMgMjRsLTMwIDQ0Ii8+PC9nPjwvc3ZnPg==",
"icon_mime_type": "image/svg+xml",
"license_term": 0,
"max_users": null,
"maximum_server_price": null,
"minimum_server_price": null,
"price": null,
"price_unit": "USD",
"product": "Comodo DV Certificate",
"product_category": "N/A",
"product_group": "ssl_certificate",
"product_id": 151,
"provider_display_name": "cPanel Store",
"provider_name": "cPStore",
"recommended": 0,
"requires_ip": 0,
"x_certificate_term": [1,
"year"
],
"x_identity_verification": null,
"x_max_http_redirects": 0,
"x_payment_trigger": "issuance",
"x_price_per_domain": 12,
"x_price_per_domain_maximum": 120,
"x_price_per_domain_minimum": 12,
"x_price_per_wildcard_domain": "99.00",
"x_price_per_wildcard_domain_maximum": "990.00",
"x_price_per_wildcard_domain_minimum": "99.00",
"x_ssl_per_domain_pricing": 1,
"x_supports_dns_dcv": 1,
"x_validation_type": "dv",
"x_warn_after": 604800,
"x_wildcard_parent_domain_free": 1
},
{"base_name": "",
"billing_type": "one-time",
"description": "An extended-validated (EV) SSL certificate signed by cPanel.",
"display_name": "cPanel EV SSL Certificate",
"enabled": 1,
"icon": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNTlwdCIgaGVpZ2h0PSIzMjAiIHZpZXdCb3g9IjAgMCAzNTkgMjQwIj48ZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjxwYXRoIGQ9Ik0xMjMgMGgyMzUuMzd2MjQwSDEyM3ptMCAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PHBhdGggZD0iTTg5LjY5IDU5LjEwMmg2Ny44MDJsLTEwLjUgNDAuMmMtMS42MDUgNS42LTQuNjA1IDEwLjEtOSAxMy41LTQuNDAyIDMuNC05LjUwNCA1LjA5Ni0xNS4zIDUuMDk2aC0zMS41Yy03LjIgMC0xMy41NSAyLjEwMi0xOS4wNSA2LjMtNS41MDUgNC4yLTkuMzUzIDkuOTA0LTExLjU1MiAxNy4xMDMtMS40IDUuNDAzLTEuNTUgMTAuNS0uNDUgMTUuMzAyIDEuMDk4IDQuNzk2IDMuMDQ3IDkuMDUgNS44NTIgMTIuNzUgMi43OTcgMy43MDMgNi40IDYuNjUyIDEwLjc5NyA4Ljg1IDQuMzk3IDIuMiA5LjE5OCAzLjI5OCAxNC40IDMuMjk4aDE5LjJjMy42MDIgMCA2LjU0NyAxLjQ1MyA4Ljg1MiA0LjM1MiAyLjI5NyAyLjkwMiAyLjk0NSA2LjE0OCAxLjk1IDkuNzVsLTEyIDQ0LjM5OGgtMjFjLTE0LjQwMyAwLTI3LjY1My0zLjE0OC0zOS43NS05LjQ1LTEyLjEwMi02LjMtMjIuMTUzLTE0LjY0OC0zMC4xNTMtMjUuMDUtOC0xMC4zOTUtMTMuNDU0LTIyLjI0Ni0xNi4zNS0zNS41NDctMi45LTEzLjMtMi41NS0yNi45NSAxLjA1Mi00MC45NTNsMS4yLTQuNWMyLjU5Ny05LjYwMiA2LjY0OC0xOC40NSAxMi4xNDgtMjYuNTUgNS41LTguMDk4IDEyLTE1IDE5LjUtMjAuNyA3LjUtNS43IDE1Ljg1LTEwLjE0OCAyNS4wNS0xMy4zNTIgOS4yLTMuMTk1IDE4Ljc5Ny00Ljc5NiAyOC44LTQuNzk2IiBmaWxsPSIjZmY2YzJjIi8+PGcgY2xpcC1wYXRoPSJ1cmwoI2EpIj48cGF0aCBkPSJNMTIzLjg5IDI0MEwxODIuOTkgMTguNjAyYzEuNTk4LTUuNTk4IDQuNTk4LTEwLjA5OCA5LTEzLjVDMTk2LjM4OCAxLjcgMjAxLjQ4NCAwIDIwNy4yODggMGg2Mi43YzE0LjQwMyAwIDI3LjY1IDMuMTQ4IDM5Ljc1IDkuNDUgMTIuMTAyIDYuMyAyMi4xNTMgMTQuNjU1IDMwLjE1MyAyNS4wNSA3Ljk5NyAxMC40MDIgMTMuNSAyMi4yNTQgMTYuNSAzNS41NSAzIDEzLjMwNSAyLjU5NCAyNi45NTQtMS4yMDIgNDAuOTVsLTEuMiA0LjVjLTIuNTk3IDkuNjAyLTYuNTk3IDE4LjQ1LTEyIDI2LjU1LTUuMzk4IDguMDk4LTExLjg0NyAxNS4wNTItMTkuMzQ3IDIwLjg0OC03LjUgNS44MDUtMTUuODU1IDEwLjMwNS0yNS4wNSAxMy41LTkuMiAzLjIwNC0xOC44MDUgNC44MDUtMjguODA1IDQuODA1aC01NC4yOTdsMTAuOC00MC41YzEuNi01LjQwMiA0LjYtOS44IDktMTMuMjAzIDQuMzk2LTMuMzk4IDkuNDk3LTUuMTAyIDE1LjMwMi01LjEwMmgxNy4zOThjNy4yIDAgMTMuNjUzLTIuMiAxOS4zNTItNi41OTcgNS42OTUtNC4zOTggOS40NDUtMTAuMDk3IDExLjI1LTE3LjEgMS4zOTQtNC45OTcgMS41NDctOS45LjQ0NS0xNC43LTEuMS00LjgtMy4wNS05LjA0Ny01Ljg0OC0xMi43NS0yLjgtMy42OTUtNi40MDItNi42OTUtMTAuNzk2LTktNC40MDYtMi4yOTctOS4yMDYtMy40NS0xNC40MDItMy40NUgyMzMuMzlsLTQzLjggMTYyLjkwM2MtMS42MDYgNS40LTQuNjA2IDkuNzk3LTkgMTMuMTk1LTQuNDAzIDMuNDA3LTkuNDA2IDUuMTAyLTE1IDUuMTAyaC00MS43IiBmaWxsPSIjZmY2YzJjIi8+PC9nPjwvc3ZnPgo=",
"icon_mime_type": "image/svg+xml",
"license_term": 0,
"max_users": null,
"maximum_server_price": null,
"minimum_server_price": null,
"price": null,
"price_unit": "USD",
"product": "cPanel EV Certificate",
"product_category": "N/A",
"product_group": "ssl_certificate",
"product_id": 209,
"provider_display_name": "cPanel Store",
"provider_name": "cPStore",
"recommended": 0,
"requires_ip": 0,
"x_certificate_term": [1,
"year"
],
"x_identity_verification": [{"label": "Organization Name",
"name": "organizationName"
},
{"is_optional": 1,
"label": "Department Name",
"name": "organizationalUnitName"
},
{"description": "9 consecutive digits or “##-###-####” (More information (https://go.cpanel.net/get_duns))",
"is_optional": 1,
"label": "Dun & Bradstreet D-U-N-S (Data Universal Numbering System) Number",
"name": "duns_number",
"pattern": "^[0-9]{2}(?:-[0-9]{3}-[0-9]{4}|[0-9]{7})$"
},
{"label": "Street Address",
"name": "streetAddress"
},
{"label": "City",
"name": "localityName"
},
{"label": "State or Province",
"name": "stateOrProvinceName"
},
{"label": "Postal Code",
"name": "postalCode"
},
{"label": "Country Code",
"name": "countryName",
"type": "country_code"
},
{"label": "Representative’s Given (First) Name",
"name": "rep_forename"
},
{"label": "Representative’s Surname (Last Name)",
"name": "rep_surname"
},
{"label": "Representative’s Email Address",
"name": "rep_email_address",
"type": "email"
},
{"description": "This should be one of the organization’s publicly-listed telephone numbers.",
"is_optional": 1,
"label": "Representative’s Telephone Number",
"name": "rep_telephone",
"type": "tel"
},
{"description": "Consult the EV SSL Certificate Guidelines (https://cabforum.org/extended-validation/) for more information about this field’s options.",
"label": "Business Category",
"name": "business_category",
"options": [["b",
"Incorporated Business (“Private Organization”)"
],
["d",
"Non-incorporated Business (“Business Entity”)"
],
["c",
"Government Entity (“Government Entity”)"
]
],
"type": "choose_one"
},
{"is_optional": 1,
"label": "City Where Incorporated (JOI (Jurisdiction of Incorporation))",
"name": "joi_locality_name"
},
{"is_optional": 1,
"label": "State or Province Where Incorporated (JOI (Jurisdiction of Incorporation))",
"name": "joi_state_or_province_name"
},
{"label": "Country Code Where Incorporated (JOI (Jurisdiction of Incorporation))",
"name": "joi_country_name",
"type": "country_code"
},
{"is_optional": 1,
"label": "Date of Incorporation",
"name": "date_of_incorporation",
"type": "date"
},
{"is_optional": 1,
"label": "Assumed Name (DBA (Doing Business As))",
"name": "assumed_name"
}
],
"x_max_http_redirects": 0,
"x_payment_trigger": "checkout",
"x_price_per_domain": 60,
"x_price_per_domain_maximum": 600,
"x_price_per_domain_minimum": 60,
"x_ssl_per_domain_pricing": 1,
"x_supports_dns_dcv": 1,
"x_validation_type": "ev",
"x_warn_after": 604800
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create shopping cart

This function creates a shopping cart with which the system sends an order to the cPanel Store. Typically, the system will send shopping cart orders for SSL certificates to UAPI’s Market::request_ssl_certificates function.

Authorizations:

BasicAuth

query Parameters

access_token required	string <uuid> Example: access_token=1a676e6f-99fc-11e6-9ab6-e60a769b73bc The access token to connect to the provider.
item required	Array of strings <json> [ items <json > ] Example: item={"product_id":123456,"provider-specfic-key":"provider-specfic-value","another-provider-specfic-key":"another-provider-specfic-value"}&item={"product_id":123457,"provider-specfic-key":"provider-specfic-value","another-provider-specfic-key":"another-provider-specfic-value"} The items to add to the shopping cart. Note: The value is a JSON string. This object has one required key, `product_id`, which is a string. The other keys/values in this object vary depending on the provider.
provider required	string Example: provider=cPStore The cPanel Market provider’s name.
url_after_checkout required	string <url> Example: url_after_checkout=http://www.example.com/thenextplace The location to which the provider directs the user after the checkout process is complete.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  create_shopping_cart \
  provider='cPStore' \
  access_token='1a676e6f-99fc-11e6-9ab6-e60a769b73bc' \
  url_after_checkout='http://www.example.com/thenextplace' \
  item='{"product_id":123456,"provider-specfic-key":"provider-specfic-value","another-provider-specfic-key":"another-provider-specfic-value"}' item='{"product_id":123457,"provider-specfic-key":"provider-specfic-value","another-provider-specfic-key":"another-provider-specfic-value"}'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_shopping_cart",
"module": "Market",
"result": {"data": {"checkout_url": "http://www.example.com/checkout",
"order_id": "8765309",
"order_items": [{ }
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return provider's login URL

This function retrieves the login URL for the cPanel Market provider.

Authorizations:

BasicAuth

query Parameters

provider required	string Example: provider=cPStore The cPanel Market provider's name.
url_after_login required	string <url> Example: url_after_login=http://hostname.example.com/redirectionlocation.cgi?state Where the cPanel Market provider redirects the user's browser after they log in.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_login_url \
  provider='cPStore' \
  url_after_login='http://hostname.example.com/redirectionlocation.cgi?state'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_login_url",
"module": "Market",
"result": {"data": "https://example.com/api/?client_id=MyHearseIsAmazing&function=login&module=bogoSSL&redirect_uri=https%3A%2F%2Fqaportal.cpanel.net%2Fbogus.cgi&response_type=token",
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return enabled providers

This function lists the names of enabled cPanel Market providers.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_providers_list

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_providers_list",
"module": "Market",
"result": {"data": [{"display_name": "cPanel Store",
"name": "cPStore"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update status of items in pending queue

This function sets the status of an item or items in the cPanel Market pending queue.

Authorizations:

BasicAuth

query Parameters

order_item_id required	string Examples: order_item_id=order_item_id-1=12345&order_item_id-2=12346&order_item_id-3=12347 - Multiple IDs. order_item_id=order_item_id=12345&order_item_id=12346&order_item_id=12347 - Multiple IDs alternative. order_item_id=12345 - A single ID. The ID of the ordered item. Note: To set the status for multiple items, duplicate or increment the parameter name. For example, to change the status for three certificates, use the `order_item_id` parameter multiple times or use the `order_item_id-1`, `order_item_id-2`, and `order_item_id-3` parameters.
provider required	string Example: provider=cPStore The cPanel Market provider's name.
status required	string Value: "confirmed" Example: status=confirmed The new status of the item in the cPanel Market pending queue. `confirmed` — The system confirmed payment for the item with the provider.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  set_status_of_pending_queue_items \
  provider='cPStore' \
  order_item_id='12345' \
  status='confirmed'

Response samples

200

Content type

application/json

Example

The function failed.

{"apiversion": 3,
"func": "set_status_of_pending_queue_items",
"module": "Market",
"result": {"data": {"error_type": "EntryDoesNotExist",
"order_item_ids": [8675309
]
},
"errors": ["The order item ID “8675309” does not match any entries in the pending queue."
],
"messages": null,
"metadata": { },
"status": 0,
"warnings": null
}
}

Validate login token

This function validates a login token to a cPanel Market provider and returns an access token.

Authorizations:

BasicAuth

query Parameters

login_token required	string Example: login_token=8675309 The login token for the cPanel Market provider.
provider required	string Example: provider=cPStore The name of the cPanel Market provider.
url_after_login required	string <url> Example: url_after_login=http://hostname.example.com/redirectionlocation.cgi?state The `url_after_login` value that you sent to UAPI's `Market::get_login_url` function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  validate_login_token \
  provider='cPStore' \
  login_token='8675309' \
  url_after_login='http://hostname.example.com/redirectionlocation.cgi?state'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "validate_login_token",
"module": "Market",
"result": {"data": {"access_token": "8675309"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update URL after checkout

This function updates the URL to which a provider sends a user after they check out.

Authorizations:

BasicAuth

query Parameters

access_token required	string Example: access_token=725431a1-d5bc-11e5-a28b-8b0e09a93f05 The access token for the session to the cPanel Market provider.
order_id required	integer Example: order_id=123456 The order ID that the cPanel Market provider assigned.
provider required	string Example: provider=cPStore The cPanel Market provider's name.
url_after_checkout required	string <url> Example: url_after_checkout=http://checkout.example.com The URL to send the browser after the user checks out.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  set_url_after_checkout \
  provider='cPStore' \
  access_token='725431a1-d5bc-11e5-a28b-8b0e09a93f05' \
  order_id='123456' \
  url_after_checkout='http://checkout.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_url_after_checkout",
"module": "Market",
"result": {"data": {"error_type": "This is an error."
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

SSL Certificates

Commerce Integration / SSL Certificates

Delete an order

This function cancels an order and removes the polling for a pending certificate.

Authorizations:

BasicAuth

query Parameters

order_item_id required	string Example: order_item_id=10427508 The ID of the ordered item to cancel.
provider required	string Example: provider=cPStore The cPanel Market provider's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  cancel_pending_ssl_certificate \
  provider='cPStore' \
  order_item_id='10427508'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "cancel_pending_ssl_certificate",
"module": "Market",
"result": {"data": [{"created_time": 1458061262,
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC0TCCAbkCAQAwGzEZMBcGA1UEAxMQY29icmFzc2x0ZXN0Lm9yZzCCASIwDQYJ\nKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKsZWNkF8hjUjoCDNNSkXO0CTp/z/0pu\niFiDMzdFAa6mg5wr97EwRBCniSvJEJ1rdQ0Sus2AAK9hg7TeZAWbFf97r7mS0chm\nr27Ht9qfit3r0EJLYcjRjnZ/wj21ZhsdjQIjjTRiI1TvXtOQRAQpWNsGxK7QV3Q3\nnjkSM/gTpteHuC3JAQxbpv72B+IjiyzUZr8DOUOoB94IO5iP27UXnkSbExInDvqu\nK43zVGYNU0Zev20A6SBWU3BALjWXHlYjwbC109FxOWNssHTg3xvePsBxzk6BFDcT\nS/QAS0tFYPfHZKmCBg6irBGFOdTjSDVmFk8zAoFYibev0juRJCMn2XsCAwEAAaBx\nMG8GCSqGSIb3DQEJDjFiMGAwXgYDVR0RAQH/BFQwUoIQY29icmFzc2x0ZXN0Lm9y\nZ4IUd3d3LmNvYnJhc3NsdGVzdC5vcmeCEWNwYW5lbHNzbHRlc3Qub3JnghV3d3cu\nY3BhbmVsc3NsdGVzdC5vcmcwDQYJKoZIhvcNAQELBQADggEBAG0l4aChMO1rSmgR\nSF5qlKu785n5YS5rTE9ev+OFu0952DvjVAB0R8y5+TZSXfg+9CH7pa2VDosAEYF4\nyjUJOuiwwVEUD/9Qhrls/2xT8KKk0QSxuWmOgP2YQy/QRH+W7ykoigtiWdXEIUuF\niJmeavS8JOYt560366V3dw7YT+QstUHQ7UlGEFDeWQI3osUN1wDrtW5qcaq09Q/G\nTcphzXrRkL5lRjKXKLIcY/HVYzOnoEX30ALX2I3bJ9s4IMRfpnhTqLmWalcr+4vq\nvqVnlB0B/nXf/qaB/xvxmEtSGx/GZ/8Gsrf5PB7GhRuStUtJoXcLuADK0bgug3X2\nGxEruS4=\n-----END CERTIFICATE REQUEST-----\n",
"domains": ["example1.com",
"example2.com"
],
"expired": 0,
"first_poll_time": 1458061262,
"last_poll_time": 1458061262,
"last_status_code": "CertificateNotFound",
"order_id": "1392472",
"order_item_id": "10427508",
"product_id": "143",
"provider": "cPStore",
"status": "confirmed",
"support_uri": "http://support.example.com/",
"vhost_names": ["abcde.com"
]
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return provider's SSL certificate request status

This function returns the status of an SSL certificate request. The returns include actionable URLs for users to expedite the validation process, if applicable.

Important:

Because this function returns data from a dynamic source, the returns in each object can vary.

Authorizations:

BasicAuth

query Parameters

order_item_id required	integer >= 1 Example: order_item_id=1234567890 The order ID that the cPanel Market provider assigned.
provider required	string Example: provider=cPStore The cPanel Market provider's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_certificate_status_details \
  order_item_id='1234567890' \
  provider='cPStore'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_certificate_status_details",
"module": "Market",
"result": {"data": {"actionUrls": {"evClickThroughStatus": "https://example.com/action",
"ovCallbackStatus": "https://example.com/action"
},
"domain_details": {"domain": "www.example.com",
"status": "AWAITINGBRAND"
},
"status_details": {"brandValStatus": "in-progress",
"certificateStatus": "in-progress",
"csrStatus": "completed",
"dcvStatus": "completed",
"evClickThroughStatus": "in-progress",
"freeDVUPStatus": "not applicable",
"organizationValidationStatus": "not applicable",
"ovCallbackStatus": "not applicable",
"validationStatus": "in-progress"
}
},
"errors": null,
"messages": ["Certificate request is still being processed."
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Return provider's DCV filename requirements

This function returns the provider's filename requirements for Domain Control Validation (DCV) checks.

Authorizations:

BasicAuth

query Parameters

provider

required

string

Example: provider=cPStore

The cPanel Market provider's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_provider_specific_dcv_constraints \
  provider='cPStore'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_provider_specific_dcv_constraints",
"module": "Market",
"result": {"data": {"dcv_file_allowed_characters": [[0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
"A",
"B",
"C",
"D",
"E",
"F"
]
],
"dcv_file_extension": "txt",
"dcv_file_random_character_count": 32,
"dcv_file_relative_path": ".well-known/pki-validation",
"dcv_max_redirects": 0,
"dcv_user_agent_string": "COMODO DCV"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return provider's pending SSL certificates

This function lists all pending SSL certificates from a cPanel Market provider for which the system currently polls.

Authorizations:

BasicAuth

query Parameters

provider

required

string

Example: provider=cPStore

The cPanel Market provider's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_pending_ssl_certificates \
  provider='cPStore'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_pending_ssl_certificates",
"module": "Market",
"result": {"data": [{"created_time": 1417475501,
"csr": "Click to view...-----BEGIN CERTIFICATE REQUEST----- MIIC4DCCAcgCAQAwgZoxFjAUBgNVBAMTDXRlc3RzaW1vbi5jb20xFjAUBgNVBAsT DURvY3VtZW50YXRpb24xDjAMBgNVBAgTBVRleGFzMQ8wDQYDVQQKEwZjUGFuZWwx KDAmBgkqhkiG9w0BCQEWGWxhdXJlbmNlLnNpbW9uQGNwYW5lbC5uZXQxCzAJBgNV BAYTAlVTMRAwDgYDVQQHEwdIb3VzdG9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A MIIBCgKCAQEA4AVM6J4Qg3DIFWr/eJ5GRmIATYsJIepKbrDy70sq+udcO8R8xxak 0oMZ/9mUdpjSNK/fLVTuCO0kxTfQ9VUWJllX7ThD6Zh9ZvlC/nf/OEZLm3ZbnBgu 8rbC8E9wuDOkKbJLnINgdhtowIydLK2MJ++q62bFV89jkHWTMcKyyqHENo3hc+lk pd9vnp8rZTinaVb7nX26uQqAFZYRo+WU0G/NPsq40QVSMoqPxyEz4qXo0hvuIlCX mzFZq/6fCVPEKPLhQgMmpdBkMz4dVOazREfqXdjMD2+QXSNiA1AwWr8l0r4rtzlx EYDJIR41yXp0xMl3KoolxMyvLBqZy32niQIDAQABoAAwDQYJKoZIhvcNAQEFBQAD ggEBAEaCn+rg6qlhp6SEKuZg1G6z1M+1XQoTN3E6bTdM3rD1wXjqtyFfYGTy5Bvv gUKrl6t312owJ2si8/K9v/ocVxdjc0rPWSOWScfSc1Od3i1L1YuqbboL2aQSak3y gpGnZMHCUED1y4xyABAFOaXUurFiZj5u3P2mBAYGt2ez2afiPlo5YpTRNCoTUlVz KNKkyUnptBLOvlwGgerBmOoP4QdVhTSuxO9TECsiPdldE1BVZrlFclDFvoP01jFZ WOTWz+k3O202gK4w/tPP2VMVldNFrC0QoENu85ohT1nJj6F3mrM1CZ+1c8zYzr+S 6aAXFhHE6FweeunRAGjEJggoTPo= -----END CERTIFICATE REQUEST-----",
"domains": ["example.com"
],
"expired": 0,
"first_poll_time": 1437475501,
"identity_verification": {"assumed_name": "cPanel",
"business_category": "b",
"countryName": "US",
"date_of_incorporation": "1996-01-01",
"duns_number": "12-345-6789",
"joi_country_name": "US",
"joi_locality_name": "Somewhere",
"joi_state_or_province_name": "PA",
"localityName": "Houston",
"organizationName": "WebPros International, LLC",
"organizationalUnitName": "Team Cobra",
"postalCode": "77092",
"rep_email_address": "[email protected]",
"rep_forename": "Richard",
"rep_surname": "Ang",
"rep_telephone": "713-529-0800",
"stateOrProvinceName": "TX",
"streetAddress": "2500 N. Loop W."
},
"last_poll_time": 1457475501,
"last_status_code": "CertificateNotFound",
"order_id": "AAE35B28-E57B-11E5-A5DD-B633DD41FB49",
"order_item_id": "1",
"product_id": "12345",
"provider": "cPStore",
"status": "confirmed",
"support_uri": "http://support.example.com/",
"vhost_names": ["example.com"
]
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return provider's available SSL certificates

This function retrieves SSL certificates when they are available from the cPanel Market provider.

Authorizations:

BasicAuth

query Parameters

order_item_id required	string Example: order_item_id=8675309 The order item for which to poll.
provider required	string Example: provider=cPStore The cPanel Market provider's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  get_ssl_certificate_if_available \
  provider='cPStore' \
  order_item_id='8675309'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_ssl_certificate_if_available",
"module": "Market",
"result": {"data": {"certificate_pem": "-----BEGIN CERTIFICATE----- MIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJ c2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQI DAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYy MjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNV BAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0G CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3P Xx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fW voK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/da M3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC +Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6 PLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGj UDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw +wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA A4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3Wh cDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVw FYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh /SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2ag qz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPa Km6r7YmwfLN/YMZBHXSR58oOGP9W -----END CERTIFICATE-----",
"encrypted_action_urls": {"evClickThroughStatus": "mgs8RgnN0rkRmJz0SAMvjLokoPoXm5LdzEkmKA7IsGmzvU5XTrFInOegFBbWFycToS7FPOevzkH9\\nZp0+QG1xcC/0bWKB1cNeTiYB3Fmv0HGu2ZsA+AYgIhSsZikyD9M6YbHk1IZA3GLNPl8DxX5zG9LQ\\nHiv7Ll2QMJcPmMaJ3xktTY9NuiaPiPmYBljEE094LeqabP3w/kRALDnhR4FcwjsTn7iDJKoxtKju\\nP/DbgV32vhESwWoaKrIYPkSJ/Dav0a/LQqLqD3Jg27WgrW+GaZSbHlHr09UQW/2CIiIK7jbUoLG3\\nANL0fKevyjxrBjCfXQq0umXcZIJPWo4gfukfkQ==\\n",
"ovCallbackStatus": "mgs8RgnN0rkRmJz0SAMvjLokoPoXm5LdzEkmKA7IsGmzvU5XTrFInOegFBbWFycToS7FPOevzkH9\\nZp0+QG1xcC/0bWKB1cNeTiYB3Fmv0HGu2ZsA+AYgIhSsZikyD9M6YbHk1IZA3GLNPl8DxX5zG9LQ\\nHiv7Ll2QMJcPmMaJ3xktTY9NuiaPiPmYBljEE094LeqabP3w/kRALDnhR4FcwjsTn7iDJKoxtKju\\nP/DbgV32vhESwWoaKrIYPkSJ/Dav0a/LQqLqD3Jg27WgrW+GaZSbHlHr09UQW/2CIiIK7jbUoLG3\\nANL0fKevyjxrBjCfXQq0umXcZIJPWo4gfukfkQ==\\n"
},
"status_code": "RequiresApproval",
"status_message": "PRE-SIGN FAILED: CAA: Processing error"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Start processing pending queue's SSL certificates

This function manually processes the cPanel Market's SSL certificate request pending queue.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Market \
  process_ssl_pending_queue

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "process_ssl_pending_queue",
"module": "Market",
"result": {"data": [{"certificate_pem": "null",
"created_time": 1460136406,
"csr": "-----BEGIN CERTIFICATE REQUEST-----\\nMIICqjCCAZICAQAwHDEaMBgGA1UEAxMRY3BhbmVsc3NsdGVzdC5vcmcwggEiMA0G\\nCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqu4KLPxCgAENTJFjcUyc4v5KaF8Lu\\n2OldjIT/vB58IRCIUxdDSD29v/qHFVBaUFEtr+Ssey0strMcc6JYSl8Vdwfe2qwv\\npB6+Ufg+hlN4lAgojxgwz7iZlPnGuRVfNTvNMmljVRzGDc4SSzskpDxZhk+aaMgP\\nSkMLFg6f6pFZ+44alridlSG5gxD34xWAtt8Qy2v+6Q4XVuMNCd9KlyAoCV9Q+wH1\\nq49yoRdwvcY6G6mqlFWtHsToz4tdYk/Nt7odZnyKcjHWGWnlRzO2FGbbBxVKF8s6\\ns3DL5OwPRfQQD18V7eL7NmcFo45zmdndBOevrLuwXJ1yWITM2bmYgF1nAgMBAAGg\\nSTBHBgkqhkiG9w0BCQ4xOjA4MDYGA1UdEQEB/wQsMCqCEWNwYW5lbHNzbHRlc3Qu\\nb3JnghV3d3cuY3BhbmVsc3NsdGVzdC5vcmcwDQYJKoZIhvcNAQELBQADggEBAFAJ\\nSqTvd3d8PN26UiT4uX0WjofaX8u1/11hU5Saekai0Dxl/ijq2R7TpebXe9r0t6Cr\\ns7NXKszVoKzQHV4nSFbfb3ZxEsnVDXbPUv3D+oLfGpMASLG+P2yOjmDhzZBNJgo4\\nQu6nf6ggJxJ0PRM81xL234FAKqsOvvTwTLXtYVrwbUCzfB+yKJXvfeGETR/3HGxR\\nqoJ97Zmjsbw78fETEsZ6rsBHDPuxtxum73BC7qoLjCl4psPznHshXvWTeV9fyR3c\\nqpdpLvwBxhI8ZOWoNGgJlUpY9jUFgqG+YI/Mkmzmxk9QC9edIHSScTXxroYkmwMC\\nginnKRLDafSp+7FyIzs=\\n-----END CERTIFICATE REQUEST-----",
"deleted": 0,
"domains": ["example.com"
],
"expired": 0,
"first_poll_time": 1458061262,
"installed": 0,
"last_poll_time": 1458061299,
"last_status_code": "CertificateNotFound",
"last_status_message": "PRE-SIGN FAILED: CAA: Processing error",
"order_id": "19461",
"order_item_id": "f9d7",
"product_id": "fg2",
"provider": "cPStore",
"status": "confirmed",
"vhost_names": ["example.com"
]
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Request SSL certificate order

This function submits a request for a certificate order to the cPanel Market provider.

Authorizations:

BasicAuth

query Parameters

access_token required	string Example: access_token=725431a1-d5bc-11e5-a28b-8b0e09a93f05 The access token for the session to the cPanel Market provider.
required	object Example: certificate={"price":6,"product_id":"143","subject_names":[{"dNSName":"example.com"},{"dNSName":"example.org"}],"validity_period":["1, \"year\""],"vhost_names":["example.com"]} A JSON-encoded string that contains the details of the certificate. Note: To request multiple certificates, duplicate or increment the parameter name. For example, to request three certificates, use the `certificate` parameter multiple times or use the `certificate-1`, `certificate-2`, and `certificate-3` parameters.
identity_verification	object Example: identity_verification={"countryName":"US","duns_number":"12-345-6789","localityName":"City Name","organizationName":"Company, Inc.","organizationalUnitName":"Team Company,","postalCode":55555,"rep_email_address":"[email protected]","rep_forename":"First Name","rep_surname":"Last Name","rep_telephone":"123-456-7891","stateOrProvinceName":"ST","streetAddress":"555 Street Name"} An object containing the required information for an EV or OV certificate. This information depends on the provider of the certificate. Note: The function returns this object for OV or EV certificate requests.
provider required	string Example: provider=cPStore The cPanel Market provider's name.
url_after_checkout	string <url> Example: url_after_checkout=http://checkout.example.com The URL to send the browser after the user checks out. Note: This URL does not contain a query string.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output-jsonpretty --user=username Market request_ssl_certificates access_token='725431a1-d5bc-11e5-a28b-8b0e09a93f05' certificate='{"price":"6","product_id":"143","subject_names":[{"dNSName":"example.com"},{"dNSName":"example.org"}],"validity_period":["1, \"year\""],"vhost_names":["example.com"]}' provider='cPStore'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "request_ssl_certificates",
"module": "Market",
"result": {"data": {"certificates": {"key_id": "ac90f_639fd_6c236062f0d7a4579a30e01612c4cee0",
"order_item_id": 12345
},
"checkout_url": "http://store.example.com/showmethemoney.cgi",
"order_id": 123456
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Contact Information

cPanel Account / Contact Information

Update Pushbullet access token

This function updates the cPanel account's Pushbullet™ access token.

Authorizations:

BasicAuth

query Parameters

pushbullet_access_token

required

string

Example: pushbullet_access_token=a1b2c3d4e5f6g7h8i9j0

The account’s new Pushbullet access token.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  set_pushbullet_access_token \
  pushbullet_access_token='a1b2c3d4e5f6g7h8i9j0'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_pushbullet_access_token",
"module": "ContactInformation",
"result": {"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return the account's notification preferences.

Use this function to get a cPanel or Webmail account's notification preferences.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  get_notification_preferences

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_notification_preferences",
"module": "ContactInformation",
"result": {"data": [{"additionalProperties": "string",
"descp": "Someone logs in to my account.",
"enabled": 1,
"name": "notify_account_login"
}
],
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return Pushbullet access token

This function retrieves the cPanel account's Pushbullet™ access token.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  get_pushbullet_access_token

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_pushbullet_access_token",
"module": "ContactInformation",
"result": {"data": "a1b2c3d4e5f6g7h8i9j0",
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Set the account's notification preferences.

Use this function to set the logged in cPanel or Webmail account's notification preferences.

Note:

To set a cPanel account's notification email address, call set_email_addresses. To return the list of account notification preferences you can set with set_notification_preferences, call get_notification_preferences.

Authorizations:

BasicAuth

Request Body schema: application/json

object

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

Payload
CLI
URL

Content type

application/json

{"preferences": {"notify_account_authn_link": "0",
"notify_account_login": "1"
}
}

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_notification_preferences",
"module": "ContactInformation",
"result": {"data": [{"additionalProperties": "string",
"descp": "Someone logs in to my account.",
"enabled": 1,
"name": "notify_account_login"
}
],
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Unset contact email addresses

Use this function to unset all contact email address for an account.

To set contact email address(es), call set_email_addresses.

Authorizations:

BasicAuth

query Parameters

old_address required	Array of strings <email> [ items <email > ] Example: [email protected] The account’s existing contact email addresses. If this list does not match the account’s current current email address(es), then the request will fail. This control is here to prevent race conditions.
password required	string Example: password=q1df%D9<z0ShqdxRP%^ The account’s password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  unset_email_addresses \
  old_address='[email protected]' \
  password='q1df%D9<z0ShqdxRP%^'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "DynamicDNS",
"result": {"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set contact email address(es)

Use this function to set an account's contact email address(es).

To unset all contact email addresses, call unset_email_addresses.

Authorizations:

BasicAuth

query Parameters

address required	Array of strings <email> [ items <email > ] Example: [email protected]&[email protected] The account’s new contact email addresses.
old_address required	Array of strings <email> [ items <email > ] Example: [email protected] The account’s existing contact email addresses. If this list does not match the account’s current current email address(es), then the request will fail. This control is here to prevent race conditions.
password required	string Example: password=q1df%D9<z0ShqdxRP%^ The account’s password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  set_email_addresses \
  address='[email protected]' address='[email protected]' \
  old_address='[email protected]' \
  password='q1df%D9<z0ShqdxRP%^'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_email_addresses",
"module": "ContactInformation",
"result": {"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return whether contact option is enabled

This function checks whether the cPanel account can contact their hosting provider from the cPanel interface.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Contactus \
  is_enabled

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_enabled",
"module": "Contactus",
"result": {"data": {"enabled": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Account Enhancements

The Account Enhancement module for UAPI.

Validate Account Enhancement assignment

This function returns whether a cPanel account has a specific Account Enhancement.

Authorizations:

BasicAuth

query Parameters

id

required

string

Example: id=sample-enhancement-id

The identifier for a specific Account Enhancement.

Note:

To retrieve a list of all Account Enhancements IDs on the server, run the WHM API 1 list_account_enhancements function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  AccountEnhancements \
  has_enhancement \
  id=account_enhancement

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list",
"module": "AccountEnhancements",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return all cPanel account's Account Enhancements

This function lists a cPanel account's Account Enhancements.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  AccountEnhancements \
  list

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list",
"module": "AccountEnhancements",
"result": {"data": [{"id": "sample-enhancement-id",
"name": "Sample Enhancement"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Account Information

cPanel Account / Account Information

Return reseller's cPanel accounts

This function lists all of a reseller's cPanel accounts.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Resellers \
  list_accounts

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_accounts",
"module": "Resellers",
"result": {"data": [{"domain": "example.com",
"select": "1",
"user": "username"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's configuration settings

This function retrieves the user's account configuration settings.

Authorizations:

BasicAuth

query Parameters

name

string

Examples:

name=name-1=mailbox_format&name-2=home&name-3=shell - Get multiple account configuration settings.
name=mailbox_format - Get a single account configuration setting.

The user configuration variables to retrieve. If you don't use this parameter, this function returns all of the user's configuration data.

Note:

To retrieve multiple account configuration settings for a user, increment the parameter name. For example: name-0, name-1, and name-2.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Variables \
  get_user_information

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_user_information",
"module": "Variables",
"result": {"data": {"backup_enabled": 1,
"bandwidth_limit": 0,
"cgi_enabled": 1,
"contact_email": "[email protected]",
"contact_email_2": "[email protected]",
"cpanel_root_directory": "/usr/local/cpanel",
"created": 1432220941,
"created_in_version": "11.94.0.0",
"database_owner": "root",
"dead_domains": ["example.example.com"
],
"demo_mode": 1,
"disk_block_limit": 100000000,
"dkim_enabled": 1,
"domain": "example.com",
"domains": ["example.com"
],
"feature": {"custom_feature": 1
},
"feature_list": "feature_list",
"gid": 5678,
"home": "/home/user",
"home_directory_links": ["symlink"
],
"ip": "192.0.2.0",
"lang": "english",
"last_modified": 1416586493,
"legacy_backup_enabled": 1,
"locale": "en",
"mailbox_format": "maildir",
"maximum_addon_domains": "unlimited",
"maximum_databases": "unlimited",
"maximum_defer_fail_percentage": "unlimited",
"maximum_email_account_disk_quota": "unlimited",
"maximum_emails_per_hour": "unlimited",
"maximum_ftp_accounts": "unlimited",
"maximum_mail_accounts": "0",
"maximum_mailing_lists": "unlimited",
"maximum_parked_domains": "unlimited",
"maximum_passenger_apps": "unlimited",
"maximum_subdomains": "unlimited",
"mxcheck": {"example.com": "local",
"example2.com": "remote"
},
"notify_account_authn_link": 1,
"notify_account_authn_link_notification_disabled": 1,
"notify_account_login": 1,
"notify_account_login_for_known_netblock": 1,
"notify_account_login_notification_disabled": 1,
"notify_autossl_expiry": 1,
"notify_autossl_expiry_coverage": 1,
"notify_autossl_renewal_coverage": 1,
"notify_autossl_renewal_coverage_reduced": 1,
"notify_autossl_renewal_uncovered_domains": 1,
"notify_bandwidth_limit": 1,
"notify_contact_address_change": 1,
"notify_contact_address_change_notification_disabled": 1,
"notify_disk_limit": 1,
"notify_password_change": 1,
"notify_password_change_notification_disabled": 1,
"notify_ssl_expiry": 1,
"notify_twofactorauth_change": 1,
"notify_twofactorauth_change_notification_disabled": 1,
"owner": "root",
"package_extensions": ["ext1",
"ext2",
"ext3"
],
"plan": "packagename",
"pushbullet_access_token": "1234567890",
"shell": "/bin/bash",
"spf_enabled": 1,
"ssl_default_key_type": "rsa-2048",
"theme": "jupiter",
"uid": 1234,
"user": "username",
"utf8_mailbox": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Account Management

cPanel Account / Account Management

Return Leika configuration

This function returns Leika configuration data. Leika is an internal module that cPanel & WHM uses to track access to features.

Note:

If you do not provide an item parameter, this returns the entire configuration.

Authorizations:

BasicAuth

query Parameters

item

string

Examples:

item=cpanel.key1 - Return the `key1` configuration key for the `cpanel` feature.
item=webmail.key3.subkey1 - Return the nested `key3.subkey1` configuration key for the `webmail` feature.

The feature(s) for which to return configuration keys.

Note:

Pass multiple item parameters to return multiple features' configuration keys.
If an item parameter returns an undefined key value, the configuration value does not exist or is set to null.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi Leika leika_get_config item='key1' item='key3'
uapi --output=jsonpretty \
--user=username \
Leika \
leika_get_config \
item=cpanel.key1 \
item=webmail.key3

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "leika_get_config",
"module": "Leika",
"result": {"data": {"cpanel.key1": "enabled",
"webmail.key3": {"subkey1": "active",
"subkey2": "inactive"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update cPanel account password

This function updates the cPanel account's password.

Authorizations:

BasicAuth

query Parameters

enabledigest	integer Default: "The previously-set value or 0" Possible Values: 0 1 Example: enabledigest=0 Whether to use Digest Authentication. `1` - Use Digest Auth. `0` - Do not use Digest Auth. Note: Windows® Vista, Windows® 7, Windows® 8, and Windows® 10 require that you use Digest Authentication in order to access your Web Disk over a clear text, unencrypted connection.
enablemysql	integer Default: 0 Possible Values: 0 1 Example: enablemysql=0 Whether to update the cPanel account's MySQL password. `1` - Update MySQL password. `0` - Do not update MySQL password.
newpass required	string <password> Example: newpass=MyNewPassw0rd! The new password.
oldpass required	string <password> Example: oldpass=ThisWasMyPassword! The current password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Users \
  change_password \
  oldpass='MyPreviousPassword' \
  newpass='MyUpdatedPassword'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "change_password",
"module": "Users",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update cPanel account password

This function updates the cPanel account's password.

Authorizations:

BasicAuth

query Parameters

enablemysql	integer Default: 0 Possible Values: 0 1 Example: enablemysql=0 Whether to update the cPanel account's MySQL password. `1` - Update MySQL password. `0` - Do not update MySQL passowrd.
newpass required	string <password> Example: newpass=MyNewPassw0rd! The new password.
oldpass required	string <password> Example: oldpass=ThisWasMyPassword! The current password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  change_password \
  oldpass='MyPreviousPassword' \
  newpass='MyUpdatedPassword'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "change_password",
"module": "UserManager",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

AuditLog

The AuditLog module for UAPI.

Contact Information

cPanel Account / Contact Information

Update Pushbullet access token

This function updates the cPanel account's Pushbullet™ access token.

Authorizations:

BasicAuth

query Parameters

pushbullet_access_token

required

string

Example: pushbullet_access_token=a1b2c3d4e5f6g7h8i9j0

The account’s new Pushbullet access token.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  set_pushbullet_access_token \
  pushbullet_access_token='a1b2c3d4e5f6g7h8i9j0'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_pushbullet_access_token",
"module": "ContactInformation",
"result": {"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return the account's notification preferences.

Use this function to get a cPanel or Webmail account's notification preferences.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  get_notification_preferences

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_notification_preferences",
"module": "ContactInformation",
"result": {"data": [{"additionalProperties": "string",
"descp": "Someone logs in to my account.",
"enabled": 1,
"name": "notify_account_login"
}
],
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return Pushbullet access token

This function retrieves the cPanel account's Pushbullet™ access token.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  get_pushbullet_access_token

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_pushbullet_access_token",
"module": "ContactInformation",
"result": {"data": "a1b2c3d4e5f6g7h8i9j0",
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Set the account's notification preferences.

Use this function to set the logged in cPanel or Webmail account's notification preferences.

Note:

To set a cPanel account's notification email address, call set_email_addresses. To return the list of account notification preferences you can set with set_notification_preferences, call get_notification_preferences.

Authorizations:

BasicAuth

Request Body schema: application/json

object

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

Payload
CLI
URL

Content type

application/json

{"preferences": {"notify_account_authn_link": "0",
"notify_account_login": "1"
}
}

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_notification_preferences",
"module": "ContactInformation",
"result": {"data": [{"additionalProperties": "string",
"descp": "Someone logs in to my account.",
"enabled": 1,
"name": "notify_account_login"
}
],
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Unset contact email addresses

Use this function to unset all contact email address for an account.

To set contact email address(es), call set_email_addresses.

Authorizations:

BasicAuth

query Parameters

old_address required	Array of strings <email> [ items <email > ] Example: [email protected] The account’s existing contact email addresses. If this list does not match the account’s current current email address(es), then the request will fail. This control is here to prevent race conditions.
password required	string Example: password=q1df%D9<z0ShqdxRP%^ The account’s password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  unset_email_addresses \
  old_address='[email protected]' \
  password='q1df%D9<z0ShqdxRP%^'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "DynamicDNS",
"result": {"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set contact email address(es)

Use this function to set an account's contact email address(es).

To unset all contact email addresses, call unset_email_addresses.

Authorizations:

BasicAuth

query Parameters

address required	Array of strings <email> [ items <email > ] Example: [email protected]&[email protected] The account’s new contact email addresses.
old_address required	Array of strings <email> [ items <email > ] Example: [email protected] The account’s existing contact email addresses. If this list does not match the account’s current current email address(es), then the request will fail. This control is here to prevent race conditions.
password required	string Example: password=q1df%D9<z0ShqdxRP%^ The account’s password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ContactInformation \
  set_email_addresses \
  address='[email protected]' address='[email protected]' \
  old_address='[email protected]' \
  password='q1df%D9<z0ShqdxRP%^'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_email_addresses",
"module": "ContactInformation",
"result": {"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return whether contact option is enabled

This function checks whether the cPanel account can contact their hosting provider from the cPanel interface.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Contactus \
  is_enabled

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_enabled",
"module": "Contactus",
"result": {"data": {"enabled": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

cPanel Features

cPanel Account / cPanel Features

Return cPanel account's features' metadata

This function lists the details of a cPanel account's available feature lists.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Features \
  get_feature_metadata

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_feature_metadata",
"module": "Features",
"result": {"data": [{"id": "wordpress_manager",
"is_cpaddon": 0,
"is_plugin": 1,
"name": "Wordpress Manager"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate cPanel account's feature access

This function checks whether a cPanel account has access to a feature.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=autossl

The feature's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Features \
  has_feature \
  name='autossl'

Response samples

200

Content type

application/json

Example

The account does not have a feature.

{"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 0,
"warnings": null
}
}

Return cPanel account's features

This function lists a cPanel account's features.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Features \
  list_features

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_features",
"module": "Features",
"result": {"data": {"bbs": 0,
"blockers": 1,
"boxtrapper": 1,
"changemx": 1,
"chat": 0,
"defaultaddress": 1,
"email_disk_usage": 1,
"emailarchive": 1,
"emailauth": 1,
"emaildomainfwd": 1,
"emailtrace": 1,
"popaccts": 1,
"spamassassin": 1,
"spambox": 1,
"traceaddy": 1,
"updatecontact": 1,
"webmail": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disk Quotas

cPanel Account / Disk Quotas

Return local disk quota information

This function retrieves the cPanel account's quota for the server where you run the function. For example, a distributed cPanel account could approach its quota. The servers will balance that cPanel user's quota between the parent and the child node.

Note:

This function runs on only the local server. To retrieve the cPanel account's total quota, use the UAPI Quota::get_quota function instead.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Quota \
  get_local_quota_info

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_local_quota_info",
"module": "Quota",
"result": {"data": {"byte_limit": 262144000,
"bytes_used": 4149284,
"inode_limit": 0,
"inodes_used": 1035
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return disk quota information

This function retrieves the cPanel account's quota.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Quota \
  get_quota_info

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_quota_info",
"module": "Quota",
"result": {"data": {"inode_limit": 0,
"inodes_remain": 0,
"inodes_used": 1035,
"megabyte_limit": 0,
"megabytes_remain": 0,
"megabytes_used": 5.46,
"under_inode_limit": 0,
"under_megabyte_limit": 1,
"under_quota_overall": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Personalization

The Personalization module for UAPI.

Save NVData data to file

This function saves its data to an NVData file on disk. cPanel NVData is a per-account configuration storage mechanism that you can use to maintain persistent cPanel & WHM settings across multiple sessions. This includes custom settings for your own themes and plugins.

Note:

NVData keys and values are limited to 128 and 2048 bytes, respectively.

Authorizations:

BasicAuth

Request Body schema: application/json
required

object

The NVData keys and values to update.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

Payload
CLI
HTTP Request (Wire Format)

Content type

application/json

{"personalization": {"coffee": "hot",
"milk": "cold"
}
}

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set",
"module": "Personalization",
"result": {"data": {"coffee": {"reason": "OK",
"success": 1,
"value": "hot"
},
"milk": {"reason": "OK",
"success": 1,
"value": "cold"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Retrieve NVData data from file

This function retrieves the data from an NVData file on disk. cPanel NVData is a per-account configuration storage mechanism that you can use to maintain persistent cPanel & WHM settings across multiple sessions. This includes custom settings for your own themes and plugins.

Note:

NVData keys and values are limited to 128 and 2048 bytes, respectively.

Authorizations:

BasicAuth

Request Body schema: application/json
required

names

Array of strings

List of NVData keys to query the server about.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

Payload
CLI
HTTP Request (Wire Format)

Content type

application/json

{"names": ["coffee",
"milk"
]
}

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get",
"module": "Personalization",
"result": {"data": {"coffee": {"reason": "OK",
"success": 1,
"value": "hot"
},
"milk": {"reason": "OK",
"success": 1,
"value": "cold"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Resource Usage and Statistics

cPanel Account / Resource Usage and Statistics

Return resource usage and custom statistics

This function retrieves resource usage and custom statistics for a cPanel user account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ResourceUsage \
  get_usages

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_usages",
"module": "ResourceUsage",
"result": {"data": [{"description": "MySQL® Databases",
"error": null,
"formatter": "format_bytes",
"id": "mysql_databases",
"maximum": 15,
"url": "sql/index.html",
"usage": 0
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account statistics

This function retrieves a cPanel account's statistics.

Authorizations:

BasicAuth

query Parameters

display required	string Example: display=bandwidthusage\|diskusage A pipe-delimited list of the account's statistics. Click for a list of available display parameters. `addondomains` — Information about the account's addon domains. `apacheversion` — The server's Apache version. `autoresponders` — Information about the account's auto-responders. `bandwidthusage` — Information about the account's bandwidth usage. `cachedlistdiskusage` — The amount of cached mailing list disk space the account currently uses. `cachedmysqldiskusage` — The amount of cached disk space that the account's MySQL® databases currently use. `cachedpostgresdiskusage` — The amount of cached disk space that the account's PostgreSQL databases use. `cpanelversion` — The server's cPanel version. `dedicatedip` — Account websites that use dedicated IP addresses. `diskusage` — Information the account's disk space usage. `emailaccounts` — Information about the account's email accounts. `emailfilters` — Information the account's email filters. `emailforwarders` — Information about the account's forwarders. `fileusage` — Information about the account's file usage. `ftpaccounts` — Information about the account's FTP accounts. `hostingpackage` — The account's hosting package. `hostname` — The server's hostname. `kernelversion` — The operating system's kernel version. `localip` — Account websites that use local IP addresses. `machinetype` — The type of operating system that the server uses. `mailinglists` — Information the account's mailing lists. `mysqldatabases` — The number of MySQL databases the account possesses. `mysqldiskusage` — The amount of disk space that the account's MySQL databases use. `mysqlversion` — The server's MySQL version. `operatingsystem` — The server's operating system. `parkeddomains` — Information about the account's parked domains (aliases). `perlpath` — The Perl binary's absolute path. `perlversion` — The server's Perl version. `phpversion` — The server's PHP version. `postgresqldatabases` — The number of PostgreSQL databases the cPanel account possesses. `postgresdiskusage` — The amount of disk space that the cPanel account's PostgreSQL databases use. `sendmailpath` — The path to the system's sendmail binary. `sharedip` — Any of the account's websites that use a shared IP address. `shorthostname` — The short version of your server's hostname. `sqldatabases` — Information about the all of the account's SQL databases. `subdomains` — Information about the account's subdomains. `theme` — The account's current theme. Note: This function may require URI-encode format (`%7C`) or quotes (`"`) in some contexts, such as the command line tool. Some display parameters may be unavailable based on the server's configuration.
infinityimg	string or null Default: null Example: infinityimg=/home/example/infinity.png The absolute file path to an alternative infinity symbol image.
infinitylang	string or null Default: null Example: infinitylang=infinity A phrase to represent infinity that the locales system can use.
rowcounter	string or null Default: null Example: rowcounter=even The type of row. `odd` `even`
warninglevel	integer or null [ 1 .. 100 ] Default: null Example: warninglevel=87 The minimum level at which to return warnings.
warnings	integer or null Default: null Possible Values: 1 0 Example: warnings=0 Whether to return all results with a warning. `1` — Return only warnings that exceed the `warninglevel` parameter's value. `0` — Return all results.
warnout	integer or null Default: null Possible Values: 1 0 Example: warnout=0 Whether to display results with a value of `100%`. `1` — Display results with a value of `100%`. `0` — Hide results with a value of `100%`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  StatsBar \
  get_stats \
  display='bandwidthusage|diskusage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_stats",
"module": "StatsBar",
"result": {"data": [{"_count": "0.00",
"_max": "1024.00",
"_maxed": 0,
"count": "0 bytes",
"feature": "bandwidth",
"id": "bandwidthusage",
"is_maxed": 0,
"item": "Monthly Bandwidth Transfer",
"max": "1 GB",
"maxed_phrase": "You have transferred your maximum allotment of data ([format_bytes,_1]) for this month.",
"module": "Stats",
"name": "bandwidthusage",
"near_limit_phrase": "You have transferred [format_bytes,_1] of your [format_bytes,_2] data allotment for this month.",
"normalized": 1,
"percent": 0,
"percent10": 0,
"percent20": 0,
"percent5": 0,
"phrase": "Monthly Bandwidth Transfer",
"rowtype": "even",
"units": "MB",
"zeroisunlimited": 1
},
{"_count": "1.75",
"_max": "1024.00",
"_maxed": 0,
"count": "1.75 MB",
"id": "diskusage",
"is_maxed": 0,
"item": "Disk Space Usage",
"langkey": "INDXDiskUsage",
"max": "1 GB",
"maxed_phrase": "You are using your maximum storage allotment, [format_bytes,_1].",
"module": "Quota",
"name": "diskusage",
"near_limit_phrase": "You are using [format_bytes,_1] of the [format_bytes,_2] of storage available to you.",
"normalized": 1,
"percent": 0,
"percent10": 0,
"percent20": 0,
"percent5": 0,
"phrase": "Disk Space Usage",
"rowtype": "odd",
"units": "MB",
"zeroisunlimited": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Subaccount Management

cPanel Account / Subaccount Management

Return Subaccounts and service accounts conflicts

This function lists the other Subaccounts or services accounts that conflict with the specified username.

Note:

If the function returns more than one account, it will return some values multiple times within the return arrays.

Authorizations:

BasicAuth

query Parameters

full_username

required

string <email>

Example: [email protected]

The Subaccount's username and domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  check_account_conflicts \
  full_username='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_account_conflicts",
"module": "UserManager",
"result": {"data": {"accounts": {"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"dismissed_merge_candidates": [ ],
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1600162200,
"issues": [{"area": "info",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"merge_candidates": [{"parent_type": "sub",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/Subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/username",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "username"
}
]
},
"conflict": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create Subaccount

This function creates a Subaccount.

Authorizations:

BasicAuth

query Parameters

alternate_email	string <email> Default: null Example: [email protected] An alternate email address for the Subaccount's user. Note: You must use this parameter if you set the `send_invite` value to `1`.
avatar_url	string <url> Default: null Example: avatar_url=https://img.example.com/avatars/example.jpg The URL path to the user's Subaccount profile photo. Note: You must use the HTTPS protocol to prevent mixed content warnings when users view the image from another HTTPS URL. Warning: We reserved this parameter for future use. Do not use this parameter.
domain required	string <domain> Example: domain=example.com The Subaccount user's associated domain that the cPanel account owns.
password required	string <password> Example: password=123456luggage The Subaccount's password. Note: Email, FTP, and Web Disk services use this password.
phone_number	string Default: null Example: phone_number=+15551234567 A phone number for the Subaccount user that conforms to ITU-T's E.164 standards. Warning: We reserved this parameter for future use. Do not use this parameter.
real_name	string Default: null Example: real_name=John Doe The Subaccount user's first and/or last name.
send_invite	integer Default: 0 Possible Values: 0 1 Example: send_invite=0 Whether to send a reset password email to the Subaccount's alternate email address. `1` - Send. `0` - Do not send.
services.email.enabled	integer Default: 0 Possible Values: 0 1 Example: services.email.enabled=1 Whether to grant the Subaccount email access. `1` - Can access. `0` - Cannot access.
services.email.quota	string Example: services.email.quota=500 The maximum amount of disk space, in megabytes (MB), allocated to Subaccount's email account. `0` or `unlimited` - The subaccount has unlimited disk space. This value defaults to the defined system value. Note: This value cannot be larger than the system's maximum email quota.
services.email.send_welcome_email	integer Default: 0 Possible Values: 0 1 Example: services.email.send_welcome_email=1 Whether to send client configuration instructions to the account. `1` - Send the instructions. `0` - Do not send the instructions.
services.ftp.enabled	integer Default: 0 Possible Values: 0 1 Example: services.ftp.enabled=1 Whether to grant the Subaccount FTP access. `1` - Can access. `0` - Cannot access.
services.ftp.homedir	string <path> Example: services.ftp.homedir=/Subaccount The Subaccount's FTP home directory, relative to the cPanel account's home directory. Note: This parameter is required if you enabled the `services.ftp.homedir` parameter. The directory must exist.
services.webdisk.enabled	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabled=1 Whether to grant the Subaccount Web Disk access. `1` _ Can access. `0` - Cannot access.
services.webdisk.enabledigest	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabledigest=0 Whether to enable the Web Disk Digest Authentication. `1` - Enabled. `0` - Disabled. Note: Only enable Digest Authentication for clients that require additional compatibility support on certain versions of Windows® operating systems. This compatibility support is only required on servers that use a self-signed certificate for the `cpsrvd` and `cpdavd` daemons. We recommend that you do not use Digest Authentication.
services.webdisk.homedir	string <path> Example: services.webdisk.homedir=/Subaccount The Subaccount's Web Disk home directory, relative to the cPanel account's home directory. Note: This parameter is required if you enable the `services.webdisk.enabled` parameter.
services.webdisk.perms	string Default: "rw" Example: services.webdisk.perms=rw The Subaccount's file permissions for its Web Disk home directory. `ro` - Read-only permissions. `rw` - Read and write permissions. Note: The `services.webdisk.homedir` parameter determines the Subaccount's Web Disk home directory.
services.webdisk.private	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.private=1 Whether to set the directory's permissions to public or private. `1` - Private (`0700`). `0` - Public (`0755`).
type	string Default: "sub" Value: "sub" Example: type=sub The type of account. `sub` - A Subaccount.
username required	string <username> <= 64 characters Example: username=example The username for the Subaccount. The username can only contain alphanumeric characters, dots (`.`), hyphens (`-`), and underscores (`_`). Note: This value does not include the domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  create_user \
  domain='example.com' \
  password='123456luggage' \
  username='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_user",
"module": "UserManager",
"result": {"data": {"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 1500
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": "0.00"
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"dismissed_merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 1500
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": "0.00"
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
}
],
"has_expired_invite": 0,
"has_invite": 0,
"invite_expiration": 1591718154,
"merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 1500
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": "0.00"
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove service account link request

This function removes a service account as a link candidate to create a subaccount or link to a subaccount. When you use this function, the system removes the Link option in cPanel's User Manager interface (cPanel >> Home >> Preferences >> User Manager).

Note:

You must use at least one of the following parameters:

services.email.dismiss
services.ftp.dismiss
services.webdisk.dismiss

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The service account's associated domain.
services.email.dismiss	integer Default: 0 Possible Values: 0 1 Example: services.email.dismiss=1 Whether to dismiss the merge of the email service account. `1` - Dismiss. `0` - Do not dismiss.
services.ftp.dismiss	integer Default: 0 Possible Values: 0 1 Example: services.ftp.dismiss=1 Whether to dismiss the merge of the FTP service account. `1` - Dismiss. `0` - Do not dismiss.
services.webdisk.dismiss	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.dismiss=1 Whether to dismiss the merge of the Web Disk service account. `1` - Dismiss. `0` - Do not dismiss.
username required	string <username> <= 64 characters Example: username=example1 The username for the service account. Note: This parameter does not include the domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  dismiss_merge \
  username='example1' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "dismiss_merge",
"module": "UserManager",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete Subaccount

This function deletes a Subaccount. This function returns only metadata if no other service accounts exist with the same username and domain.

If one service account uses the same username and domain, the function returns the service account's information.
If two or more service accounts use the same username and domain, the function returns a hypothetical Subaccount.

Note:

A hypothetical Subaccount consists of two or more service accounts that use the same username and domain.
This function returns only metadata if the specified username and domain do not match any service accounts or hypothetical Subaccounts.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The Subaccount's associated domain. The domain must be one that the cPanel account owns.
username required	string <= 64 characters Example: username=example The Subaccount's username. Characters — `a-z`, `A-Z`, `0-9`, dot (`.`), hyphen (`-`), underscore (`_`) Note: This value does not include the domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  delete_user \
  username='example' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_user",
"module": "UserManager",
"result": {"data": {"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"dismissed_merge_candidates": [{ }
],
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1466258282,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"merge_candidates": [{"alternate_email": "string",
"avatar_url": "string",
"can_delete": 0,
"can_set_password": 0,
"can_set_quota": 0,
"dismissed": 0,
"dismissed_merge_candidates": ["string"
],
"domain": "string",
"full_username": "string",
"guid": "string",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 0,
"issues": ["string"
],
"merge_candidates": ["string"
],
"parent_type": "string",
"phone_number": "string",
"real_name": "string",
"services": { },
"special": 0,
"sub_account_exists": 0,
"synced_password": 0,
"type": "string",
"username": "string"
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/account",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "service",
"username": "string"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account's Subaccounts

This function lists the cPanel account's Subaccounts.

Authorizations:

BasicAuth

query Parameters

flat	integer Default: 0 Possible Values: 0 1 Example: flat=0 Whether to return Subaccounts with the same name under the merge_candidates array. `1` - Do not return. `0` - Return.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  list_users

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_users",
"module": "UserManager",
"result": {"data": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"dismissed_merge_candidates": [ ],
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"merge_candidates": [ ],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"special": 1,
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 0,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update Subaccount settings

This function edits a Subaccount.

Authorizations:

BasicAuth

query Parameters

alternate_email	string or null <email> Default: null Example: [email protected] An alternate email address for the Subaccount's user. Note: The cPanel account user could use this email address to contact the Subaccount user if their primary email address's domain is unavailable.
avatar_url	string or null <url> Default: null Example: avatar_url=https://img.example.com/avatars/example.jpg Warning: We reserved this parameter for future use. Do not use this parameter. The user's Subaccount profile photo. Note: You must use the HTTPS protocol to prevent mixed content warnings when users view the photo from another HTTPS URL.
domain required	string <domain> Example: domain=example.com The Subaccount user's associated domain. A domain that the cPanel account owns.
password	string Example: password=12345luggage The Subaccount's new password. Note: The Subaccount uses this password for email, FTP, and Web Disk services.
phone_number	string or null Default: null Example: phone_number=+15551234567 The Subaccount user's phone number. Warning: We reserved this parameter for future use. Do not use this parameter. The number conforms to the ITU-T's E.164-recommended standard for the representation of telephone numbers.
real_name	string or null Default: null Example: real_name=John Doe The Subaccount user's name. A first name. A last name. A first name and last name. An empty string.
services.email.enabled	integer Default: 0 Possible Values: 0 1 Example: services.email.enabled=1 Whether to grant the Subaccount email access. `1` - Can access. `0` - Cannot access.
services.email.quota	integer Example: services.email.quota=500 The maximum amount of disk space, in megabytes (MB), that the subaccount's email account may use. If you do not declare a value, the system defaults to the defined system value. Note: This value cannot be greater than the maximum email quota. `0` or `unlimited` - The subaccount possesses unlimited disk space.
services.ftp.enabled	integer Default: 0 Possible Values: 0 1 Example: services.ftp.enabled=1 Whether to grant the Subaccount FTP access. `1` - Can access. `0` - Cannot access.
services.ftp.homedir	string <path> Example: services.ftp.homedir=/Subaccount The Subaccount's FTP home directory. Note: This parameter is required if you enable FTP access. A relative path from the cPanel account's home directory. Note: The specified directory must exist.
services.webdisk.enabled	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabled=1 Whether to grant the Subaccount Web Disk access. `1` - Can access. `0` - Cannot access.
services.webdisk.enabledigest	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabledigest=0 Whether to enable Web Disk digest authentication. Notes: Only enable Digest Authentication for clients that require additional compatibility support on certain versions of Windows® operating systems. This compatibility support is only required on servers that use a self-signed certificate for the `cpsrvd` and `cpdavd` daemons. We recommend that you do not use Digest Authentication. `1` - Enabled `0` - Disabled.
services.webdisk.homedir	string <path> Example: services.webdisk.homedir=/Subaccount The Subaccount's Web Disk home directory. Note: This parameter is required if you enable Web Disk access. A relative path from the cPanel account's home directory.
services.webdisk.perms	string Default: "rw" Possible Values: "ro" "rw" Example: services.webdisk.perms=rw Whether to grant write permissions to the Subaccount. Note: The `services.webdisk.homedir` parameter determines the Subaccount's Web Disk home directory. `ro` - Read-only permissions. `rw` - Read and write permissions.
services.webdisk.private	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.private=1 Whether to set the Web Disk directory's permissions to public or private. `1` - Private (`0700`). `0` - Public (`0755`).
type	string Default: "sub" Value: "sub" Example: type=sub The type of account. `sub` - A Subaccount.
username required	string Example: username=example The Subaccount's username. Length - 64 characters. Characters - `a-z`, `A-Z`, `0-9`, dot (`.`), hyphen (`-`), underscore (`_`). Note: This value does not include the domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  edit_user \
  domain='example.com' \
  password='12345luggage' \
  username='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "edit_user",
"module": "UserManager",
"result": {"data": {"dismissed_merge_candidates": [{"merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"merge_candidates": [{ }
]
}
]
}
],
"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"merge_candidates": [{ }
]
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return Subaccount's information

This function lists a single Subaccount's information.

Authorizations:

BasicAuth

query Parameters

guid

required

string

Example: guid=EXAMPLE1:EXAMPLE.COM:564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37

The Subaccount's unique identifier.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  lookup_user \
  guid='EXAMPLE1:EXAMPLE.COM:564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "lookup_user",
"module": "UserManager",
"result": {"data": {"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"merge_candidates": [{ }
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"special": 1,
"webdisk": {"enabled": 0,
"enabledigest": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 0,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"dismissed_merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"merge_candidates": [{ }
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"special": 1,
"webdisk": {"enabled": 0,
"enabledigest": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 0,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
}
],
"has_expired_invite": 0,
"has_invite": 0,
"invite_expiration": 1591718154
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return service account's information

This function lists a service account's information.

Authorizations:

BasicAuth

query Parameters

full_username required	string Example: [email protected] The full username for the system account.
type required	string Possible Values: "email" "ftp" "webdisk" Example: type=email The type of system account. `email` `ftp` `webdisk`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  lookup_service_account \
  type='email' \
  full_username='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "lookup_service_account",
"module": "UserManager",
"result": {"data": {"dismissed_merge_candidates": [{"merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"merge_candidates": [{ }
]
}
]
}
],
"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example",
"merge_candidates": [{ }
]
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Unregister service account from Subaccount

This function unlinks a service account from a subaccount.

Authorizations:

BasicAuth

query Parameters

dismiss	integer Default: 0 Possible Values: 0 1 Example: dismiss=0 Whether to dismiss the service account as a merge candidate. `1` - Dismiss as merge candidate. `0` - Display as merge candidate. Note: If any email, FTP, or Web Disk accounts use the same username, cPanel's User Manager interface (cPanel >> Home >> Preferences >> User Manager) allows you to merge those accounts into a subaccount.
domain required	string <domain> Example: domain=example.com The subaccount's associated domain.
service required	string Possible Values: "email" "ftp" "webdisk" Example: service=ftp The service to unlink. `email` `ftp` `webdisk`
username required	string <username> Example: username=example The subaccount's username. Note: This value does not include the domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  unlink_service_account \
  username='example' \
  domain='example.com' \
  service='ftp'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unlink_service_account",
"module": "UserManager",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Register service account to Subaccount

This function links service accounts to subaccounts and creates a subaccount if one does not exist.

Note:

You can only link email, FTP, or Web Disk accounts.

Important

You must use at least one of the following parameters:

services.email.merge
services.ftp.merge
services.webdisk.merge

To link multiple service accounts, the service accounts must share the same username and domain.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The service account's associated domain.
services.email.merge	integer Default: 0 Possible Values: 0 1 Example: services.email.merge=1 Whether to link the email account to the subaccount. `1` - Merge. `0` - Do not merge.
services.ftp.merge	integer Default: 0 Possible Values: 0 1 Example: services.ftp.merge=1 Whether to link the FTP account to the subaccount. `1` - Merge. `0` - Do not merge.
services.webdisk.merge	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.merge=1 Whether to link the Web Disk account to the subaccount. `1` - Merge. `0` - Do not merge.
username required	string <username> Example: username=example The username for the service account that meets the account name limitations. Length - 64 characters Characters — `a-z`, `A-Z`, `0-9`, dot (`.`), hyphen (`-`), underscore (`_`). Note: This value does not include the domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  UserManager \
  merge_service_account \
  username='example' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "merge_service_account",
"module": "UserManager",
"result": {"data": {"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"dismissed": 1,
"dismissed_merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
}
],
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_expired_invite": 0,
"has_invite": 0,
"has_siblings": 0,
"invite_expiration": 1591718154,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"merge_candidates": [{"alternate_email": "[email protected]",
"avatar_url": "https://img.example.com/avatars/example.jpg",
"can_delete": 0,
"can_set_password": 1,
"can_set_quota": 0,
"domain": "example.com",
"full_username": "[email protected]",
"guid": "N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4",
"has_siblings": 0,
"issues": [{"area": "quota",
"limit": 1500,
"message": "Your account is over quota.",
"service": "email",
"type": "info",
"used": 2000
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
}
],
"parent_type": "hypothetical",
"phone_number": "+15551234567",
"real_name": "John Doe",
"services": {"email": {"enabled": 1,
"quota": 100
},
"ftp": {"enabled": 0,
"homedir": "/subaccount",
"quota": 100
},
"webdisk": {"enabled": 0,
"homedir": "/bob",
"perms": "rw",
"private": 0
}
},
"special": 1,
"sub_account_exists": 0,
"synced_password": 0,
"type": "sub",
"username": "example"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Team Roles

The Team Roles module for UAPI.

List all role feature descriptions

This function gives a list of all team roles and their included features.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  TeamRoles \
  list_feature_descriptions

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_feature_descriptions",
"module": "TeamRoles",
"result": {"data": {"features": ["Backup",
"MySQL® Databases",
"PHP"
],
"id": "database",
"title": "Database"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Team Users

The Team User module for UAPI.

Stop a team user from expiring

This function stops a team user from expiring.

Authorizations:

BasicAuth

query Parameters

user

required

string

Example: user=teamUser

The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  cancel_expire \
  user='teamUser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "expire_team_user",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set a team user to expire

This function expires a team user after a specified amount of time.

If the team user already has an expire date set, it's replaced with a new date and reason.

Authorizations:

BasicAuth

query Parameters

required	integer or string Examples: date=120days - date=1649948169 - The epoch time on which the team user account expires, or the offset from the current time, in days. Integers are treated as Unix Epoch Time unless followed by 'days'.
reason	string Example: reason=teamUser gave a two week notice. The reason for expiration.
user required	string Example: user=teamUser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  set_expire \
  user='teamUser' \
  date='120days'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_expire",
"module": "Team",
"result": {"data": 1674575562,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Reinstate a team user

This function reinstates a team user by removing any suspended or expired statuses. The reason field is also cleared.

Authorizations:

BasicAuth

query Parameters

user

required

string

Example: user=teamUser

The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  reinstate_team_user \
  user='teamUser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "reinstate_team_user",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Add roles to a team user

This function adds roles to a team user.

Note:

This action may result in team users gaining access to team owner level privileges.

Authorizations:

BasicAuth

query Parameters

role required	string Example: role=database The role or roles to add to the team user. Current roles include admin, database, email, web.
user required	string Example: user=teamuser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  add_roles \
  user='teamuser' \
  role='database'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_roles",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Sends a password reset request link to team user.

This function enables a team user to reset the password by sending a password reset request link.

Authorizations:

BasicAuth

query Parameters

user

required

string

Example: user=teamuser

The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  password_reset_request \
  user='teamuser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "password_reset_request",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set a contact email address for a team user

This function sets or changes primary and secondary email addresses.

Authorizations:

BasicAuth

query Parameters

email1	string Example: [email protected] The primary contact email address to set for the team user.
email2	string Example: [email protected] The secondary contact email address to set for the team user.
user required	string Example: user=teamUser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  set_contact_email \
  user='teamUser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_contact_email",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set password for a team user

This function replaces the current password with a new one.

Authorizations:

BasicAuth

query Parameters

password required	string Example: password=securepassword The password to set for the team user.
user required	string Example: user=teamuser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  set_password \
  user='teamuser' \
  password='securepassword'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_password",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Remove roles from a team user

This function removes roles from a team user.

Authorizations:

BasicAuth

query Parameters

role required	string Example: role=database The role or roles to remove from the team user.
user required	string Example: user=teamuser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  remove_roles \
  user='teamuser' \
  role='database'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_roles",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Add a team user

This function creates and adds a new team user.

Note:

This action may result in team users gaining access to team owner level privileges.

Authorizations:

BasicAuth

query Parameters

activation_email	integer Example: activation_email=1 Send an email to the team user that allows them to set their own password. `1` - Enabled. Note: You must pass either the `password` or `activation_email` parameter.
email1 required	string Example: [email protected] The contact email for the new team user.
email2	string Example: [email protected] The secondary email for the new team user.
	integer or string Examples: expire_date=120days - expire_date=1649948169 - The epoch time on which the team user account expires, or the offset from the current time, in days. Integers are treated as Unix Epoch Time unless followed by 'days'.
expire_reason	string Example: expire_reason=teamUser gave a two week notice. The reason for expiration.
notes	string Example: notes=This is a note about teamuser Notes about the new team user. This field should not contain private information. Maximum of 100 characters.
password	string Example: password=securepassword The password to set for the new team user. Note: You must pass either the `password` or `activation_email` parameter.
roles	string Example: roles=email,database A comma-separated list of roles assigned to the new team user. Current roles include admin, database, email, web.
services.email.enabled	integer Default: 0 Possible Values: 0 1 Example: services.email.enabled=1 Whether to create an email subaccount for the team user. A subaccount is always created for a team user, but it does not have any associated service subaccounts by default. `1` - Create an email subaccount. `0` - Do Not create an email subaccount.
services.email.quota	string Example: services.email.quota=500 The maximum amount of disk space, in megabytes (MB), allocated to the team user's email account. `0` or `unlimited` - The subaccount has unlimited disk space. This value defaults to the defined system value. Note: This value cannot be larger than the system's maximum email quota.
services.ftp.enabled	integer Default: 0 Possible Values: 0 1 Example: services.ftp.enabled=1 Whether to create an FTP subaccount for the team user. A subaccount is always created for a team user, but it does not have any associated service subaccounts by default. `1` - Create an FTP subaccount. `0` - Do Not create an FTP subaccount.
services.ftp.homedir	string <path> Example: services.ftp.homedir=/Teamusername The team user's FTP home directory, relative to the cPanel account's home directory. Note: This parameter is required if you enabled the `services.ftp.homedir` parameter. The directory must exist.
services.webdisk.enabled	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabled=1 Whether to create a Web Disk subaccount for the team user. A subaccount is always created for a team user, but it does not have any associated service subaccounts by default. `1` - Create a Web Disk subaccount. `0` - Do Not create a Web Disk subaccount.
services.webdisk.enabledigest	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabledigest=0 Whether to enable the Web Disk Digest Authentication. `1` - Enabled. `0` - Disabled. Note: Only enable Digest Authentication for clients that require additional compatibility support on certain versions of Windows® operating systems. This compatibility support is only required on servers that use a self-signed certificate for the `cpsrvd` and `cpdavd` daemons. We recommend that you do not use Digest Authentication.
services.webdisk.homedir	string <path> Example: services.webdisk.homedir=/Teamusername The team user's Web Disk home directory, relative to the cPanel account's home directory. Note: This parameter is required if you enable the `services.webdisk.enabled` parameter.
services.webdisk.perms	string Default: "rw" Example: services.webdisk.perms=rw The team user's file permissions for its Web Disk home directory. `ro` - Read-only permissions. `rw` - Read and write permissions. Note: The `services.webdisk.homedir` parameter determines the team user's Web Disk home directory.
services.webdisk.private	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.private=1 Whether to set the directory's permissions to public or private. `1` - Private (`0700`). `0` - Public (`0755`).
user required	string Example: user=teamuser The username of the team user. Follows cPanel standards.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  add_team_user \
  user='teamuser' \
  email1='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_team_user",
"module": "Team",
"result": {"data": 1674575562,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

List Team Users

This function lists the team users connected to a cPanel account. This list is given in an array by default, but can be given in a hash.

Authorizations:

BasicAuth

query Parameters

format

string

Example: format=array

The format in which the team data is listed.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  list_team

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_team",
"module": "Team",
"result": {"data": [{"contact-email": "[email protected]",
"created": 1650036110,
"expire_date": 1674575562,
"expire_reason": "team user 1 year",
"lastlogin": 1650046110,
"locale": "en",
"notes": "This is a note about team user.",
"password": "encryptedpassword",
"roles": ["email,web"
],
"secondary-contact-email": "[email protected]",
"services": {"email": "500*2**20",
"ftp": 1,
"webdisk": "rw"
},
"suspend_date": 1650046210,
"suspend_reason": "team user is on vacation",
"username": "teamuser"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Suspend a team user

This function immediately suspends a team user.

Authorizations:

BasicAuth

query Parameters

reason	string Example: reason=teamuser is on vacation The reason for suspension.
user required	string Example: user=teamuser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  suspend_team_user \
  user='teamuser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "suspend_team_user",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Remove a team user

This function removes a team user.

Authorizations:

BasicAuth

query Parameters

user

required

string

Example: user=teamuser

The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  remove_team_user \
  user='teamuser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_team_user",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Edit a team user

This function modifies a team user.

Authorizations:

BasicAuth

query Parameters

add_role	string Example: add_role=database The role or roles to add to the team user.
email1	string Example: [email protected] The primary contact email address to set for the team user.
email2	string Example: [email protected] The secondary contact email address to set for the team user.
expire_reason	string Example: expire_reason=teamUser gave a two week notice. The reason for expiration.
notes	string Example: notes=This is a note about teamUser Notes about the new team user. This field should not contain private information.
password	string Example: password=securepassword The password to set for the team user.
remove_role	string Example: remove_role=database The role or roles to remove from the team user.
services.email.enabled	integer Default: 0 Possible Values: 0 1 Example: services.email.enabled=1 Whether to create or remove an email subaccount for the team user. A subaccount is always created for a team user, but it does not have any associated service subaccounts by default. `1` - Create and associate an email subaccount. `0` - Remove any associated email subaccounts.
services.email.quota	string Example: services.email.quota=500 The maximum amount of disk space, in megabytes (MB), allocated to the team user's email account. `0` or `unlimited` - The subaccount has unlimited disk space. This value defaults to the defined system value. Note: This value cannot be larger than the system's maximum email quota.
services.ftp.enabled	integer Default: 0 Possible Values: 0 1 Example: services.ftp.enabled=1 Whether to create or remove an FTP subaccount for the team user. A subaccount is always created for a team user, but it does not have any associated service subaccounts by default. `1` - Create and associate an FTP subaccount. `0` - Remove any associated FTP subaccounts.
services.ftp.homedir	string <path> Example: services.ftp.homedir=/Teamusername The team user's FTP home directory, relative to the cPanel account's home directory. Note: This parameter is required if you enabled the `services.ftp.homedir` parameter. The directory must exist.
services.webdisk.enabled	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabled=1 Whether to create or remove a Web Disk subaccount for the team user. A subaccount is always created for a team user, but it does not have any associated service subaccounts by default. `1` - Create and associate a Web Disk subaccount. `0` - Remove any associated Web Disk subaccounts.
services.webdisk.enabledigest	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.enabledigest=0 Whether to enable the Web Disk Digest Authentication. `1` - Enabled. `0` - Disabled. Note: Only enable Digest Authentication for clients that require additional compatibility support on certain versions of Windows® operating systems. This compatibility support is only required on servers that use a self-signed certificate for the `cpsrvd` and `cpdavd` daemons. We recommend that you do not use Digest Authentication.
services.webdisk.homedir	string <path> Example: services.webdisk.homedir=/Teamusername The team user's Web Disk home directory, relative to the cPanel account's home directory. Note: This parameter is required if you enable the `services.webdisk.enabled` parameter.
services.webdisk.perms	string Default: "rw" Example: services.webdisk.perms=rw The team user's file permissions for its Web Disk home directory. `ro` - Read-only permissions. `rw` - Read and write permissions. Note: The `services.webdisk.homedir` parameter determines the team user's Web Disk home directory.
services.webdisk.private	integer Default: 0 Possible Values: 0 1 Example: services.webdisk.private=1 Whether to set the directory's permissions to public or private. `1` - Private (`0700`). `0` - Public (`0755`).
	integer or string Examples: set_expire=120days - set_expire=1649948169 - The epoch time the team user account expires on or the offset in days.
set_role	string Example: set_role=email The role or roles to set for the team user.
user required	string Example: user=teamUser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  edit_team_user \
  user='teamUser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "edit_team_user",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set notes for a team user

This function replaces the current notes field with new text.

Authorizations:

BasicAuth

query Parameters

notes required	string Example: notes=teamUser is a good employee The content of the notes field.
user required	string Example: user=teamUser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  set_notes \
  user='teamUser' \
  notes='teamUser '

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_notes",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set locale for a team user

This function sets locale for a team user.

Authorizations:

BasicAuth

query Parameters

locale required	string Example: locale=es_es The new locale for the team user.
user required	string Example: user=teamuser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  set_locale \
  user='teamuser' \
  locale='es_es'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_locale",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Set roles for a team user

This function sets roles for a team user.

Note:

This action may result in team users gaining access to team owner level privileges.

Authorizations:

BasicAuth

query Parameters

role	string Example: role=database The role or roles to set for the team user. Current roles include admin, database, email, web.
user required	string Example: user=teamuser The username of the team user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  set_roles \
  user='teamuser'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_roles",
"module": "Team",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Get number of team users with roles

This function returns the current and maximum number of team users with roles.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Team \
  get_team_users_with_roles_count

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_team_users_with_roles_count",
"module": "Team",
"result": {"data": {"max": 7,
"used": 2
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Backup

The Backup module for UAPI.

Back up cPanel account via SCP with password

This function creates a full backup to a remote server via the secure copy protocol (scp) command with a password. The system creates a file in the backup-MM.DD.YYYY_HH-mm-ss.tar.gz filename format.

Authorizations:

BasicAuth

query Parameters

directory	string Example: directory=/user The directory on the remote server that will store the backup. Note: This parameter defaults to the remote server account's default login directory.
email	string <email> Default: null Example: [email protected] The email address to receive a confirmation email when the backup completes. Note: The system does not provide confirmation if you do not pass this parameter.
homedir	string Default: "include" Possible Values: "include" "skip" Example: homedir=include How to manage the home directory in the backup. `include` — Include the home directory in the backup. `skip` — Omit the home directory from the backup.
required	string or string Example: host=example.com The remote server's hostname or IP address.
password required	string Example: password=luggage123456 The remote server account's password.
port	integer [ 1 .. 65335 ] Default: 22 Example: port=22 The port to use during the transfer.
username required	string Example: username=username The remote server account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Backup \
  fullbackup_to_scp_with_password \
  host='example.com' \
  username='username' \
  password='luggage123456'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fullbackup_to_scp_with_password",
"module": "Backup",
"result": {"data": {"pid": "2857"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Back up cPanel account via FTP

This function creates a full backup to the remote server via File Transfer Protocol (FTP). The system creates a file in the backup-MM.DD.YYYY_HH-mm-ss.tar.gz filename format.

Authorizations:

BasicAuth

query Parameters

directory	string Example: directory=/public_ftp The directory on the remote server that will store the backup. Note: This value defaults to the remote server account's default login directory. Enter the directory relative to the FTP user's login directory. For example, enter `/public_ftp` not `/home/username/public_ftp`.
email	string <email> Default: null Example: [email protected] The email address to receive a confirmation email when the backup completes. Note: The system does not provide confirmation if you do not pass this parameter.
homedir	string Default: "include" Possible Values: "include" "skip" Example: homedir=include How to manage the home directory in the backup. `include` — Include the home directory in the backup. `skip` — Omit the home directory from the backup.
required	string or string Example: host=example.com The remote server's hostname or IP address.
password required	string Example: password=luggage123456 The remote server account's password.
port	integer [ 1 .. 65535 ] Default: 21 Example: port=21 The port number to use during the transfer.
username required	string Example: username=username The remote server account's username.
variant	string Default: "active" Possible Values: "active" "passive" Example: variant=active Whether to use the `active` or `passive` FTP variant to connect to the remote server. For more information about FTP variants, read our How to Enable FTP Passive Mode documentation. `active` — The FTP server responds to the connection attempt and returns a connection request from a different port to the FTP client. `passive` — The FTP client initiates connection attempts.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Backup \
  fullbackup_to_ftp \
  username='username' \
  password='luggage123456' \
  host='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fullbackup_to_ftp",
"module": "Backup",
"result": {"data": {"pid": "2857"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Back up cPanel account via SCP with SSH key

This function creates a full backup to a remote server with a private SSH key via the secure copy protocol (scp) command. The system creates a file in the backup-MM.DD.YYYY_HH-mm-ss_username.tar.gz filename format.

Authorizations:

BasicAuth

query Parameters

directory	string Example: directory=/user The directory on the remote server that will store the backup. Note: This parameter defaults to the remote server account's default login directory.
email	string <email> Default: null Example: [email protected] The email address to receive a confirmation email when the backup completes. Note: The system does not provide confirmation if you do not pass this parameter.
homedir	string Default: "include" Possible Values: "include" "skip" Example: homedir=include How to manage the home directory in the backup. `include` — Include the home directory in the backup. `skip` — Omit the home directory from the backup.
required	string or string Example: host=example.com The remote server's hostname or IP address.
key_name required	string Example: key_name=examplesshkey The SSH key's name. Notes: To generate a private SSH key, use the UAPI `SSL::generate_key` function. To import an existing SSH key, use the cPanel API 2 `SSH::importkey` function.
key_passphrase required	string >= 4 characters Example: key_passphrase=123456luggage The SSH key's password.
port	integer [ 1 .. 65335 ] Default: 22 Example: port=22 The port to use during the transfer.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Backup \
  fullbackup_to_scp_with_key \
  host='example.com' \
  key_name='examplesshkey' \
  key_passphrase='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fullbackup_to_scp_with_key",
"module": "Backup",
"result": {"data": {"pid": "2857"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Back up cPanel account to home directory

This function creates a full backup to the user's home directory. The system creates a file in the backup-MM.DD.YYYY_HH-mm-ss_username.tar.gz filename format.

Authorizations:

BasicAuth

query Parameters

email	string <email> Default: null Example: [email protected] The email address to receive a confirmation email when the backup process completes. Note: The system does not provide confirmation if you do not pass this parameter.
homedir	string Default: "include" Possible Values: "include" "skip" Example: homedir=include How to manage the home directory in the backup. `include` — Include the home directory in the backup. `skip` — Omit the home directory from the backup.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Backup \
  fullbackup_to_homedir

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fullbackup_to_homedir",
"module": "Backup",
"result": {"data": {"pid": "2857"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return backup files

This function lists the account's backup files.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Backup \
  list_backups

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_backups",
"module": "Backup",
"result": {"data": ["2014-12-02"
],
"errors": null,
"messages": null,
"metadata": {"cnt": 1,
"transformed": 1
},
"status": 1,
"warnings": null
}
}

File Restoration

cPanel Account Backups / File Restoration

Return cPanel accounts with backup metadata

This function lists a reseller's users that have existing backup metadata.

Note:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Restore \
  get_users

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_users",
"module": "Restore",
"result": {"data": ["username"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return backups in home directory

This function lists all of the backup files and directories in the user's home directory.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

path

required

string

Example: path=/public_html/

A path to a subdirectory within the user's home directory, or any level below it.

Note:

The value of this parameter must begin and end with a forward slash (/) for security purposes.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Restore \
  directory_listing \
  path='/public_html/'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "directory_listing",
"module": "Restore",
"result": {"data": [{"conflict": 0,
"exists": 1,
"name": "public_html",
"onDiskType": "file",
"type": "file"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return backup storage locations

This function lists all of an item's backup locations. An item can be a file, a directory, or a symlink.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

exists	integer Default: 0 Possible Values: 1 0 Example: exists=0 Whether to show the `exist` return, which indicates whether the item exists in the local disk or only in the backup. `1` — Show the `exist` return's value. `0` — Do not show the `exists` return's value.
path required	string <path> Example: path=/public_html/index.php A file, directory, or symlink in the user's directory tree. Note: The value of this parameter must begin with a forward slash (`/`).

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Restore \
  query_file_info \
  path='/public_html/index.php'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "query_file_info",
"module": "Restore",
"result": {"data": [{"backupDate": "2020-07-01",
"backupID": "weekly/2017-07-01",
"backupType": "compressed",
"exists": 1,
"fileSize": 199,
"mtime": 1520043240,
"path": "/public_html/index.php",
"type": "file"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Restore file or directory

This function restores a file or directory from a backup to the file or directory's original location.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

required	string or string or string or string Example: backupID=weekly/2017-07-03 The backup's identification. `YYYY-MM-DD` — Restore a daily backup from the specified backup date. `incremental` — Restore a daily incremental backup. `weekly/YYYY-MM-DD` — Restore a weekly backup from the specified backup date. `monthly/YYYY-MM-DD` — Restore a monthly backup from the specified backup date. `weekly/incremental` — Restore a weekly incremental backup. `monthly/incremental` — Restore a monthly incremental backup.
overwrite required	integer Possible Values: 1 0 Example: overwrite=1 Whether to overwrite the file or directory on the disc with its backup replacement. `1` — Overwrite the file or directory. `0` — Do not overwrite the file or directory.
path required	string <path> Example: path=/public_html/index.php The absolute file or directory's path, within a backup, that you wish to restore. Important: The value of this parameter must begin with a forward slash (/). You must parse filenames properly to prevent a cross-site scripting (XSS) attack.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Restore \
  restore_file \
  backupID='weekly/2017-07-03' \
  path='/public_html/index.php' \
  overwrite='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "restore_file",
"module": "Restore",
"result": {"data": {"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Restore databases

This function restores a database's backup files.

Important:

When the MySQL Client role is disabled, the system also disables this function.

Note:

You must pass either the file or backup parameter.

Authorizations:

BasicAuth

query Parameters

backup	string Examples: backup=backup-1=home/user/user_db1.sql.gz backup-2=home/user/user_db2.sql.gz backup-3=home/user/user_db3.sql.gz - Restore multiple database backup files. backup=home/user/user_db1.sql.gz - Restore a single database backup file. The database backup file to restore. Important: Only pass this parameter to restore files already on the server. Note: To restore multiple database backup files, increment the parameter name. For example: `backup-1`, `backup-2`, and `backup-3`.
timeout	integer >= 0 Default: 7200 Example: timeout=3600 The maximum number of seconds to try to restore the file. `0` - The system will not time out the file restoration.
verbose	integer Default: 0 Possible Values: 0 1 Example: verbose=1 Whether to return additional information from the `/usr/local/cpanel/logs/cpbackup` log file. `1` - Return additional information. `0` - Do not return additional information.

Request Body schema: multipart/form-data

The database backup file to upload and restore.

Important:

Only pass this parameter to upload files that don't already exist on the server.
You can not pass this parameter on the command line.

Note:

To upload multiple database backup files, increment the parameter name. For example: file-1, file-2, and file-3.
Pass this file in a multipart/form-data structure.
For more information about this structure, read Mozilla's POST Method documentation.

file	string <binary>

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  Backup \
  restore_databases

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "restore_databases",
"module": "Backup",
"result": {"data": {"log_id": "2019-08-13T15:10:07Z.1",
"log_path": "/home/cptest/logs/restoredb/2019-08-13T15:10:07Z.1.log",
"messages": ["The system successfully restored the database 'user_db1' from the backup file 'user_db1.sql.gz'"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Restore email forwarders

This function restores an account's email forwarders.

Important:

When the Receive Mail role is disabled, the system also disables this function.

Note:

You must use the backup parameter when you call this function in one of the following formats:

As part of a multipart/form-data request body to upload and restore a backup file to the server. For more information about this structure, read Mozilla's POST Method documentation.
As a query parameter to restore an existing file on the server.

Authorizations:

BasicAuth

query Parameters

backup	string Examples: backup=backup-1=/home/user/aliases-example1.com.gz backup-2=/home/user/aliases-example2.com.gz backup-3=/home/user/aliases-example3.com.gz - Restore multiple email forwarder files. backup=/home/user/aliases-example.com.gz - Restore a single email forwarder file. The email forwarder file to restore. Important: Only pass this parameter to restore email forwarder files that already exist on the server. Note: To restore multiple email filter files, increment the parameter name. For example: `backup-1`, `backup-2`, and `backup-3`.
timeout	integer >= 0 Default: 7200 Example: timeout=3600 The maximum number of seconds to try to restore the file. `0` - The system will not time out the file restoration.
verbose	integer Default: 0 Possible Values: 0 1 Example: verbose=1 Whether to return additional information from the `/home/cpuser/.cpanel/logs/restore-email-forwarders` log files. `1` - Return additional information. `0` - Do not return additional information.

Request Body schema: multipart/form-data

The email forwarder file to upload and restore.

Important:

Only pass this parameter to upload files that don't already exist on the server.
You can't pass this parameter on the command line.

Note:

To upload multiple email filter files, increment the parameter name. For example: backup-1, backup-2, and backup-3.

backup

string <binary>

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  Backup \
  restore_email_forwarders

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "restore_email_forwarders",
"module": "Backup",
"result": {"data": {"log_id": "2019-08-13T15:10:07Z.1",
"log_path": "/home/cpuser/.cpanel/logs/restore-email-forwarders/2019-09-11T18:30:49Z.1.log",
"messages": ["The system successfully restored the email forwarders from the 'aliases-example.com.gz' backup."
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Restore files

This function restores an account's files.

Important:

When the File Storage role is disabled, the system also disables this function.

Note:

You must use the backup parameter when you call this function in one of the following formats:

As part of a multipart/form-data request body to upload and restore a backup file to the server. For more information about this structure, read Mozilla's POST Method documentation.
As a query parameter to restore an existing file on the server.

Authorizations:

BasicAuth

query Parameters

backup	string Examples: backup=backup-1=/home/cpuser/backup-cpuser.tld-9-10-2019_1.tar.gz backup-2=/home/cpuser/backup-cpuser.tld-9-10-2019_2.tar.gz - Restore multiple backup files. backup=/home/cpuser/backup-cpuser.tld-9-10-2019_1.tar.gz - Restore a single backup file. The backup file to restore. Important: Only pass this parameter to restore backup files that already exist on the server. Note: To restore multiple backup files, increment the parameter name. For example: `backup-1`, `backup-2`, and `backup-3`.
directory	string <path> Example: directory=/home/user/example The directory to which to restore the file. The default is the user's `home` directory.
timeout	integer >= 0 Default: 172800 Example: timeout=7200 The maximum number of seconds to try to restore the file. `0` - The system will not time out the file restoration.
verbose	integer Default: 0 Possible Values: 0 1 Example: verbose=1 Whether to return additional information from the `/home/cptest/.cpanel/logs/restorefiles` log files. `1` - Return additional information. `0` - Do not return additional information.

Request Body schema: multipart/form-data

The backup file to upload and restore.

Important:

Only pass this parameter to upload files that don't already exist on the server.
You can't pass this parameter on the command line.

Note:

To upload and restore multiple backup files, increment the parameter name. For example: backup-1, backup-2, and backup-3.

backup

string <binary>

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  Backup \
  restore_files

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "restore_files",
"module": "Backup",
"result": {"data": {"log_id": "2019-08-13T15:10:07Z.1",
"log_path": "/home/cptest/.cpanel/logs/restorefiles/2019-08-13T15:10:07Z.1.log",
"messages": ["The system successfully restored the directory /home/cpuser/point2 from the backup file backup-cpuser.tld-9-10-2019_1.tar.gz"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Restore email filters

This function restores an account's email filters.

Important:

When the Receive Mail role is disabled, the system also disables this function.

Note:

You must use the backup parameter when you call this function in one of the following formats:

As part of a multipart/form-data request body to upload and restore a backup file to the server.
As a query parameter to restore an existing file on the server.

Authorizations:

BasicAuth

query Parameters

backup	string Examples: backup=backup-1=/home/user/filter_info1.username.yaml.gz backup-2=/home/user/filter_info2.username.yaml.gz backup-3=/home/user/filter_info3.username.yaml.gz - Restore multiple email filter files. backup=/home/user/filter_info.username.yaml.gz - Restore a single email filter file. The email filter file to restore. Important: Only pass this parameter to restore email filter files that already exist on the server. Note: To restore multiple email filter files, increment the parameter name. For example: `backup-1`, `backup-2`, and `backup-3`.
timeout	integer >= 0 Default: 7200 Example: timeout=3600 The maximum number of seconds to try to restore the file. `0` - The system will not time out the file restoration.
verbose	integer Default: 0 Possible Values: 0 1 Example: verbose=1 Whether to return additional information from the `/home/cpuser/.cpanel/logs/restore-email-filters` log files. `1` - Return additional information. `0` - Do not return additional information.

Request Body schema: multipart/form-data

The email filter file to upload and restore.

Important:

Only pass this parameter to upload files that don't already exist on the server.
You can't pass this parameter on the command line.

Note:

To upload multiple email filter files, increment the parameter name. For example: backup-1, backup-2, and backup-3.
Pass this file in a multipart/form-data structure.
For more information about this structure, read Mozilla's POST Method documentation.

backup

string <binary>

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  Backup \
  restore_email_filters

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "restore_email_filters",
"module": "Backup",
"result": {"data": {"log_id": "2019-08-13T15:10:07Z.1",
"log_path": "/home/cpuser/.cpanel/logs/restore-email-filters/2019-09-11T18:30:49Z.1.log",
"messages": ["The system successfully restored the email filters from the 'filter-info.user.yaml.gz' backup."
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Application Information

cPanel Theme Management / Application Information

Return multiple apps' info from dynamicui.conf

This function retrieves an application's information from a specific theme's dynamicui.conf file.

Authorizations:

BasicAuth

query Parameters

app_keys

string

Example: app_keys=addon_domains,ftp_accounts,anonymous_ftp

A comma-separated list of an application feature names. If you do not specify this parameter, the output will include all of the applications that the dynamicui.conf file contains.

Note:

This value must match an application's feature value in the dynamicui.conf file.
For more information, read our Guide to cPanel Interface Customization - Appkeys documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Branding \
  get_applications

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_applications",
"module": "Branding",
"result": {"data": {"addon_domains": {"acontent": "",
"base64_png_image": "",
"feature": "addondomains",
"file": "addon_domains",
"group": "domains",
"height": "48",
"if": "$HASROLE{'WebServer'}",
"imgtype": "icon",
"implements": "Domains_AddonDomains",
"itemdesc": "Addon Domains",
"itemorder": "3",
"key": "addon_domains",
"onclick": "",
"plainitemdesc": "Addon Domains",
"searchtext": "Domains Addon domain Addon Domains",
"subtype": "img",
"target": "",
"type": "image",
"url": "addon/index.html",
"width": "48"
},
"anonymous_ftp": {"acontent": "",
"base64_png_image": "",
"feature": "ftpaccts",
"file": "anonymous_ftp",
"group": "files",
"height": "48",
"if": "$SERVICEPROVIDED{'ftp'} && $hasanonftp",
"imgtype": "icon",
"itemdesc": "Anonymous FTP",
"itemorder": "8",
"key": "anonymous_ftp",
"onclick": "",
"plainitemdesc": "Anonymous FTP",
"searchtext": "Anonymous FTP anonymousftp",
"subtype": "img",
"target": "",
"touch": "ftp",
"type": "image",
"url": "ftp/anonymous.html",
"width": "48"
},
"ftp_accounts": {"acontent": "",
"base64_png_image": "",
"feature": "ftpaccts",
"file": "ftp_accounts",
"group": "files",
"height": "48",
"if": "$SERVICEPROVIDED{'ftp'}",
"imgtype": "icon",
"itemdesc": "FTP Accounts",
"itemorder": "6",
"key": "ftp_accounts",
"onclick": "",
"plainitemdesc": "FTP Accounts",
"searchtext": "FTP Accounts ftp create",
"subtype": "img",
"target": "",
"touch": "ftp",
"type": "image",
"url": "ftp/accounts.html",
"width": "48"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return current user's cPanel application details

This function retrieves information about the groups and applications in the authenticated user's cPanel interface.

Authorizations:

BasicAuth

query Parameters

nvarglist

string

Example: nvarglist=pref|software|domains

A pipe-separated list of group names denoting the order in which to sort the groups. If you do not supply a value, the function does not sort the groups.

Note:

arglist is an alias for this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Branding \
  get_available_applications

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_available_applications",
"module": "Branding",
"result": {"data": {"default_group_order": {"advanced": 7,
"databases": 2,
"domains": 3,
"email": 4,
"files": 1,
"metrics": 5,
"preferences": 8,
"sample_apps": 9,
"security": 6,
"software": 6
},
"grouporder": ["files",
"databases",
"domains",
"email",
"metrics",
"security",
"software",
"advanced",
"preferences",
"pref"
],
"groups": [{"desc": "Files",
"group": "files",
"items": [{"acontent": "target=\"file_manager\"",
"base64_png_image": "",
"feature": "filemanager",
"file": "file_manager",
"group": "files",
"height": "48",
"if": "$HASROLE{'FileStorage'}",
"imgtype": "icon",
"implements": "FileManager_Home",
"itemdesc": "File Manager",
"itemorder": "1",
"key": "file_manager",
"onclick": "",
"plainitemdesc": "File Manager",
"searchtext": "File Manager file-manager",
"subtype": "img",
"target": "file_manager",
"type": "image",
"url": "filemanager/index.html",
"width": "48"
}
]
}
],
"implements": {"API_Tokens_Manager": "api_tokens",
"Backups_Home": "backup",
"Calendar_Configure": "calendar_and_contacts",
"ContactInfo_Change": "contact_information",
"Cron_Home": "cron_jobs",
"Database_MySQL": "mysql_databases",
"Database_phpMyAdmin": "php_my_admin",
"Domains_AddonDomains": "addon_domains",
"Domains_SubDomains": "subdomains",
"Email_AccountLevelFiltering": "global_email_filters",
"Email_Accounts": "email_accounts",
"Email_Authentication": "email_deliverability",
"Email_AutoResponders": "autoresponders",
"Email_BoxTrapper": "boxtrapper",
"Email_DefaultAddress": "default_address",
"Email_DeliveryReport": "track_delivery",
"Email_Disk_Usage": "email_disk_usage",
"Email_Forwarders": "forwarders",
"Email_MailingLists": "mailing_lists",
"Email_Routing": "email_routing",
"Email_SpamFilter": "apache_spam_assassin",
"Email_UserLevelFiltering": "email_filters",
"FileManager_Home": "file_manager",
"Locale_Change": "change_language",
"Password_Change": "change_password",
"SSL_TLS_Manager": "ssl_tls",
"SSL_TLS_Status": "tls_status",
"Site_Software": "site_software",
"Stats_AWStats": "awstats"
},
"index": {"addon_domains": [2,
2
],
"address_importer": [3,
10
],
"aliases": [2,
4
],
"analog_stats": [4,
5
],
"apache_handlers": [7,
5
],
"apache_spam_assassin": [3,
11
],
"api_tokens": [5,
3
],
"autoresponders": [3,
3
],
"awstats": [4,
4
],
"backup": [0,
5
],
"backup_wizard": [0,
6
],
"bandwidth": [4,
2
],
"boxtrapper": [3,
13
],
"calendar_and_contacts": [3,
14
],
"change_language": [8,
1
],
"change_password": [8,
0
],
"change_style": [8,
2
],
"contact_information": [8,
3
],
"cron_jobs": [7,
1
],
"default_address": [3,
4
],
"directory_privacy": [0,
2
],
"disk_usage": [0,
3
],
"domains": [2,
1
],
"email_accounts": [3,
0
],
"email_deliverability": [3,
9
],
"email_disk_usage": [3,
15
],
"email_filters": [3,
8
],
"email_routing": [3,
2
],
"encryption": [3,
12
],
"error_pages": [7,
4
],
"errors": [4,
1
],
"file_manager": [0,
0
],
"forwarders": [3,
1
],
"global_email_filters": [3,
7
],
"hotlink_protection": [5,
4
],
"images": [0,
1
],
"indexes": [7,
3
],
"ip_blocker": [5,
1
],
"leech_protection": [5,
5
],
"mailing_lists": [3,
5
],
"metrics_editor": [4,
7
],
"mime_types": [7,
6
],
"multiphp_ini_editor": [6,
5
],
"multiphp_manager": [6,
4
],
"mysql_database_wizard": [1,
2
],
"mysql_databases": [1,
1
],
"optimize_website": [6,
3
],
"perl_modules": [6,
1
],
"php_my_admin": [1,
0
],
"php_pear_packages": [6,
0
],
"raw_access": [4,
3
],
"redirects": [2,
5
],
"remote_mysql": [1,
3
],
"site_publisher": [2,
0
],
"site_software": [6,
2
],
"ssh_access": [5,
0
],
"ssl_tls": [5,
2
],
"subdomains": [2,
3
],
"terminal": [7,
0
],
"tls_status": [5,
6
],
"track_delivery": [3,
6
],
"track_dns": [7,
2
],
"user_manager": [8,
4
],
"version_control": [0,
7
],
"visitors": [4,
0
],
"web_disk": [0,
4
],
"webalizer": [4,
6
],
"zone_editor": [2,
6
]
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return app's info from sitemap.json

This function retrieves an application's information from a specific theme's sitemap.json file.

Authorizations:

BasicAuth

query Parameters

app_keys	string Example: app_keys=email_filters A comma-separated list of Appkey names. If you do not specify this parameter, the output will include all of the applications that the `sitemap.json` file contains. Note: This value must match an application's `key` value in the `sitemap.json` file. For more information, read our Guide to cPanel Interface Customization - Appkeys documentation.
docroot required	string <path> Example: docroot=/usr/local/cpanel/base/webmail/jupiter The absolute path to the directory containing the `sitemap.json` file. This is the path to your theme's document root.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Branding \
  get_information_for_applications \
  docroot='/usr/local/cpanel/base/webmail/jupiter'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_information_for_applications",
"module": "Branding",
"result": {"data": {"property1": {"condition": {"feature": "blockers",
"if": "!$isarchiveuser",
"module": "string"
},
"description": "Email Filters",
"icon": {"height": 32,
"url": "email_filters",
"width": 35
},
"implements": "Email_UserLevelFiltering",
"key": "email_filters",
"name": "Email Filters",
"order": 4,
"terms": ["email",
"filter",
"filters"
],
"type": "item",
"url": "mail/filters/userfilters.html"
},
"property2": {"condition": {"feature": "blockers",
"if": "!$isarchiveuser",
"module": "string"
},
"description": "Email Filters",
"icon": {"height": 32,
"url": "email_filters",
"width": 35
},
"implements": "Email_UserLevelFiltering",
"key": "email_filters",
"name": "Email Filters",
"order": 4,
"terms": ["email",
"filter",
"filters"
],
"type": "item",
"url": "mail/filters/userfilters.html"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return single app's info from dynamicui.conf

This function retrieves an application's information from the dynamicui.conf file.

Authorizations:

BasicAuth

query Parameters

app_key

required

string

Example: app_key=boxtrapper

The application's feature name. This value must match a feature's app_key value. For a list of app_key values, read our Guide to cPanel Interface Customization - Appkeys documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Branding \
  get_application_information \
  app_key='boxtrapper'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_application_information",
"module": "Branding",
"result": {"data": {"feature": "boxtrapper",
"file": "boxtrapper",
"group": "mail",
"height": 32,
"if": "$hasboxtrapper",
"imgtype": "icon",
"itemdesc": "BoxTrapper",
"itemorder": 3,
"module": "BoxTrapper",
"searchtext": "boxtrapper",
"subtype": "img",
"type": "image",
"url": "mail/boxtrapper.html",
"width": 35
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Brand Management

cPanel Theme Management / Brand Management

Return cPanel theme header and footer HTML

This function returns header and footer HTML. You can use this HTML to create a page with the same visual appearance as your cPanel theme.

Authorizations:

BasicAuth

query Parameters

page_title

required

string

Example: page_title=Test

The title of the page to wrap in the theme's headers and footers.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Chrome \
  get_dom \
  page_title='Test'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_dom",
"module": "Chrome",
"result": {"data": {"footer": "\n<!-- The Footer HTML of the user's assigned theme -->\n</html>\n\n",
"header": "\n\n<!DOCTYPE html>\n\n<html lang=\"en\" dir=\"ltr\">\n<!-- The Header HTML of the user's assigned theme -->"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Browser Cache Management

cPanel Theme Management / Browser Cache Management

Create web browser cached file override ID

This function generates a random integer (the CacheBuster ID). Use this ID to work with and around a browser's caching mechanism.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CacheBuster \
  update

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update",
"module": "CacheBuster",
"result": {"data": {"cache_id": 11381138
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return web browser cached file override ID

This function returns the current CacheBuster id. The system uses this ID to force the browser to fetch a new resource when that resource already exists in the web browser cache. This is useful when an application has updated the resource on the server. You should append this ID to the end of the url in the query-string. For example, if you are accessing a url like:

https://example.com/styled/basic/sprites/icon_spritemap.css

To force the browser to fetch the updated version, you would append the following:

https://example.com/styled/basic/sprites/icon_spritemap.css?<CacheBusterID>

Note

The application that updates the resource at this url on the server must call the CacheBuster::update function when it updates the resource to signify that update.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CacheBuster \
  read

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "read",
"module": "CacheBuster",
"result": {"data": {"cache_id": 11381138
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Language

cPanel Theme Management / Language

Return current locale settings

This function retrieves information about the user's current locale setting.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Locale \
  get_attributes

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_attributes",
"module": "Locale",
"result": {"data": {"direction": "ltr",
"encoding": "utf-8",
"locale": "en",
"name": "English"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return available locales

This function lists an account's available interface languages.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Locale \
  list_locales

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_locales",
"module": "Locale",
"result": {"data": [{"direction": "ltr",
"local_name": "Deutsch",
"locale": "de",
"name": "German"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update cPanel account locale

This function sets the account's locale.

Authorizations:

BasicAuth

query Parameters

locale

required

string

Example: locale=en

The locale's abbreviated name according to UAPI's Locale::list_locales function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Locale \
  set_locale \
  locale='en'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_locale",
"module": "Locale",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Theme Settings

cPanel Theme Management / Theme Settings

Return current theme Deprecated

This function is deprecated and does not return useful output.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Themes \
  get_theme_base

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_theme_base",
"module": "Themes",
"result": {"data": "jupiter",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update current theme

This function applies a new theme to the cPanel interface.

Note:

The /usr/local/cpanel/scripts/modify_accounts script allows you to modify the theme for many or all accounts on the server. For more information, read our The modify_accounts Script documentation.

Authorizations:

BasicAuth

query Parameters

theme

required

string

Example: theme=jupiter

The theme name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Themes \
  update \
  theme='jupiter'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update",
"module": "Themes",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return available themes

This function lists available themes.

Note:

The /usr/local/cpanel/scripts/modify_accounts script allows you to modify the style and theme for many or all accounts on the server. For more information, read our The modify_accounts Script documentation.

Authorizations:

BasicAuth

query Parameters

show_mail_themes

integer

Default: 0

Possible Values: 0 1

Example: show_mail_themes=1

Whether to list the account's mail themes.

1 — List mail themes.
0 — Do not list mail themes.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Themes \
  list

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list",
"module": "Themes",
"result": {"data": ["jupiter"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Directory Indexes

Directory Management / Directory Indexes

Return directory indexing settings

This function returns the directory indexing settings for a directory on the cPanel account and its subdirectories.

Authorizations:

BasicAuth

query Parameters

dir

required

string

Example: dir=/home/example/example.com

The directory for which to check the indexing type.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryIndexes \
  get_indexing \
  dir='/home/example/example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_indexing",
"module": "DirectoryIndexes",
"result": {"data": "disabled",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return subdirectories directory indexing settings

This function returns the directory indexing settings of the subdirectories in a directory.

Authorizations:

BasicAuth

query Parameters

dir

required

string <path>

Example: dir=/home/example/example.com

The absolute path of the directory for which to return indexing information.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryIndexes \
  list_directories \
  dir='/home/example/example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_directories",
"module": "DirectoryIndexes",
"result": {"data": {"children": [{"path": "/home/example/example.com/cgi-bin",
"state": {"index_type": "inherit"
}
}
],
"current": {"path": "/home/example/example.com",
"state": {"index_type": "inherit"
}
},
"home": {"path": "/home/example",
"state": {"index_type": "inherit"
}
},
"parent": {"path": "/home/example",
"state": {"index_type": "inherit"
}
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update directory indexing settings

This function configures the directory indexing settings for a directory on the cPanel account.

Authorizations:

BasicAuth

query Parameters

dir

required

string <path>

Example: dir=/home/example/example.com

The directory for which to manage directory indexing.

type

required

string

Possible Values: "standard" "disabled" "inherit" "fancy"

Example: type=inherit

The type of directory indexing.

standard — The directory uses directory indexing with standard formatting.
disabled — The directory doesn't use directory indexing.
inherit — The directory uses the system's default settings.
fancy — The directory uses directory indexing with Apache FancyIndexing directive. The directory will include additional information such as file size and the date of the file's last update.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryIndexes \
  set_indexing \
  dir='/home/example/example.com' \
  type='inherit'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_indexing",
"module": "DirectoryIndexes",
"result": {"data": "disabled",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Directory Privacy

Directory Management / Directory Privacy

Return authorized users for protected directory

This function returns the users who can access a password-protected directory on the cPanel account.

Authorizations:

BasicAuth

query Parameters

dir

required

string <path>

Example: dir=/home/example/example.com

The password-protected directory for which to return authorized users.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryPrivacy \
  list_users \
  dir='/home/example/example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_users",
"module": "DirectoryPrivacy",
"result": {"data": ["example1",
"example2"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return whether directory uses password protection

This function confirms whether a directory uses password protection.

Authorizations:

BasicAuth

query Parameters

dir

required

string <path>

Example: dir=/home/example/example.com

The absolute directory path on the cPanel account to check for password protection.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryPrivacy \
  is_directory_protected \
  dir='/home/example/example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_directory_protected",
"module": "DirectoryPrivacy",
"result": {"data": {"auth_name": "Protected 'example.com'",
"auth_type": "Basic",
"passwd_file": "/home/example/.htpasswds/example.com/passwd",
"protected": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable or disable protected directory

This function enables or disables password protection for a directory on the cPanel account.

Authorizations:

BasicAuth

query Parameters

authname required	string Example: authname=protectandserve The name of the directory protection authorization instance. Note: Only use this parameter when you enable password protection.
dir required	string <path> Example: dir=/home/example/example.com The absolute or relative directory path for which to enable or disable password protection.
enabled required	integer Possible Values: 0 1 Example: enabled=1 Whether to enable password protection for the directory. `1` - Enable. `0` - Disable.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryPrivacy \
  configure_directory_protection \
  dir='/home/example/example.com' \
  enabled='1' \
  authname='protectandserve'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "configure_directory_protection",
"module": "DirectoryPrivacy",
"result": {"data": {"auth_name": "protectandserve",
"auth_type": "Basic",
"passwd_file": "/home/example/.htpasswds/example.com/passwd",
"protected": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return privacy status of subdirectories

This function returns the privacy status of the subdirectories in a directory.

Authorizations:

BasicAuth

query Parameters

dir

required

string <path>

Example: dir=/home/example/example.com

The directory path for which to return the subdirectories' privacy information.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryPrivacy \
  list_directories \
  dir='/home/example/example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_directories",
"module": "DirectoryPrivacy",
"result": {"data": {"children": [{"path": "/home/example/example.com/cgi-bin",
"state": {"auth_name": "Protected 'example.com'",
"auth_type": "Basic",
"passwd_file": "/home/example/.htpasswds/example.com/passwd",
"protected": 1
}
}
],
"current": {"path": "/home/example/example.com",
"state": {"auth_name": "protected",
"auth_type": "Basic",
"passwd_file": "/home/example/.htpasswds/example.com/passwd",
"protected": 1
}
},
"home": {"path": "/home/example",
"state": {"auth_name": "protected",
"auth_type": "Basic",
"passwd_file": "/home/example/.htpasswds/example.com/passwd",
"protected": 1
}
},
"parent": {"path": "/home/example",
"state": {"auth_name": "protected",
"auth_type": "Basic",
"passwd_file": "/home/example/.htpasswds/example.com/passwd",
"protected": 1
}
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete authorized user for protected directory

This function deletes a user who can access a protected directory on the cPanel account.

Authorizations:

BasicAuth

query Parameters

dir required	string <path> Example: dir=/home/example/example.com The absolute directory path on the cPanel account from which to remove a user.
user required	string <username> Example: user=example1 The username to remove from the directory.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryPrivacy \
  delete_user \
  dir='/home/example/example.com' \
  user='example1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_user",
"module": "DirectoryPrivacy",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add authorized user for protected directory

This function adds a user who can access a protected directory on the cPanel account.

Authorizations:

BasicAuth

query Parameters

dir required	string <path> Example: dir=/home/example/example.com The directory to add users to.
password required	string Example: password=123456luggage The password for the user.
user required	string Example: user=example1 The username of the user who can access the directory.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryPrivacy \
  add_user \
  dir='/home/example/example.com' \
  user='example1' \
  password='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_user",
"module": "DirectoryPrivacy",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Directory Protection

Directory Management / Directory Protection

Return Directory Protection settings

This function returns the leech protection settings of the subdirectories in a directory.

Authorizations:

BasicAuth

query Parameters

dir

required

string <path>

Example: dir=/home/example/example.com

The absolute or relative file path in the user's home directory for which to return leech protection information.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DirectoryProtection \
  list_directories \
  dir='/home/example/example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_directories",
"module": "DirectoryProtection",
"result": {"data": {"children": [{"path": "/home/example/example.com/cgi-bin",
"state": {"has_leech_protection": 1
}
}
],
"current": {"path": "/home/example/example.com",
"state": {"has_leech_protection": 1
}
},
"home": {"path": "/home/example",
"state": {"has_leech_protection": 1
}
},
"parent": {"path": "/home/example",
"state": {"has_leech_protection": 1
}
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

DNS

The DNS module for UAPI.

Return whether domains only resolve locally

This function indicates whether the account's domains resolve exclusively to this server.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain=example.com&domain-1=example1.com&domain-2=example2.com - Multiple domains
domain=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains
domain=example.com - A single domain.

The domain to check.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, to exclude three domains, you could:

Use the domain parameter multiple times.
Use the domain, domain-1, and domain-2 parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  ensure_domains_reside_only_locally \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ensure_domains_reside_only_locally",
"module": "DNS",
"result": {"data": ["The domain resolves to Mars. Beep beep beep."
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return `ALIAS` DNS record availability & resolver

This function returns whether ALIAS and ANAME records are available and the value of the running PowerDNS (PDNS) resolver setting, if any exists. For more information, read our ALIAS documentation.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username DNS is_alias_available

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_alias_available",
"module": "DNS",
"result": {"data": {"alias": 1,
"aname": 0,
"resolver": "8.8.8.8"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domain's DNS information

This function returns DNS zone information about a domain.

Authorizations:

BasicAuth

query Parameters

domain

required

string

Example: domain=example.com

A fully qualified domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  lookup \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "lookup",
"module": "DNS",
"result": {"data": ["example.com has address 93.184.216.34",
"example.com has IPv6 address 2606:2800:220:1:248:1893:25c8:1946",
"example.com mail is handled by 0 ."
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return a parsed DNS zone

This function parses a given DNS zone.

Important:

Most DNS zones contain only 7-bit ASCII. However, it is possible for DNS zones to contain any binary sequence. An application that decodes this function's base64 output must be able to handle cases where the decoded octets do not match any specific character encoding.

Authorizations:

BasicAuth

query Parameters

zone

required

string

Example: zone=example.com

The name of one of the user’s DNS zones.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  parse_zone \
  zone='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "parse_zone",
"module": "DNS",
"result": {"data": [{"line_index": 22,
"type": "record",
"data_b64": ["dGV4YXMuY29tLg=="
],
"dname_b64": "dGV4YXMuY29tLg==",
"record_type": "MX",
"ttl": 14400
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update a DNS zone

This function updates a DNS zone by allowing multiple records to be added, modified, or removed in a single call. It also ensures modified records occupy the same number of lines as before the edit.

NOTE:

You cannot use this function to edit temporary domains.

Authorizations:

BasicAuth

query Parameters

add	Array of strings <json> [ items <json > ] Examples: add='{"dname":"example", "ttl":14400, "record_type":"A", "data":["11.22.33.44"]}' - An A record. add='{"dname":"example", "ttl":14400, "record_type":"TXT", "data":["string1", "string2"]}' - A TXT record. The records to add to the zone. Each item must be a serialized JSON object that contains: `dname` — The record’s name. `ttl` — The record’s TTL (Time-To-Live) value. `record_type` — The record’s type. For example, `A` or `TXT`. `data` — An array of strings. The format and number of the strings depend on the `record_type` value.
edit	Array of strings <json> [ items <json > ] Example: edit='{"line_index": 9, "dname":"example", "ttl":14400, "record_type":"TXT", "data":["string1", "string2"]}' The records to edit in the zone. Each item must be a serialized JSON object that contains: `line_index` — The line number in the DNS zone where the record starts. This is a 0-based index, so to edit the first line in the file use the `0` value. To edit the second line, give `1`, and so forth. `dname` — The record’s name. `ttl` — The record’s TTL (Time-To-Live) value. `record_type` — The record’s new type. For example, `A` or `TXT`. `data` — An array of strings. The format and number of the strings depend on the `record_type` value.
remove	Array of integers[ items >= 0 ] Example: remove=22 The line indexes of records to remove from the zone.
serial required	integer >= 0 Example: serial=202001010100 The current serial number in the DNS zone’s SOA (Start of Authority) record. If this value does not match the zone’s current state, the request fails.
zone required	string Example: zone=example.com The name of one of the user’s DNS zones.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username DNS mass_edit_zone zone='example.com' serial='202001010100' remove=23 add='{"dname":"example","ttl":14400,"record_type":"A","data":["127.0.0.1"]}'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "mass_edit_zone",
"module": "DNS",
"result": {"data": {"new_serial": 2021031903
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update IP addresses in zone files

This function replaces a domain's IPv4 address in the DNS zone file with the specified destination IPv4 address.

Authorizations:

BasicAuth

query Parameters

dest_ip required	string <ipv4> Example: dest_ip=192.0.2.1 The IPv4 address to use as the replacement in the zone files.
domain required	string <domain> Examples: domain=example.com domain-1=example1.com domain-2=example2.com - Update multiple domains. domain=example.com domain=example1.com domain=example2.com - Update multiple domains. domain=example.com - Update a single domain. The domain to perform the zone file updates on. Note: To update multiple domains, increment or duplicate the parameter name. For example, `domain-0`, `domain-1`, and `domain-2`.
ftp_ip	string <ipv4> Example: ftp_ip=192.0.2.1 The IPv4 address to use as the replacement for FTP records in the zone files. If this parameter is not provided, then the system will use the `dest_ip` value.
source_ip	string <ipv4> Example: source_ip=192.0.2.0 The IPv4 address to replace in the zone files. The detected source IPv4 address is one of: If there is an A record for the root of the zone and the IP address is not a loopback address, then the system will use its address. If there are any A records in the zone whose addresses are not loopback addresses, then the system will use the address of the first such A record in the zone file. If no A records exist in the zone or all A records have loopback addresses, then the system will not update the zone file. If you do not call this parameter, the system will automatically detect the IP addresses in the zone files.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --user=username DNS swap_ip_in_zones domain='example.com' source_ip='192.0.2.0' dest_ip='192.0.2.1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "swap_ip_in_zones",
"module": "DNS",
"result": {"data": [{"zone_name": "example.com",
"record_name": "example.com",
"record_type": "A",
"old_value": "192.0.2.0",
"new_value": "192.0.2.1"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether local DNS server is authoritative

This function checks whether the local server is authoritative for the domain's DNS records.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain-0=example.com domain-1=example1.com domain-2=example2.com - Check multiple domains.
domain=domain=example.com domain=example1.com domain=example2.com - Check multiple domains.
domain=example.com - Check a single domain.

The domain to check whether the local server is authoritative for the domain's DNS records.

Note:

To check multiple domains, increment or duplicate the parameter name. For example, domain-0, domain-1, and domain-2.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  has_local_authority \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_local_authority",
"module": "DNS",
"result": {"data": [{"domain": "example.com",
"local_authority": 1,
"nameservers": ["ns1.example.com",
"ns2.example.com"
],
"zone": "example.com"
},
{"domain": "example2.com",
"local_authority": 0,
"nameservers": [ ]
},
{"domain": "example3.com",
"error": "(XID 3z756a) DNS query (example3.com/SOA) timeout!",
"local_authority": 0,
"nameservers": [ ],
"zone": "example3.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

DNS Information

DNS / DNS Information

Return whether domains only resolve locally

This function indicates whether the account's domains resolve exclusively to this server.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain=example.com&domain-1=example1.com&domain-2=example2.com - Multiple domains
domain=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains
domain=example.com - A single domain.

The domain to check.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, to exclude three domains, you could:

Use the domain parameter multiple times.
Use the domain, domain-1, and domain-2 parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  ensure_domains_reside_only_locally \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ensure_domains_reside_only_locally",
"module": "DNS",
"result": {"data": ["The domain resolves to Mars. Beep beep beep."
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return `ALIAS` DNS record availability & resolver

This function returns whether ALIAS and ANAME records are available and the value of the running PowerDNS (PDNS) resolver setting, if any exists. For more information, read our ALIAS documentation.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username DNS is_alias_available

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_alias_available",
"module": "DNS",
"result": {"data": {"alias": 1,
"aname": 0,
"resolver": "8.8.8.8"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domain's DNS information

This function returns DNS zone information about a domain.

Authorizations:

BasicAuth

query Parameters

domain

required

string

Example: domain=example.com

A fully qualified domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  lookup \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "lookup",
"module": "DNS",
"result": {"data": ["example.com has address 93.184.216.34",
"example.com has IPv6 address 2606:2800:220:1:248:1893:25c8:1946",
"example.com mail is handled by 0 ."
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return a parsed DNS zone

This function parses a given DNS zone.

Important:

Most DNS zones contain only 7-bit ASCII. However, it is possible for DNS zones to contain any binary sequence. An application that decodes this function's base64 output must be able to handle cases where the decoded octets do not match any specific character encoding.

Authorizations:

BasicAuth

query Parameters

zone

required

string

Example: zone=example.com

The name of one of the user’s DNS zones.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  parse_zone \
  zone='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "parse_zone",
"module": "DNS",
"result": {"data": [{"line_index": 22,
"type": "record",
"data_b64": ["dGV4YXMuY29tLg=="
],
"dname_b64": "dGV4YXMuY29tLg==",
"record_type": "MX",
"ttl": 14400
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update a DNS zone

This function updates a DNS zone by allowing multiple records to be added, modified, or removed in a single call. It also ensures modified records occupy the same number of lines as before the edit.

NOTE:

You cannot use this function to edit temporary domains.

Authorizations:

BasicAuth

query Parameters

add	Array of strings <json> [ items <json > ] Examples: add='{"dname":"example", "ttl":14400, "record_type":"A", "data":["11.22.33.44"]}' - An A record. add='{"dname":"example", "ttl":14400, "record_type":"TXT", "data":["string1", "string2"]}' - A TXT record. The records to add to the zone. Each item must be a serialized JSON object that contains: `dname` — The record’s name. `ttl` — The record’s TTL (Time-To-Live) value. `record_type` — The record’s type. For example, `A` or `TXT`. `data` — An array of strings. The format and number of the strings depend on the `record_type` value.
edit	Array of strings <json> [ items <json > ] Example: edit='{"line_index": 9, "dname":"example", "ttl":14400, "record_type":"TXT", "data":["string1", "string2"]}' The records to edit in the zone. Each item must be a serialized JSON object that contains: `line_index` — The line number in the DNS zone where the record starts. This is a 0-based index, so to edit the first line in the file use the `0` value. To edit the second line, give `1`, and so forth. `dname` — The record’s name. `ttl` — The record’s TTL (Time-To-Live) value. `record_type` — The record’s new type. For example, `A` or `TXT`. `data` — An array of strings. The format and number of the strings depend on the `record_type` value.
remove	Array of integers[ items >= 0 ] Example: remove=22 The line indexes of records to remove from the zone.
serial required	integer >= 0 Example: serial=202001010100 The current serial number in the DNS zone’s SOA (Start of Authority) record. If this value does not match the zone’s current state, the request fails.
zone required	string Example: zone=example.com The name of one of the user’s DNS zones.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username DNS mass_edit_zone zone='example.com' serial='202001010100' remove=23 add='{"dname":"example","ttl":14400,"record_type":"A","data":["127.0.0.1"]}'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "mass_edit_zone",
"module": "DNS",
"result": {"data": {"new_serial": 2021031903
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return whether local DNS server is authoritative

This function checks whether the local server is authoritative for the domain's DNS records.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain-0=example.com domain-1=example1.com domain-2=example2.com - Check multiple domains.
domain=domain=example.com domain=example1.com domain=example2.com - Check multiple domains.
domain=example.com - Check a single domain.

The domain to check whether the local server is authoritative for the domain's DNS records.

Note:

To check multiple domains, increment or duplicate the parameter name. For example, domain-0, domain-1, and domain-2.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNS \
  has_local_authority \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_local_authority",
"module": "DNS",
"result": {"data": [{"domain": "example.com",
"local_authority": 1,
"nameservers": ["ns1.example.com",
"ns2.example.com"
],
"zone": "example.com"
},
{"domain": "example2.com",
"local_authority": 0,
"nameservers": [ ]
},
{"domain": "example3.com",
"error": "(XID 3z756a) DNS query (example3.com/SOA) timeout!",
"local_authority": 0,
"nameservers": [ ],
"zone": "example3.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

DNS Security

DNS / DNS Security

Update domain to use NSEC

This function configures the domain to use Next Secure Record (NSEC) semantics instead of Next Secure Record 3 (NSEC3) semantics.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

required

string

Example: domain=example.com

The domain on which to disable NSEC3 semantics and use NSEC semantics.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  unset_nsec3 \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unset_nsec3",
"module": "DNSSEC",
"result": {"data": {"disabled": {"example.com": 1
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable DNSSEC

This function enables DNSSEC on the domain.

Note:

After you enable DNSSEC on the domain, you must add the DNS records to your registrar.
You cannot modify the DNSSEC security key. To make any changes, you must disable (and delete) and re-create the DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

active	integer Default: 1 Possible Values: 0 1 Example: active=1 Whether to activate the newly-created key. `1` — Activate the key. `0` — Do not activate the key.
algo_num	integer [ 0 .. 255 ] Default: 8 Example: algo_num=8 The algorithm that the system uses to generate the security key. `5` — RSA/SHA-1 `6` — DSA-NSEC3-SHA1 `7` — RSASHA1-NSEC3-SHA1 `8` — RSA/SHA-256 `10` — RSA/SHA-512 `13` — ECDSA Curve P-256 with SHA-256 `14` — ECDSA Curve P-384 with SHA-384 Note: We recommend that you use `ECDSA Curve P-256 with SHA-256` if your registrar supports it.
domain required	string <domain> Examples: domain=domain-0=example0.com&domain-1=example1.com&domain-2=example2.com - To enable DNSSEC on multiple domains. domain=example.com - To enable DNSSEC on a single domain. The domain on which to enable DNSSEC. Note: To enable DNSSEC on multiple domains, increment the parameter name. For example: `domain-0`, `domain-1`, `domain-2`.
key_setup	string Default: "classic" Possible Values: "simple" "classic" Example: key_setup=classic The manner in which the system creates the security key. `simple` — Use a single key for both KSK and ZSK. Use this value when the `algo_nom` parameter is greater than `8`. `classic` — Use separate keys for KSK and ZSK. Use this value when the `algo_nom` parameter is equal to or less than `8`.
nsec3_iterations	integer [ 1 .. 500 ] Default: 7 Example: nsec3_iterations=7 The number of times that the system rehashes the first resource record hash operation. A positive integer less than `501`.
nsec3_narrow	integer Default: 1 Possible Values: 0 1 Example: nsec3_narrow=1 Whether NSEC3 will operate in Narrow or Inclusive mode. In Narrow mode, PowerDNS sends out white lies about the next secure record. Rather than query the resource record in the database, PowerDNS sends the hash plus `1` as the next secure record. `1` — Narrow mode. `0` — Inclusive mode.
nsec3_opt_out	integer Default: 0 Possible Values: 0 1 Example: nsec3_opt_out=0 Whether the system will create records for all delegations. `1` — Create records for all delegations. `0` — Create records only for secure delegations. Note: Only select `1` if you must create records for all delegations.
nsec3_salt	string <hex> <= 255 characters Example: nsec3_salt=1A2B3C4D5E6F A hexadecimal string that the system appends to the domain name before it applies the hash function to the name. For more information about the salt value, read the RFC 5155 documentation. If you do not declare a value, the system defaults to a random 64-bit value.
use_nsec3	integer Default: 1 Possible Values: 0 1 Example: use_nsec3=1 Whether the domain will use Next Secure Record (NSEC) or NSEC3 semantics. `1` — Use NSEC3 semantics. `0` — Use NSEC semantics. Note: If you use NSEC semantics (`0`), the system ignores the other NSEC3 options.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  enable_dnssec \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_dnssec",
"module": "DNSSEC",
"result": {"data": {"enabled": {"example.com": {"enabled": 1,
"new_key_id": "1",
"nsec_version": "NSEC3"
}
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Export DNSSEC security key

This function exports a DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The security key's domain.
key_id required	integer >= 1 Example: key_id=12345 The security key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  export_zone_key \
  domain='example.com' \
  key_id='12345'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "export_zone_key",
"module": "DNSSEC",
"result": {"data": {"domain": "example.com",
"key_content": "Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: 9i8AlGZkwKJj6HYZX+9OcOyCMQ0L9eHBaTg2Y83cVBSaIyiIWo54QpuiJykiuFYYHihOi+LW8vfU9A9jXLBs7DaeDkXO49OqYxfgD1vwmztJeXCQlmgxqUeD181gtSTNO43uUMkCisZft+OsJ96bdUof1UeJ1+IuSENBr1TZgYjmzBgIkmjdv8T5muPaaDfeOISLJKGOG2gI0xlyQ39ppd3CeB90cpIvFpCGjNC8nGvIqN4oyny6NftcEhaRFudbEhB6t2gI362wS5ohERK1F1rBTt+mqUwszCv46Y6p3Za3PsebWK7fR6ITnsW7KGyn3r8BxpJTHlHMwOtBPosaXw==\nPublicExponent: AQAB\nPrivateExponent: MZO5nCkatSh+0jumVImO1HLsrRAhjnzORHBLk8HLUytq9xWckBAM6+0HtLc2BMVhygD4AHfILdn3CsdmjS4CYXeGUP2B8qOXtqkCOFWdmMVRwKEInSGSjrKWPIlhplko84tbqO0yE9xrPk8dRlIwIGizDHKBsfYct/TDb5m4y7rvEHcBSm2DZz7AQL1qqC/WYI54qxHFXTId+nKsYMx/alRUV3AOSL20VSgL56VcM1luFS76ylDIWEOrQVyTFCtEcHvw3FLIOEVCM/CAErLFNlFdXHnYcRYnG/oXcsPW0DjpPNrqx8iaAOuhYFd/pu9CvKQnxYLLqXByOkSUIO3ggQ==\nPrime1: /mtiBD3gJ5Yu5ARsLew4eohRAobl4c3Bt9Gw62wmHiOJfgjbnY91H/bxc/ilnQh92yZUfxfm5z6FXEqluh0ZN3BOQTwzUEuTT9Pn00FhRfemL0UMpHn0BkoXCLwjs1XRyI0hXTOhGhH7XVczuYw/S7kWT5Cmfo4MODZ6cooR8SE=\nPrime2: 97aFfZxJcTYTKkZTc7yeUQVWTtKF25L780TRuCiG83hTSNKlmuWE2bAU/Cl2CX2NdW5sBmO5z9fEI5rA8LhuWHlKF82cXg1h50CsXkaAhFKrThMmb6SRSjIksxlz7rtK777z4En/V9v3l1yKcQ5eSQYQRHg1cCkn6NNlZPZ2G38=\nExponent1: LoHarQPSken2MGBOliZ0PJHmnRujsh82pi+Cs8ZVQXUlkRB1dNvggTNW9+gf/hCrUQA0ufbYkrTvE+vhV6AyF9xDsdEbYDYwe4s0+X0eFvgqPMHWicpxPSUWCNa7f/DUJGEIFE13yZg35twl7GkiuOjglzLN/Jxix3PN9loe5YE=\nExponent2: Mya4iAimzb7p1DfzcZnIY1ijyuEEDSRb7I8Qc2PDAjGdmRMOaV7twPnwS2XQXwNTG6Wyntsm+nlGokeJgevDtXdOSn4FxRIkXllnfow2a5yajSO9Mx6bdePG2kjuPKTmQ3195JnDJYRhqxrL566c351l7I2aE1AcUqKcdG3EU8c=\nCoefficient: T4dFDz5pQhVUQSjV0hhKHHZ1wBxiXdZeCFIfbyypWEdxGXdX2lIN264u9cGQhI+iExTEjZCaYASMBzOqnIhkHhj0M1DGYrhRCdTpgxmDwdcHniRl/XMxPGqpmsP4WFCBxmIbr3SdnqoiPMXix0SjWkHTisq5i09DBMNGIGQyqS8=\n\n",
"key_id": 12345,
"key_tag": 51640,
"key_type": "KSK",
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add DNSSEC security key

This function imports a DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The security key's domain.
key_data required	string Example: key_data=Private-key-format:%20v1.2%0AAlgorithm:%2013%20$ECDSAP256SHA256$%0APrivateKey:%20xCM281KtWE9oCsUX8fP1hDZ02/X7JCjp4QZA/DZjfX0=%0A%0A The security key data that the `pdnsutil` utility's `export-zone-key` call returns.
key_type required	string Possible Values: "ksk" "zsk" Example: key_type=ksk The security key's type. `ksk` `zsk`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  import_zone_key \
  domain='example.com' \
  key_type='ksk' \
  key_data=$'Private-key-format:%20v1.2%0AAlgorithm:%2013%20\\(ECDSAP256SHA256\\)%0APrivateKey:%20xCM281KtWE9oCsUX8fP1hDZ02/X7JCjp4QZA/DZjfX0=%0A%0A'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "import_zone_key",
"module": "DNSSEC",
"result": {"data": {"domain": "example.com",
"new_key_id": "1",
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Export DNSKEY record value

This function exports a domain's DNSKEY record value.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain from which to fetch the DNSKEY record value.
key_id required	integer >= 1 Example: key_id=12345 The DNSSEC record's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  export_zone_dnskey \
  domain='example.com' \
  key_id='12345'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "export_zone_dnskey",
"module": "DNSSEC",
"result": {"data": {"dnskey": "AwEAAch8SGW4vE6PjFWA9rbUm0AfTq+gJ0HC/nLu+2axdWHBIStt9lsOzKDorAr4vlmhlJzEzA62s96xp6mZ7XHUyWnkFwLs8obo6upL2in4h1ToOxzVl3lTs8O+kWtDq5/h1nwFlPDs9zpLJhlkTCtx2OTGbvimEYeqwPolUuSQR/Yb",
"key_id": 12345,
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domain's DS records

This function fetches a domain's Delegation of Signing (DS) records.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain-0=example0.com&domain-1=example1.com&domain-2=example2.com - To fetch DS records on multiple domains.
domain=example.com - To fetch DS records on a single domain.

The domain from which to fetch DS records.

Note:

To enable DNSSEC on multiple domains, increment the parameter name. For example: domain-0, domain-1, domain-2.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  fetch_ds_records \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_ds_records",
"module": "DNSSEC",
"result": {"data": {"example.com": {"keys": {"33930": {"active": 1,
"algo_desc": "RSA/SHA-256",
"algo_num": "8",
"algo_tag": "RSASHA256",
"bits": 1024,
"created": "1590002705",
"flags": 256,
"key_id": 2,
"key_tag": 33930,
"key_type": "ZSK",
"privatekey": "Private-key-format: v1.2\nAlgorithm: 8 (RSASHA256)\nModulus: wcZl882v587qKmt3M7+y6u+kzSgCvfgyiSGQHE2EulDcAnfEmz/ryanXMveHGBsO4L/GynYYUUsGvD2jHK1ITh8CeISiqmbUmPolf9HLQgwcT5pVcvwJ0Wmzpw5Ukmx67N7TTX+yieI5OyflP23GnJYQ5EQUzBu/DhdxhL90hYU=\nPublicExponent: AQAB\nPrivateExponent: EnoBdKrTMA5Jw7u1hQitXbt2Al3jTQvifbLmk9xMYJufLtkOtSL2L6dzLpftmL3TwFho8xspnG7D+KUD7ZMURrwxnLlqTttaL2PeaYJdQ184ezuflExppkDkdTEOqcIUuSylfAbyIdeGkVFuWr0cdjM9OFKMAkoYaVeAUP0SYU0=\nPrime1: 4eslxBBwyvXzmFqKx5TTiHfU7EHIAxUru3ykOMqD2tVMHbRAq5AMKZL6ZhuTXk8mnGppEfC6qqNKnf3VT5jLxw==\nPrime2: 25OUAsWWAJrQ4uLytsXoSbjHsVyh61DgZ4S4n2Mv7RsSHt0Q/VcuyvHXuAKb8Y0XCYczZBtEW+ZoPte/HHnsUw==\nExponent1: Xkb4AqLtvvT2i8y0/2avA9MmCtXEtuydzGbOTVjNv4OlePvgxPee67aHQhcd34xeS4XohPEVpOHx4I6t9sKHvw==\nExponent2: ulZDBRcodNrs6Z4u22yX8/gbfyhdQJUh2reG9bv2sAB/wEJaaKPT0eXqav3L2PKfCjbyJcH+AP9G+A2e4UuWgQ==\nCoefficient: mynNLSgStpQMktIEdysefyOg5jpXE3VeDZF6fbEOUg+E2ZnLBkLu4KPrriCwfl+cLagwgzx2M6wV/1QWkm8vPQ=="
},
"nsec_details": {"nsec3_hash_algo_desc": "SHA-1",
"nsec3_hash_algo_num": "1",
"nsec3_iterations": "3",
"nsec3_narrow": 1,
"nsec3_opt_out": "0",
"nsec3_salt": "fa1ac2c1rd7fbab4",
"nsec_version": "NSEC3"
}
}
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove DNSSEC security key

This function removes a DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The security key's domain.
key_id required	integer >= 1 Example: key_id=1 The security key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  remove_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_zone_key",
"module": "DNSSEC",
"result": {"data": {"domain": "example.com",
"key_id": "12",
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable DNSSEC security key

This function deactivates a DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The security key's domain.
key_id required	integer >= 1 Example: key_id=1 The security key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  deactivate_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "deactivate_zone_key",
"module": "DNSSEC",
"result": {"data": {"domain": "example.com",
"error": "Error:  Invalid key_id or domain specified: No such key present for domain.",
"key_id": "1",
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable DNSSEC

This function disables DNSSEC on the domain.

Warning:

This action is irreversible. If you disable DNSSEC on the domain, you will lose the associated keys. You can only retrieve the previous state with a full backup.
If you disable DNSSEC, you must remove the DNS records at the registrar.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain-0=example0.com&domain-1=example1.com&domain-2=example2.com - To enable DNSSEC on multiple domains.
domain=example.com - To enable DNSSEC on a single domain.

The domain on which to disable DNSSEC.

Note:

To enable DNSSEC on multiple domains, increment the parameter name. For example: domain-0, domain-1, domain-2.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  disable_dnssec \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_dnssec",
"module": "DNSSEC",
"result": {"data": {"disabled": {"example.com": 1
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create DNSSEC security key

This function generates a DNSSEC zone key for a domain.

Note:

After you enable DNSSEC on the domain, you must add the DS records to your registrar.
You cannot modify the DNSSEC security key. To make any changes, you must disable (and delete) and re-create the DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

active	integer Default: 1 Possible Values: 0 1 Example: active=1 Whether to activate the newly-created key. `1` — Activate the key. `0` — Do not activate the key.
algo_num required	integer Possible Values: 5 6 7 8 10 13 14 Example: algo_num=8 The algorithm that the system uses to generate the security key. `5` — RSA/SHA-1 `6` — DSA-NSEC3-SHA1 `7` — RSASHA1-NSEC3-SHA1 `8` — RSA/SHA-256 `10` — RSA/SHA-512 `13` — ECDSA Curve P-256 with SHA-256 `14` — ECDSA Curve P-384 with SHA-384 Note: We recommend that you use 'ECDSA Curve P-256 with SHA-256' if your registrar supports it.
domain required	string <domain> Example: domain=example.com The domain on which to enable DNSSEC.
key_size	integer [ 256 .. 2048 ] Example: key_size=2048 The key's size, in bits. Note: For the following `algo_num` and `key_type` parameters, the `key_size` defaults to the following values: `5` — ksk `2048` zsk `1024` `6` — ksk `2048` zsk `1024` `7` — ksk `2048` zsk `1024` `8` — ksk `2048` zsk `1024` `10` — ksk `2048` zsk `1024` `13` — ksk `256` zsk `256` `14` — ksk `384` zsk `384`
key_type required	string Possible Values: "ksk" "zsk" Example: key_type=ksk The type of key to add. `ksk` `zsk`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  add_zone_key \
  domain='example.com' \
  algo_num='8' \
  key_type='ksk'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_zone_key",
"module": "DNSSEC",
"result": {"data": {"domain": "example.com",
"error": "Error: Invalid key_id or domain specified: No such key present for domain.",
"new_key_id": "1",
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update domain to use NSEC3

This function configures the domain to use Next Secure Record 3 (NSEC3) semantics.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain on which to enable NSEC3 semantics.
nsec3_iterations required	integer [ 1 .. 500 ] Example: nsec3_iterations=7 The number of times that the system re-executes the first resource record hash operation.
nsec3_narrow required	integer Possible Values: 0 1 Example: nsec3_narrow=1 Whether NSEC3 will operate in Narrow mode or Inclusive mode. In Narrow mode, PowerDNS sends out white lies about the next secure record. Rather than query the resource record in the database, PowerDNS sends the hash plus 1 as the next secure record. `1` - Narrow mode. * `0` - Inclusive mode.
nsec3_opt_out required	integer Possible Values: 0 1 Example: nsec3_opt_out=0 Whether the system will create records for all delegations. `1` - Create records for all delegations. `0` - Create records only for secure delegations. Note: Only select `1` if you must create records for all delegations.
nsec3_salt required	string <hex> Example: nsec3_salt=1A2B3C4D5E6F The salt value that PowerDNS uses in the hashes. For more information about the salt value, read the RFC 5155 documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  set_nsec3 \
  domain='example.com' \
  nsec3_opt_out='0' \
  nsec3_iterations='7' \
  nsec3_narrow='1' \
  nsec3_salt='1A2B3C4D5E6F'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_nsec3",
"module": "DNSSEC",
"result": {"data": {"enabled": {"example1.com": 1
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable DNSSEC security key

This function activates a DNSSEC security key.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The security key's domain.
key_id required	integer >= 1 Example: key_id=1 The security key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DNSSEC \
  activate_zone_key \
  domain='example.com' \
  key_id='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "activate_zone_key",
"module": "DNSSEC",
"result": {"data": {"domain": "example.com",
"key_id": "1",
"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Dynamic DNS

DNS / Dynamic DNS

Create Dynamic DNS domain

This function creates a Dynamic DNS (DDNS) domain.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

description	string Example: description=Home network A human-readable string that describes the domain.
domain required	string <domain> Example: domain=home.example.com The fully-qualified domain name to create as a DDNS domain.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DynamicDNS \
  create \
  domain='home.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "DynamicDNS",
"result": {"data": {"created_time": 0,
"id": "ggiugyxxjwnkmqtwysgmvrurplmafxpq"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return Dynamic DNS domains

This function lists the user’s Dynamic DNS (DDNS) domains.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DynamicDNS \
  list

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list",
"module": "DynamicDNS",
"result": {"data": [{"created_time": 0,
"description": "My home network",
"domain": "home.example.com",
"id": "gziugyxxjwnamqtwysgmvrurplmafxpj",
"last_run_times": [0
],
"last_update_time": 0
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete Dynamic DNS domain

This function deletes an existing Dynamic DNS (DDNS) domain.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

id

required

string

Example: id=ggiugyxxjwnkmqtwysgmvrurplmafxpq

The DDNS domain’s ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DynamicDNS \
  delete \
  id='ggiugyxxjwnkmqtwysgmvrurplmafxpq'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete",
"module": "DynamicDNS",
"result": {"data": {"deleted": 1
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update Dynamic DNS domain ID

This function gives a new, randomly-generated ID to an existing Dynamic DNS (DDNS) domain.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

id

required

string

Example: id=ggiugyxxjwnkmqtwysgmvrurplmafxpq

The DDNS domain’s ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DynamicDNS \
  recreate \
  id='ggiugyxxjwnkmqtwysgmvrurplmafxpq'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "recreate",
"module": "DynamicDNS",
"result": {"data": {"id": "ggiugyxxjwnkmqtwysgmvrurplmafxpq"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update Dynamic DNS domain description

This function sets the description on a user’s Dynamic DNS (DDNS) domain.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

description required	string Example: description=Home network A human-readable string that describes the domain.
id required	string Example: id=ggiugyxxjwnkmqtwysgmvrurplmafxpq The DDNS domain’s ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DynamicDNS \
  set_description \
  id='ggiugyxxjwnkmqtwysgmvrurplmafxpq' \
  description='Home network'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list",
"module": "DynamicDNS",
"result": {"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Email DNS Settings

DNS / Email DNS Settings

Create mail exchanger record

This function creates a Mail Exchanger (MX) record. For more information about MX record settings, read our Email Routing Configuration documentation.

Important:

When you disable the Receive Mail role, the system disables this function

Authorizations:

BasicAuth

query Parameters

alwaysaccept	integer Default: 0 Possible Values: 0 1 Example: alwaysaccept=1 Whether the mail exchanger accepts all mail for the domain. `1` — The mail exchanger always accepts mail. `0` — The mail exchanger does not always accept mail.
domain required	string <domain> Example: domain=example.com The new mail exchanger's domain.
exchanger required	string <domain> Example: exchanger=mail.example.com The new mail exchanger's name.
priority required	integer >= 0 Example: priority=5 The new mail exchanger's priority value. Note: It is common practice to set a priority value that is divisible by five.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_mx \
  domain='example.com' \
  exchanger='mail.example.com' \
  priority='5'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_mx",
"module": "Email",
"result": {"data": {"checkmx": {"changed": 1,
"detected": "auto",
"isprimary": 0,
"issecondary": 0,
"local": 0,
"mxcheck": "auto",
"remote": 0,
"secondary": 0,
"warnings": ["Auto Detect of MX configuration not possible due to non-resolving MX entries. Defaulting to last known setting: local."
]
},
"results": "Added entry:\\nBind reloading on example using rndc zone: [example.com]\\n",
"status": 1,
"statusmsg": "Added entry:\\nBind reloading on example using rndc zone: [example.com]\\n"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update mail exchanger record

This function creates a Mail Exchanger (MX) record. For more information about MX record settings, read our Email Routing Configuration documentation.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

alwaysaccept	integer Default: 0 Possible Values: 0 1 Example: alwaysaccept=1 Whether the mail exchanger accepts all mail for the domain. `1` — The mail exchanger always accepts mail. `0` — The mail exchanger does not always accept mail.
domain required	string <domain> Example: domain=example.com The mail exchanger's domain.
exchanger required	string <domain> Example: exchanger=mail.example.com The mail exchanger's name.
oldexchanger required	string <domain> Example: oldexchanger=mail.example.com The mail exchanger's current name.
oldpriority	integer >= 0 Example: oldpriority=5 The mail exchanger's current priority value. If multiple MX entries match the `oldexchanger` value, the system uses this parameter to find the correct entry.
priority required	integer >= 0 Example: priority=15 The mail exchanger's new priority value. Note: Common practice sets a priority value divisible by five.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  change_mx \
  domain='example.com' \
  exchanger='mail.example.com' \
  oldexchanger='mail.example.com' \
  priority='15'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "change_mx",
"module": "Email",
"result": {"data": {"checkmx": {"changed": 1,
"detected": "auto",
"isprimary": 0,
"issecondary": 0,
"local": 0,
"mxcheck": "auto",
"remote": 0,
"secondary": 0,
"warnings": ["Auto Detect of MX configuration not possible due to non-resolving MX entries. Defaulting to last known setting: local."
]
},
"results": "Replacing existing entry on line matched old entry and old priority: 51:\\nBind reloading on example using rndc zone: [example.com]",
"status": 1,
"statusmsg": "Replacing existing entry on line matched old entry and old priority: 51:\\nBind reloading on example using rndc zone: [example.com]"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete mail exchanger record

This function deletes a Mail Exchanger (MX) record. For more information about MX record settings, read our Email Routing Configuration documentation.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The mail exchanger's domain.
exchanger required	string Example: exchanger=mail.example.com The mail exchanger's name.
priority required	integer >= 1 Example: priority=15 The mail exchanger's priority value. If multiple MX entries match the exchanger value, the system uses this parameter to find the correct entry.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_mx \
  domain='example.com' \
  exchanger='mail.example.com' \
  priority='15'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_mx",
"module": "Email",
"result": {"data": {"checkmx": {"changed": 1,
"detected": "auto",
"isprimary": 0,
"issecondary": 0,
"local": 0,
"mxcheck": "auto",
"remote": 0,
"secondary": 0,
"warnings": "Auto Detect of MX configuration not possible due to non-resolving MX entries. Defaulting to last known setting: local."
},
"results": "Removed entry: example.com. IN MX 15 mail.example.com\nBind reloading on example using rndc zone: [example.com]",
"status": 1,
"statusmsg": "Removed entry: example.com. IN MX 15 mail.example.com\nBind reloading on example using rndc zone: [example.com]"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Apply DMARC records to domains.

This function applies a DMARC record to the specified domain(s)

Authorizations:

BasicAuth

query Parameters

domain

string <domain>

Examples:

domain=domain-1=example1.com domain-2=example2.com domain-3=example3.com - Enable multiple domains' DMARC records.
domain=domain=example1.com domain=example2.com domain=example3.com - Enable multiple domains' DMARC records.
domain=example.com - Enable a single domain's DMARC records.

The domain for which to apply the DMARC record.

Note:

To enable multiple domain DMARC records, duplicate or increment the parameter. For example, to enable DMARC records for three domains, perform either of the following actions:

Use the domain parameter three times.
Use the domain, domain-1, and domain-2 parameters.

If you do not include this argument, the system applies the DMARC record to all the user's domains.

You cannot use this function to edit temporary domains' DMARC records.

policy

required

string

Example: policy=v=DMARC1;p=reject;pct=100;rua=mailto:[email protected]

The DMARC record to apply to the requested domains.

Note:

Visit the following link for more information about the DMARC record specification: https://dmarc.org/resources/specification/

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  apply_dmarc \
  domain='example.com' \
  policy='v=DMARC1; p=reject;'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "apply_dmarc",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "[ADD:TXT@_dmarc.example.com:v=DMARC1; p=reject;]",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate domains' DMARC records

This function checks the validity of the current DMARC record for one or more domains.

Authorizations:

BasicAuth

query Parameters

domain

string <domain>

Examples:

domain=domain=example.com,domain=another.com,domain=yetanother.com - Check DMARC records for multiple domains.
domain=domain=example.com - Check DMARC records for a single domain.

The domain for which to check the DMARC record.

Note:

If you do not include this argument, the system will validate DMARC records for all domains owned by the user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  validate_current_dmarcs \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "validate_current_dmarcs",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"error": "(XID 4krw35) DNS returned SERVFAIL (code 2)\nin response to the system's query for _dmarc.example.com\nTXT records.",
"record": "v=DMARC1; p=none;",
"state": "VALID",
"subdomain": "_dmarc.example.com",
"suggested": "v=DMARC1; p=none;"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove DMARC record from domain(s)

This function removes the DMARC record for domains.

Authorizations:

BasicAuth

query Parameters

domain

string

Examples:

domain=domain=example.com&domain=example2.com&domain=example.com - Multiple domains.
domain=example.com - A single domain.

The domain from which to remove the DMARC record.

Note:

If you do not include this argument, the system will remove all DMARC records from all domains owned by the user.

To remove multiple domain DMARC records, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

You cannot remove DMARC records on temporary domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  remove_dmarc \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_dmarc",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "[REMOVE:TXT@_dmarc.example.com:v=DMARC1; p=reject;]",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return mail exchanger records

This function lists Mail Exchanger (MX) records.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

string <domain>

Example: domain=example.com

The domain to query. If you do not use this parameter, the function returns MX records for all of the cPanel account's domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_mxs

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_mxs",
"module": "Email",
"result": {"data": [{"alwaysaccept": 1,
"detected": "local",
"domain": "example.com",
"entries": [{"domain": "example.com",
"entrycount": 1,
"mx": "mx.example.com",
"priority": 5,
"row": "odd"
}
],
"local": 1,
"mx": "mx.example.com",
"mxcheck": "auto",
"remote": 0,
"secondary": 0,
"status": 1,
"statusmsg": "Fetched MX List"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable domains' DKIM records

This function enables DomainKeys Identified Mail (DKIM) records on the DNS server for one or more domains.

Note:

If a DKIM record does not exist on the server, this function will install a new DKIM record.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain-1=example1.com domain-2=example2.com domain-3=example3.com - Enable multiple domains' DKIM records.
domain=domain=example1.com domain=example2.com domain=example3.com - Enable multiple domains' DKIM records.
domain=example.com - Enable a single domain's DKIM records.

The domain for which to enable DKIM records on the DNS server.

Note:

To enable multiple domain DKIM records, duplicate or increment the parameter. For example, to perform this for three domains, you could:

Use the domain parameter multiple times.
Use the domain, domain-1, and domain-2 parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  enable_dkim \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_dkim",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "[no changes needed]",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate domains' DKIM private keys

This function confirms the validity of a DomainKeys Identified Mail (DKIM) key for one or more domains.

Notes:

If an existing DKIM key does not meet the server's security requirements, the system replaces the existing DKIM key.
If no DKIM key exists, the system creates a new key for the domain.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain=example.com&domain=example2.com&domain=example3.com - Multiple domains.
domain=example.com - A single domain.

The domain for which to confirm a valid DKIM key exists.

Note:

To check the DKIM key validity for multiple domains, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  ensure_dkim_keys_exist \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ensure_dkim_keys_exist",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "created new key",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove domains' DKIM records

This function removes the DomainKeys Identified Mail (DKIM) records on the DNS server for one or more domains.

Authorizations:

BasicAuth

query Parameters

domain

required

string

Examples:

domain=domain=example.com&domain=example2.com&domain=example.com - Multiple domains.
domain=example.com - A single domain.

The domain for which to remove DKIM records on the DNS server.

Note:

To remove multiple domain DKIM records, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  disable_dkim \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_dkim",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "[REMOVE:TXT@default._domainkey:v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiLMNOpQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO/xJtrPZKskZF8/sU0zWGTqKUOErlyJfoJzMDUv3/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB\\;]",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domains' DKIM private keys

This function returns a domain's installed DKIM private key in Privacy-Enhanced Mail (PEM) format.

Warning:

We strongly recommend that you protect your private key. If others obtain your private DKIM key, they could sign emails and impersonate you as a sender.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain=example.com&domain=example2.com&domain=example3.com - Multiple domains.
domain=example.com - A single domain.

The domain for which to retrieve the installed DKIM private key.

Note:

To retrieve multiple domain DKIM keys, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  fetch_dkim_private_keys \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_dkim_private_keys",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"pem": "-----BEGIN RSA PRIVATE KEY-----\nMIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G\nA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2VydGlmaWNhdGUgYXV0aG9y\naXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdudVRMUyBjZXJ0aWZpY2F0\nZSBhdXRob3JpdHkwHhcNMTEwNTIzMjAzODIxWhcNMTIxMjIyMDc0MTUxWjB9MQsw\nCQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQLExxHbnVUTFMgY2Vy\ndGlmaWNhdGUgYXV0aG9yaXR5MQ8wDQYDVQQIEwZMZXV2ZW4xJTAjBgNVBAMTHEdu\ndVRMUyBjZXJ0aWZpY2F0ZSBhdXRob3JpdHkwWTATBgcqhkjOPQIBBggqhkjOPQMB\nBwNCAARS2I0jiuNn14Y2sSALCX3IybqiIJUvxUpj+oNfzngvj/Niyv2394BWnW4X\nuQ4RTEiywK87WRcWMGgJB5kX/t2no0MwQTAPBgNVHRMBAf8EBTADAQH/MA8GA1Ud\nDwEB/wQFAwMHBgAwHQYDVR0OBBYEFPC0gf6YEr+1KLlkQAPLzB9mTigDMAoGCCqG\nSM49BAMCA0gAMEUCIDGuwD1KPyG+hRf88MeyMQcqOFZD0TbVleF+UsAGQ4enAiEA\nl4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo==\n-----END RSA PRIVATE KEY-----\n"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add domains' DKIM record keys

This function installs existing keys for use in a DomainKeys Identified Mail (DKIM) record. This is useful if you do not want the system to generate keys for DKIM records.

Note:

This function does not update the local DNS server's records.
If the local DNS server is authoritative for the domain's DNS records, use the UAPI EmailAuth::enable_dkim function to update the local DNS server's DNS records.
- We recommend that you use the UAPI EmailAuth::install_dkim_private_keys and EmailAuth::enable_dkim functions in a batch UAPI call.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain=example&domain=example2.com&domain=example3.com - Multiple domains.
domain=example - A single domain.

The domain for which to install a DKIM private key on the local server.

Note:

To install multiple RSA private keys for multiple domains, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

key

required

string <pem-private-key>

Example: key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0aAAAAB3NzaC1yc2EAAAABIwAAAQEA5kSivOqhs0U9ZMN20nxFe27QZ3t0lT2zbH7OSXylKd%0a1rjAjYXGnSXC9j2uaZlemHlptBKVziMJC86ha7Hcj6dVOVrDQ6vF4q34bOCjtKLphQ0IjB%0azVIvqILH9eLJdRaOrS34CmgmPaisrCk5wKVlakygvUfcj3HzaTKS6THyZDGx5shdTpa9lb%0ay8tpOD3JceV7ay4w8r0DipoKPC0OLpvS4EABEeMo9sx8zQEaKv03XygjNCCYtFvxlQQIRG%0alVoL7mPaHSaL3anI05RpNbm/PS+9BhZg+BqNjU4ofHBbfkXk5MiN6M7ieR4Sk5BquccboG%0aF13U5slNgmCEekdt0amw%0a-----END%20RSA%20PRIVATE%20KEY-----%0a

An RSA key in Privacy-Enhanced Mail (PEM) format.

Note:

You must provide this parameter for each domain parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  install_dkim_private_keys \
  domain='example' \
  key='-----BEGIN%20RSA%20PRIVATE%20KEY-----%0aAAAAB3NzaC1yc2EAAAABIwAAAQEA5kSivOqhs0U9ZMN20nxFe27QZ3t0lT2zbH7OSXylKd%0a1rjAjYXGnSXC9j2uaZlemHlptBKVziMJC86ha7Hcj6dVOVrDQ6vF4q34bOCjtKLphQ0IjB%0azVIvqILH9eLJdRaOrS34CmgmPaisrCk5wKVlakygvUfcj3HzaTKS6THyZDGx5shdTpa9lb%0ay8tpOD3JceV7ay4w8r0DipoKPC0OLpvS4EABEeMo9sx8zQEaKv03XygjNCCYtFvxlQQIRG%0alVoL7mPaHSaL3anI05RpNbm/PS+9BhZg+BqNjU4ofHBbfkXk5MiN6M7ieR4Sk5BquccboG%0aF13U5slNgmCEekdt0amw%0a-----END%20RSA%20PRIVATE%20KEY-----%0a'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "install_dkim_private_keys",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "[ADD:TXT@default._domainkey:v=DKIM1; k=rsa; p=AAAAB3NzaC1yc2EAAAABIwAAAQEA5kSivOqhs0U9ZMN20nxFe27QZ3t0lT2zbH7OSXylKd1rjAjYXGnSXC9j2uaZlemHlptBKVziMJC86ha7Hcj6dVOVrDQ6vF4q34bOCjtKLphQ0IjBzVIvqILH9eLJdRaOrS34CmgmPaisrCk5wKVlakygvUfcj3HzaTKS6THyZDGx5shdTpa9lby8tpOD3JceV7ay4w8r0DipoKPC0OLpvS4EABEeMo9sx8zQEaKv03XygjNCCYtFvxlQQIRGlVoL7mPaHSaL3anI05RpNbm/PS+9BhZg+BqNjU4ofHBbfkXk5MiN6M7ieR4Sk5BquccboGF13U5slNgmCEekdt0amw;]",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add domains' SPF records

This function installs a Sender Policy Framework (SPF) record for a domain on the DNS server.

Authorizations:

BasicAuth

query Parameters

domain required	string Examples: domain=domain=example.com&domain=example2.com&domain=example3.com - Multiple domains. domain=example.com - A single domain. The domain for which to install an SPF record on the DNS server. Note: To install multiple SPF records, duplicate the parameter name. For example, use the `domain=example.com`, `domain=example2.com`, and `domain=example3.com` parameters.
record required	string Example: record="v=spf1 ip4:10.0.0.1 %2Ba %2Bmx %2Bip4:10.0.0.2 %2Bip4:10.0.0.3 -all" An SPF record. Note: You must provide this parameter for each `domain` parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  install_spf_records \
  domain='example.com' \
  record='"v=spf1 ip4:10.0.0.1 %2Ba %2Bmx %2Bip4:10.0.0.2 %2Bip4:10.0.0.3 -all"'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "install_spf_records",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"msg": "[ADD:[email protected].:v=spf1 ip4:10.0.0.1 %2Ba %2Bmx %2Bip4:10.0.0.2 %2Bip4:10.0.0.3 -all]",
"status": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate domains' SPF records

This function retrieves the the Sender Policy Framework (SPF) records for one or more domains.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=`domain`=example.com,`domain`=another.com,`domain`=yetanother.com `domain`=example.com,`domain-1`=another.com,`domain-2`=yetanother.com - Check `SPF` records for a multiple domains.
domain=example.com - Check `SPF` records for a single domain.

The domain for which to check the SPF records.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  validate_current_spfs \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "validate_current_spfs",
"module": "EmailAuth",
"result": {"data": [{"domain": "example.com",
"error": "(XID rm8h9f) DNS returned SERVFAIL (code 2)\nin response to the systems query for example2.coms\nTXT records.",
"expected": "ip6:0:0:0:0:0:ffff:c0a8:101",
"ip_address": "0:0:0:0:0:ffff:c0a8:101",
"ip_version": 6,
"records": [{"current": "v=spf1 +a +mx ip6:0:0:0:0:0:ffff:c0a8:101 ~all",
"reason": "'example.com: Sender\nis not authorized by default to use ''example.com''\nin ''helo'' identity, however domain is not\ncurrently prepared for false failures (mechanism\n''~all'' matched)'",
"state": "PASS"
}
],
"state": "VALID"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate domains' PTR records

This function validates the pointer records (PTR) for IPv4 and IPv6 addresses that the account's domains send mail from. It retrieves the PTR records for each IP address and determines which of the domain's IP addresses send mail. It then validates the PTR records for each IP address and validates the A or AAAA records pointing to each domain. This function also ensures that at least one of that domain's A or AAAA records points back to the IP address.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=`domain`=example.com,`domain`=another.com,`domain`=yetanother.com `domain`=example.com,`domain-1`=another.com,`domain-2`=yetanother.com - Check PTR records for a multiple domains.
domain=example.com - Check PTR records for a single domain.

The domain for which to validate the PTR records.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  validate_current_ptrs \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "validate_current_ptrs",
"module": "EmailAuth",
"result": {"data": [{"arpa_domain": "1.0.0.10.in-addr.arpa",
"domain": "example.com",
"error": "1.1.1.1.1 is not a valid IP address.",
"helo": "example.com",
"ip_address": "10.0.0.1",
"ip_version": 4,
"nameservers": ["ns1.example.com"
],
"ptr_records": [{"domain": "example.com",
"forward_records": ["10.0.0.1"
],
"state": "VALID"
}
],
"state": "VALID"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate domains' DKIM records

This function retrieves and checks the DomainKeys Identified Mail (DKIM) records for one or more domains.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain=example.com,domain=another.com,domain=yetanother.com domain=example.com,domain-1=another.com,domain-2=yetanother.com - Check DKIM records for a multiple domains.
domain=example.com - Check DKIM records for a single domain.

The domain for which to check the DKIM records.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EmailAuth \
  validate_current_dkims \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "validate_current_dkims",
"module": "EmailAuth",
"result": {"data": [{"domain": "default._domainkey.example.com",
"error": "(XID 4krw35) DNS returned SERVFAIL (code 2)\nin response to the systems query for default._domainkey.example2.coms\nTXT records.",
"expected": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\\/xJtrPZKskZF8\\/sU0zWGTqKUOErlyJfoJzMDUv3\\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB",
"records": [{"current": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\\/xJtrPZKskZF8\\/sU0zWGTqKUOErlyJfoJzMDUv3\\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB",
"reason": "example.com: The DKIM version must be \"DKIM1\".",
"state": "VALID"
}
],
"state": "VALID",
"validity_cache_update": "valid"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Domain

The Domain module for UAPI.

Return whether a domain is temporary

This function determines whether a domain is temporary.

Note:

For more information about temporary domains, read our Temporary Domains documentation.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

A domain on the cPanel account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL

uapi --output=jsonpretty \
  --user=username \
  Domain \
  is_temporary_domain \
  domain=example.com

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_temporary_domain",
"module": "Domain",
"result": {"data": 1,
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Convert a temporary domain to a registered domain

This function converts a temporary domain into a registered domain and moves its document root files to the new document root location.

Note:

For more information about temporary domains, read our Temporary Domains documentation.
You cannot use this function to convert a cPanel account's main domain.

Authorizations:

BasicAuth

query Parameters

docroot	string Example: docroot=example.com The path to the domain's document root directory. If you do not specify a value, this parameter defaults to the domain's name. Note: The function will create a symlink in place of the previous temporary domain's document root directory. The symlink will point to the registered domain's document root.
domain required	string <domain> Example: domain=wonderful-fushsia-owl.10-20-30-40.cpanel.site A valid temporary domain on the account.
registered required	string <domain> Example: registered=example.com A valid domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL

uapi --output=jsonpretty \
  --user=username \
  Domain \
  convert_temporary_to_registered \
  domain=wonderful-fushsia-owl.10-20-30-40.cpanel.site \
  registered=example.com

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "convert_temporary_to_registered",
"module": "Domain",
"result": {"data": {"message": "Domain wonderful-fushsia-owl.10-20-30-40.cpanel.site successfully converted to example.com"
},
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Direct Link Protection (Hotlink)

Domain Management / Direct Link Protection (Hotlink)

Enable hotlink protection

This function adds hotlink protection for a site. Hotlink protection will redirect users to another URL if they navigate to a file with a specified extension, but an allowed URL did not refer them.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

allow_null	integer Possible Values: 0 1 Example: allow_null=1 Whether the domain allows hotlinks. `1` - Allows. `0` - Does not allow.
extensions required	string Examples: extensions=foo,bar - Add hotlink protection for multiple file extensions. extensions=foo - Add hotlink protection for a single file extension. File types to hotlink protect. Note: To protect multiple file types, use a comma-separated list.
redirect_url required	string <url> Example: redirect_url=http://redirect.example.com/ The URL to which the system sends hotlinkers.
urls required	string Examples: urls=http://example.com/ http://foobar.com/ - Add hotlink protection for multiple sites. urls=http://example.com/ - Add hotlink protection for a single site. The site to hotlink protect. Note: To protect multiple URLs, separate each URL with a newline character.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  add_hotlink \
  urls='http://example.com/' \
  extensions='foo' \
  redirect_url='http://redirect.example.com/'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_hotlink",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable hotlink protection

This function removes hotlink protection.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  delete_hotlink

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_hotlink",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domains with hotlink protection

This function lists domains with hotlink protection.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  list_hotlinks

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_hotlinks",
"module": "Mime",
"result": {"data": {"allow_null": 1,
"extensions": "jpg,jpeg,gif,png,bmp",
"redirect_url": "http://redirect.example.com/",
"state": "disabled",
"urls": ["http://example.com/"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Domain

The Domain module for UAPI.

Return whether a domain is temporary

This function determines whether a domain is temporary.

Note:

For more information about temporary domains, read our Temporary Domains documentation.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

A domain on the cPanel account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL

uapi --output=jsonpretty \
  --user=username \
  Domain \
  is_temporary_domain \
  domain=example.com

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_temporary_domain",
"module": "Domain",
"result": {"data": 1,
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Convert a temporary domain to a registered domain

This function converts a temporary domain into a registered domain and moves its document root files to the new document root location.

Note:

For more information about temporary domains, read our Temporary Domains documentation.
You cannot use this function to convert a cPanel account's main domain.

Authorizations:

BasicAuth

query Parameters

docroot	string Example: docroot=example.com The path to the domain's document root directory. If you do not specify a value, this parameter defaults to the domain's name. Note: The function will create a symlink in place of the previous temporary domain's document root directory. The symlink will point to the registered domain's document root.
domain required	string <domain> Example: domain=wonderful-fushsia-owl.10-20-30-40.cpanel.site A valid temporary domain on the account.
registered required	string <domain> Example: registered=example.com A valid domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL

uapi --output=jsonpretty \
  --user=username \
  Domain \
  convert_temporary_to_registered \
  domain=wonderful-fushsia-owl.10-20-30-40.cpanel.site \
  registered=example.com

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "convert_temporary_to_registered",
"module": "Domain",
"result": {"data": {"message": "Domain wonderful-fushsia-owl.10-20-30-40.cpanel.site successfully converted to example.com"
},
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Domain Information

Domain Management / Domain Information

Return built-in subdomain aliases

This function returns the built-in subdomain aliases for an account's main domain.

Note:

This function retrieves data from the /var/cpanel/userdata/user/domain file, where user represents the cPanel account username and domain represents the domain. For this reason, actual output may not contain all of the returns that this document lists.

Authorizations:

BasicAuth

query Parameters

hide_temporary_domains

integer

Default: 0

Possible Values: 1 0

Example: hide_temporary_domains=1

Whether to hide domain aliases if the main domain is a temporary domain.

1 — Return empty array if the main domain is a temporary domain.
0 — Show aliases regardless of domain type.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DomainInfo \
  main_domain_builtin_subdomain_aliases

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "main_domain_builtin_subdomain_aliases",
"module": "DomainInfo",
"result": {"data": ["mail",
"www"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return the cPanel account's primary domain

This function returns the cPanel account's main domain.

Authorizations:

BasicAuth

query Parameters

hide_temporary_domains

integer

Default: 0

Possible Values: 1 0

Example: hide_temporary_domains=1

Whether to hide temporary domains from the response.

1 — Return null if the main domain is a temporary domain.
0 — Return the main domain if it's a temporary domain.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DomainInfo \
  primary_domain

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "primary_domain",
"module": "DomainInfo",
"result": {"data": {"primary_domain": "example.com"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return all domains' hosting configuration

This function lists user data for the cPanel account's domains.

Note:

This function retrieves data from the /var/cpanel/userdata/user/domain file, where user represents the cPanel account username and domain represents the domain. For this reason, actual output may not contain all of the returns that this document lists.

Authorizations:

BasicAuth

query Parameters

format	string Default: "hash" Possible Values: "hash" "list" Example: format=hash The function's return format. `hash` — Use a hash format. The function will return objects based on the domain type. `list` — Use a list format. The function will return an array of objects, where each object is a domain.
hide_temporary_domains	integer Default: 0 Possible Values: 1 0 Example: hide_temporary_domains=1 Whether to hide temporary domains from the response arrays. `1` — Hide temporary domains from `addon_domains`, `sub_domains`, and `parked_domains` arrays. `0` — Return all domains, including the temporary domains.
return_https_redirects_status	integer Default: 0 Possible Values: 1 0 Example: return_https_redirects_status=1 Whether to return the secure redirect status of the addon domains. `1` — Return the status. `0` — Do not return the status.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DomainInfo \
  domains_data

Response samples

200

Content type

application/json

Example

Output in hash return format.

{"data": {"addon_domains": [{"all_aliases_valid": "0",
"can_https_redirect": "0",
"documentroot": "/home/user/public_html/seconddomain.com",
"domain": "seconddomain.com",
"group": "user",
"hascgi": "1",
"homedir": "/home/user",
"ip": "192.168.0.128",
"ipv6": null,
"is_https_redirecting": "0",
"is_temporary": "0",
"no_cache_update": "0",
"owner": "root",
"serveradmin": "[email protected]",
"serveralias": "seconddomain.com www.seconddomain.com www.seconddomain.example.com",
"servername": "seconddomain.example.com",
"type": "addon_domain",
"usecanonicalname": "Off",
"user": "user",
"userdirprotect": ""
},
{"all_aliases_valid": "0",
"can_https_redirect": "0",
"documentroot": "/home/user/public_html/subdomain",
"domain": "exampledomain.com",
"group": "user",
"hascgi": "1",
"homedir": "/home/user",
"ip": "192.168.0.128",
"ipv6": null,
"is_https_redirecting": "0",
"is_temporary": "0",
"no_cache_update": "0",
"owner": "root",
"serveradmin": "[email protected]",
"serveralias": "exampledomain.com www.exampledomain.com www.subdomain.example.com",
"servername": "subdomain.example.com",
"type": "addon_domain",
"usecanonicalname": "Off",
"user": "user",
"userdirprotect": ""
},
{"all_aliases_valid": "0",
"can_https_redirect": "0",
"documentroot": "/home/user/addondomain/home/dir",
"domain": "addondomain.com",
"group": "user",
"hascgi": "1",
"homedir": "/home/user",
"ip": "192.168.0.128",
"ipv6": null,
"is_https_redirecting": "0",
"is_temporary": "0",
"main_domain": {"all_aliases_valid": "0",
"can_https_redirect": "0",
"customlog": [{"format": "combined",
"target": "/usr/local/apache/domlogs/example.com"
},
{"format": "\"%{%s}t %I .\\n%{%s}t %O .\"",
"target": "/usr/local/apache/domlogs/example.com-bytes_log"
}
],
"documentroot": "/home/user/public_html",
"domain": "example.com",
"group": "user",
"hascgi": "1",
"homedir": "/home/user",
"ifmodulemodsuphpc": {"group": "user"
},
"ip": "192.168.0.128",
"is_https_redirecting": "0",
"options": "ExecCGI Includes",
"owner": "root",
"port": "80",
"scriptalias": [{"path": "/home/user/public_html/cgi-bin",
"url": "/cgi-bin/"
},
{"path": "/home/user/public_html/cgi-bin/",
"url": "/cgi-bin/"
}
],
"serveradmin": "[email protected]",
"serveralias": "parkeddomain.com www.parkeddomain.com www.example.com",
"servername": "example.com",
"type": "main_domain",
"usecanonicalname": "Off",
"user": "user",
"userdirprotect": ""
},
"no_cache_update": "0",
"owner": "root",
"parked_capable_of_https_redirects": ["parkeddomain.com"
],
"parked_domains": ["parkeddomain.com"
],
"parked_with_https_redirects": ["parkeddomain.com"
],
"serveradmin": "[email protected]",
"serveralias": "addondomain.com www.addondomain.com www.subdomain.example.com",
"servername": "subdomain.example.com",
"sub_domains": [{"all_aliases_valid": "0",
"can_https_redirect": "0",
"documentroot": "/home/user/public_html/sub",
"domain": "sub.example.com",
"group": "user",
"hascgi": "1",
"homedir": "/home/user",
"ip": "192.168.0.128",
"ipv6": null,
"is_https_redirecting": "0",
"is_temporary": "0",
"no_cache_update": "0",
"owner": "root",
"serveradmin": "[email protected]",
"serveralias": "www.sub.example.com",
"servername": "sub.example.com",
"type": "sub_domain",
"usecanonicalname": "Off",
"user": "user",
"userdirprotect": ""
}
],
"type": "addon_domain",
"usecanonicalname": "Off",
"user": "user",
"userdirprotect": ""
}
]
},
"errors": null,
"messages": null,
"metadata": null,
"status": 1
}

Return domain's hosting configuration

This function lists user data for a domain.

Important:

This function retrieves data from the /var/cpanel/userdata/user/domain file, where user represents the cPanel account username and domain represents the domain.

Because aliases (parked domains) do not use a user data file, this function cannot query information for aliases. To retrieve information for an alias, specify the associated main or addon domain.
Due to differences in user data files, the function's actual output may not contain all of the returns that this document lists.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain on the cPanel account. Important: Do not specify an alias (parked domain).
hide_temporary_domains	integer Default: 0 Possible Values: 1 0 Example: hide_temporary_domains=1 Whether to hide temporary domains from the returned values. `1` — Return an error if the requested domain is a temporary domain. `0` — Return all domains, including the temporary domains. Note: If you set this parameter's value to `1` and the requested domain is temporary, the function will return an error similar to the following example: `Domain [example.com] is a temporary domain and` hide_temporary_domains `is enabled.`
return_https_redirect_status	integer Default: 0 Possible Values: 0 1 Example: return_https_redirect_status=1 Whether to return the secure redirect status of the addon domains. `1` - Return status. `0` - Do not return status.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DomainInfo \
  single_domain_data \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "single_domain_data",
"module": "DomainInfo",
"result": {"data": {"all_aliases_valid": 0,
"can_https_redirect": 0,
"customlog": {"domain": "combined",
"target": "/usr/local/apache/domlogs/example.com"
},
"documentroot": "/home/user/public_html/",
"domain": "example.com",
"group": "user",
"hascgi": 1,
"homedir": "/home/user",
"ifmodulemodsuphpc": {"group": "user"
},
"ip": "192.168.0.128",
"is_https_redirecting": 0,
"is_temporary": 0,
"options": "ExecCGI Includes",
"owner": "root",
"phpopenbasedirprotect": 1,
"port": 80,
"scriptalias": {"path": "/home/user/public_html/cgi-bin",
"url": "/cgi-bin/"
},
"serveradmin": "[email protected]",
"serveralias": "parkeddomain.com www.parkeddomain.com www.example.com",
"servername": "example.com",
"type": "main_domain",
"usecanonicalname": "Off",
"user": "user",
"userdirprotect": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account's domains

This function lists the cPanel account's domains.

Note:

For this function to succeed, the /var/cpanel/userdata/username/main file (where username represents the authenticated user) must possess the correct permissions. If a permissions error occurs, this function returns blank values for all of its returns and does not return an error message.

Authorizations:

BasicAuth

query Parameters

hide_temporary_domains

integer

Default: 0

Possible Values: 1 0

Example: hide_temporary_domains=1

Whether to hide temporary domains from the response arrays.

1 — Hide temporary domains from the addon_domains, sub_domains, and parked_domains arrays, and from the main_domain field.
0 — Return all domains, including the temporary domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DomainInfo \
  list_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_domains",
"module": "DomainInfo",
"result": {"data": {"addon_domains": ["addondomain.com"
],
"main_domain": "example.com",
"parked_domains": ["parkeddomain.com"
],
"sub_domains": ["subdomain.example.com"
],
"is_temporary": {"property1": 0,
"property2": 0
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Domain Redirection

Domain Management / Domain Redirection

Add redirect to domain

This function adds a redirect to a domain.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain from which to redirect.
redirect required	string <url> Example: redirect=http://example.com/ The URL to which to redirect.
redirect_wildcard	integer Default: 0 Possible Values: 0 1 Example: redirect_wildcard=1 Whether to redirect all files within a directory to the same filename within the destination directory. `1` - Redirect all files within the directory. `0` - Do not redirect all files within the directory.
redirect_www	integer Default: 0 Example: redirect_www=0 Whether to redirect domains with or without `www`. `2` - Redirect with `www`. `1` - Redirect without `www`. `0` - Redirect with and without `www`.
src	string <url-path> Default: "/" Example: src=/specific-page A specific page from which to redirect.
type	string Default: "permanent" Possible Values: "permanent" "temp" Example: type=permanent Whether the redirect is temporary. `permanent` `temp`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  add_redirect \
  domain='example.com' \
  redirect='http://example.com/'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_redirect",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": ["Htaccess Installed"
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Return redirect URL for domain

This function retrieves a redirection URL for a domain.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

The domain's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  get_redirect \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_redirect",
"module": "Mime",
"result": {"data": {"redirection_enabled": 1,
"url": "http://www.domain.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove redirect from domain

This function removes a redirect from a domain.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

args	string Default: "" Example: args=redirectme http://redirectme.com/ An argument string that contains the arguments of a `Redirect` or `RedirectMatch` directives.
docroot	string <path> Example: docroot=/home/example/public_html/ The absolute file path to the document root containing the `.htaccess` file to change. If you don't pass this parameter, the system looks up the document root from the `domain` parameter's value.
domain required	string <domain> Example: domain=example.com The domain name.
src	string Default: "" Example: src=redirectpage.html The specific page that redirects visitors.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  delete_redirect \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_redirect",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return .htaccess files' redirects

This function lists the redirects in an account's .htaccess files.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

destination	string Example: destination=http://example.tld The string with which to filter results. Note: This will only return results that match the `destination` parameter exactly.
regex	string Example: regex="^[a-z0-9_-]{6,18}$" A Perl regular expression that filters the results. The system matches the regular expression to the `sourceurl` return value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  list_redirects

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_redirects",
"module": "Mime",
"result": {"data": [{"destination": "http://redirect.example.com/",
"displaydomain": "ALL",
"displaysourceurl": "/marceau.html",
"docroot": "/home/example/public_html",
"domain": "example.com",
"kind": "rewrite",
"matchwww": 1,
"matchwww_text": "checked",
"opts": "L",
"source": "/marceau.html",
"sourceurl": "/marceau.html",
"statuscode": "301",
"targeturl": "http://redirect.example.com/",
"type": "permanent",
"urldomain": "example.com",
"wildcard": 1,
"wildcard_text": "checked"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

SubDomain

The SubDomain module for UAPI.

Create subdomain

This function creates a subdomain.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

canoff	integer Default: 1 Possible Values: 0 1 Example: canoff=1 Whether to use a canonical name (CNAME) in the Apache® configuration for self-referential URLs. `1` - Use the CNAME. `0` - Do not use the CNAME.
dir	string <path> Example: dir=/public_html/directory_name The subdomain's document `root` within the home directory, given as a valid directory path relative to the user's home directory. This value defaults to the user's home directory `/public_html/` path. Note: If the Restrict document roots to public_html value is set to Off in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings), this parameter defaults to the `/username/` path. For example, the `username` user's subdomain `example` would default to the `/home/username/example` path.
disallowdot	integer Default: 0 Possible Values: 0 1 Example: disallowdot=1 Whether to remove the dot (`.`) characters from the `domain` value. `1` - Remove dots from the domain. `0` - Do not remove dots from the domain.
domain required	string Example: domain=subdomain The subdomain name to create.
rootdomain required	string <domain> Example: rootdomain=example.com The domain on which to create the new subdomain. The domain must already exist on the cPanel account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SubDomain \
  addsubdomain \
  domain='subdomain' \
  rootdomain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "addsubdomain",
"module": "SubDomain",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Virtual Host Information

Domain Management / Virtual Host Information

Return virtual host names for domains

This function lists virtual host names for each domain.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebVhosts \
  list_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_domains",
"module": "WebVhosts",
"result": {"data": [{"domain": "example.com",
"proxy_subdomains": ["cpanel",
"webmail",
"autodiscover",
"whm",
"webdisk"
],
"vhost_is_ssl": 1,
"vhost_name": "hostname.example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domains that allow SSL certificate purchase

This function lists every domain for which you may purchase an SSL certificate. The possible domains for the Secure Sockets Layer (SSL) certificate include applicable service subdomains.

Authorizations:

BasicAuth

query Parameters

hide_temporary_domains

integer

Default: 0

Possible Values: 1 0

Example: hide_temporary_domains=1

Whether to hide temporary domains from the returned values.

1 — Return an error if the requested domain is a temporary domain.
0 — Return all domains, including the temporary domains. Note:

If you set this parameter's value to 1 and the requested domain is temporary, the function will return an error similar to the following example: Domain [example.com] is a temporary domain and hide_temporary_domains is enabled.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebVhosts \
  list_ssl_capable_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_ssl_capable_domains",
"module": "WebVhosts",
"result": {"data": [{"domain": "example.com",
"is_proxy": 1,
"vhost_name": "hostname.example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Email Accounts

Email / Email Accounts

Return current user's account name

This function returns the provided value. This function works with other functions to display form data within a user interface.

Note:

If you call this function from a Webmail session URL, the system will only access data for that email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account	string Example: account=user The function will return this value in the data return. If you do not include this parameter, the function returns `All Mail On The Account` or a blank value. A valid string. An empty value. Note: The function does not validate this parameter's value.
display	string Example: display=any_value Include this parameter to cause the function to return `All Mail On The Account` if the account parameter is blank or does not exist. If you do not include this parameter and the account value is blank or does not exist, the function returns a blank data value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  account_name

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "account_name",
"module": "Email",
"result": {"data": "[email protected]",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create email address

This function creates an email address.

Important:

When you disable the Receive Mail role, the system disables this function.
We recommend that you use the UAPI UserManager::create_user function to create an email address instead of this function. This function is incompatible with the Reset Password feature.
You must URI-encode values when using the CLI.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Default: "The cPanel account's main domain." Example: domain=example.com The email account's domain. For example, `example.com` to create `[email protected]`.
required	string or string Example: email=user The email account username or address. A valid email account username. For example, `user` to create `[email protected]`. A valid email address. Note: You cannot enter `cpanel` as an account name when you create an email account.
password required	string Example: password=123456luggage The email account password.
password_hash	string Example: password_hash=$6$1sOyHP5ZDYp3pGUz$R0TSgfPRHfDjT5PP5RJGv39FhiGTNNPvM7IFpCBjXijMmlMZk9yI8T3LqGuntc9fdKb5eX.lGL7wBS9e4DAWn/ The account's password hash. Notes: You can use this parameter instead of the `password` parameter. However, you cannot use both `password` and `password_hash` parameters in the same request. You can find your server's hash type in the `/etc/sysconfig/authconfig` file.
	string or integer Default: "The defined system value." Example: quota=500 The maximum amount of disk space that the new email account may use. A positive integer that represents the maximum amount of disk space, in megabytes (MB). `0` or `unlimited` — The account possesses unlimited disk space. Note: The positive integer value cannot exceed the maximum email quota. The `0` or `unlimited` value is only available to users without a maximum email account quota.
send_welcome_email	integer Default: 0 Possible Values: 0 1 Example: send_welcome_email=0 Whether to send client configuration instructions to the account. `1` — Send the instructions. `0` — Do not send the instructions.
skip_update_db	integer Default: 0 Possible Values: 0 1 Example: skip_update_db=1 Whether to skip the update of the email accounts database's cache. `1` — Skip the update. `0` — Perform the update.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_pop \
  email='user' \
  password='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_pop",
"module": "Email",
"result": {"data": "user+example.com",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return mail directory's subdirectories and files

This function lists the mail directory's subdirectories (boxes) and files.

Important:

When you disable the Receive Mail role, the system disables this function.

Notes:

If you do not use any input parameters, the function returns a list of items in the cPanel account's main mail directory.

Authorizations:

BasicAuth

query Parameters

account	string <email> Example: [email protected] An email address, to limit the function's results.
dir	string Example: dir=maildir A mail directory name, to limit results to specific directories. Note: If you pass the `default` or `mail` values, the function lists information for all mail directories.
showdotfiles	integer Default: 0 Possible Values: 0 1 Example: showdotfiles=0 Whether to include hidden files and directories. `1` — Include hidden items. `0` — Do not include hidden items.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  browse_mailbox

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "browse_mailbox",
"module": "Email",
"result": {"data": [{"depth": 2,
"file": "archive",
"fullpath": "/home/example/mail/archive",
"isleaf": 0,
"ismailbox": 0,
"mtime": 1413398866,
"path": "/home/example/mail",
"relpath": "/archive",
"type": "dir"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's autoresponders total

This function returns the number of autoresponders for every email address on a cPanel account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  count_auto_responders

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "count_auto_responders",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's email account total

This function returns the number of email accounts for a cPanel account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  count_pops

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "count_pops",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete email account's outgoing messages

This function deletes all outbound email messages held in the mail queue for the specified email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email address to query.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_held_messages \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_held_messages",
"module": "Email",
"result": {"data": 0,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update email account's quota

This function changes an email address's quota.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The email account's domain. Defaults to the cPanel account's main domain.
email required	string Example: email=user The email account username.
quota	string Example: quota=500 The maximum amount of disk space that the new email account may use. Defaults to the system value. A positive integer that represents the maximum amount of disk space, in megabytes (MB). Note: You cannot enter a value that exceeds the maximum email quota. `0` or `unlimited` — The account possesses unlimited disk space. If the email account's quota value is set higher (or unlimited) than the account's max quota, the account's max quota will be applied instead of the value entered. Note: This value is only available to users without a maximum email account quota.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  edit_pop_quota \
  email='user' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "edit_pop_quota",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Send email client settings to an email address

This function sends an email account's client settings to an email address.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: account=username The email account username or address for which to send client settings.
to required	string <email> Example: [email protected] The email address to send client settings.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  dispatch_client_settings \
  to='[email protected]' \
  account='username'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "dispatch_client_settings",
"module": "Email",
"result": {"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Stop email account's outgoing mail

This function sets Exim's queue to not send outgoing mail from an email account.

Notes:

To send all mail from the queue, use the UAPI Email::release_outgoing function.
To reject outgoing mail and not place mail in a queue, use the UAPI Email::suspend_outgoing function.
This function does not hold local outgoing mail.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  hold_outgoing \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "hold_outgoing",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's autoresponder information

This function retrieves autoresponder information.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string <username> Example: email=user The email account name.
temp_charset	string Default: "utf-8" Example: temp_charset=utf-8 The autoresponder's character set.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_auto_responder \
  email='user'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_auto_responder",
"module": "Email",
"result": {"data": {"body": "This is an autoresponder message.",
"charset": "UTF-8",
"from": "User Name",
"interval": 24,
"is_html": 1,
"start": 1410277881,
"stop": 1410300000,
"subject": "Autoresponder Subject"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's default email quota

This function retrieves the account's default email quota size, in bytes format.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_default_email_quota

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_default_email_quota",
"module": "Email",
"result": {"data": 34359738368,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's client settings

This function retrieves an email account's client settings.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account

string <email>

Example: [email protected]

The email address for which to send client settings.

Note:

This parameter defaults to the system default email account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_client_settings

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_client_settings",
"module": "Email",
"result": {"data": {"account": "[email protected]",
"activesync_available": 1,
"activesync_host": "mail.example.com",
"activesync_port": 2091,
"activesync_username": "[email protected]",
"display": "[email protected]",
"domain": "domain.com",
"from_archiving": 0,
"has_plaintext_authentication": 1,
"inbox_host": "mail.example.com",
"inbox_insecure_port": 143,
"inbox_port": 993,
"inbox_service": "imap",
"inbox_username": "[email protected]",
"mail_domain": "mail.example.com",
"smtp_host": "mail.example.com",
"smtp_insecure_port": 25,
"smtp_port": 465,
"smtp_username": "[email protected]"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's disk usage

This function retrieves the disk space that an email account uses.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The email account's domain.
user required	string <username> Example: user=user The email account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_disk_usage \
  user='user' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_disk_usage",
"module": "Email",
"result": {"data": {"diskused": 399.6,
"domain": "example.com",
"login": "[email protected]",
"user": "user"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's default email quota in MiB

This function retrieves the account's default email quota size in mebibytes (MiB).

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_default_email_quota_mib

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_default_email_quota_mib",
"module": "Email",
"result": {"data": 32768,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's outgoing message count

This function returns the count of outbound email messages held in the mail queue for the specified email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

string <email>

Example: [email protected]

The email address to query.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_held_message_count

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_held_message_count",
"module": "Email",
"result": {"data": 0,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return primary email account's disk usage

This function returns the disk space that the main account uses.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_main_account_disk_usage

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_main_account_disk_usage",
"module": "Email",
"result": {"data": "3076 bytes",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return primary email account's disk usage in bytes

This function returns the disk space that the cPanel account uses.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_main_account_disk_usage_bytes

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_main_account_disk_usage_bytes",
"module": "Email",
"result": {"data": 3076,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's quota

This function retrieves an email account's quota.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

as_bytes	integer Default: 0 Possible Values: 0 1 Example: as_bytes=1 Whether to return the quota as bytes. `1` — Return the quota as bytes. `0` — Return the quota as megabytes (MB).
domain	string <domain> Example: domain=example.com The email account's domain. This parameter defaults to the cPanel account's main domain.
email required	string Example: email=user The email account username. For example, user if the email address is user@example.com.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_pop_quota \
  email='user'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_pop_quota",
"module": "Email",
"result": {"data": 262144000,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's max quota size

This function retrieves the account's maximum email quota size, in bytes format.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_max_email_quota

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_max_email_quota",
"module": "Email",
"result": {"data": 4503599627370496,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's max quota size in MiB

This function retrieves the account's maximum email account quota size, in Mebibytes (MiB) format.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_max_email_quota_mib

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_max_email_quota_mib",
"module": "Email",
"result": {"data": 4294967296,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's Webmail settings

This function retrieves an email account's Webmail settings.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

string or string

The email account.

Note:

If you do not specify a value, the function retrieves settings for the cPanel account's default mail account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_webmail_settings

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_webmail_settings",
"module": "Email",
"result": {"data": {"domain": "mail.example.com",
"has_maildir": 1,
"user": "[email protected]"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domain's default email address

This function retrieves a domain's default address.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The domain. If you do not specify a value, the function lists default addresses for all of the cPanel account's domains.
user required	string <username> Example: user=user The user whose default addresses to list.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_default_address \
  user='user'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_default_address",
"module": "Email",
"result": {"data": [{"defaultaddress": "user",
"domain": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domain's autoresponders

This function lists a domain's autoresponders.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain name.
regex	string Example: regex=user A Perl Compatible Regular Expression (PCRE) that filters the results.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_auto_responders \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_auto_responders",
"module": "Email",
"result": {"data": [{"email": "[email protected]",
"subject": "Autoresponder Subject"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's mail domains

This function lists the account's mail domains.

Important:

When you disable the Receive Mail role, the system disables this function.

Note:

This function always returns the account's main domain first.

Additional Note:

By default, temporary domains (*.cpanel.site) are excluded. Use the return_temporary_domain parameter to include them.

Authorizations:

BasicAuth

query Parameters

add_www	integer Default: 0 Possible Values: 0 1 Example: add_www=1 Whether to list `www.` addresses. `1` — List `www.` addresses. `0` — Do not list `www.` addresses. For example, if you specify `1`, the function's output would include both `example.com` and `www.example.com`. If you specify `0`, the output would include only `example.com`.
include_wildcard	integer Default: 0 Possible Values: 0 1 Example: include_wildcard=1 Whether to list wildcard addresses. `1` — List wildcard addresses. `0` — Do not list wildcard addresses. For example, if you specify `1`, the function's output would include both `example.com` and `.example.com`. If you specify `0`, the output would include only* `example.com`.
return_temporary_domain	boolean Default: false Whether to include temporary domains (*.cpanel.site) in the output. By default, temporary domains are excluded.
select	string <domain> Example: select=example.com The name of the domain that the function returns with the `select` output parameter. If you do not use this parameter, the function will not return the `select` parameter with any domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_mail_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_mail_domains",
"module": "Email",
"result": {"data": [{"domain": "example.com",
"select": 1
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return email accounts

This function lists the cPanel account's email accounts.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

no_validate	integer Default: 0 Possible Values: 0 1 Example: no_validate=1 Whether to skip the email database's validation check. `1` — Skip the validation check. `0` — Run the validation check.
regex	string Example: regex=user A Perl Compatible Regular Expression (PCRE) that filters the results.
skip_main	integer Default: 0 Possible Values: 0 1 Example: skip_main=0 Whether to exclude the cPanel account's main account from the results. `1` — Exclude the main account. `0` — Include the main account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_pops

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_pops",
"module": "Email",
"result": {"data": [{"email": "[email protected]",
"login": "[email protected]",
"suspended_incoming": 0,
"suspended_login": 0
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return email accounts with disk information

This function lists the cPanel account's email accounts with disk information.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com A domain name to filter the results by. If you do not use this parameter, the function returns all of the cPanel account's email addresses.
email	string <username> Example: email=user The cPanel user account to query. If you do not use this parameter, the function returns the email addresses for all cPanel accounts that the user owns. Note: To retrieve information for a single email address, add the domain parameter. For example, `email=user&domain=example.com` will return information for the email address `[email protected]`.
get_restrictions	integer Default: 0 Possible Values: 0 1 Example: get_restrictions=0 Whether to display restriction status for each of the email addresses. `1` — Display. `0` — Do not display.
infinityimg	string Example: infinityimg=images/myimg.jpg An image to display for email addresses with an unlimited quota. If you specify an `infinityimg` value, the function returns HTML code to display that image as the `diskquota` parameter's value.
infinitylang	integer Default: 0 Possible Values: 0 1 Example: infinitylang=0 Whether to return the `∞` character for email addresses with an unlimited quota. `1` — Return the `∞` character for unlimited `diskquota` values. `0` — Return the string `unlimited` for unlimited `diskquota` values. Note: If you specify `1` for this parameter and the `infinityimg` parameter, the function ignores this parameter and returns HTML code for unlimited `diskquota` values.
maxaccounts	integer >= 1 Default: "unlimited" Example: maxaccounts=500 The maximum number of email addresses to return. If you do not use this parameter, the function returns an unlimited number of email addresses.
no_disk	integer Default: 0 Possible Values: 0 1 Example: no_disk=0 Whether to skip the collection of disk usage information. `1` — Do not collect. `0` — Collect.
no_validate	integer Default: 0 Possible Values: 0 1 Example: no_validate=0 Whether to skip email database validation. `1` — Skip validation. `0` — Perform the validation.
regex	string Default: "An empty string" Example: regex=/^[a-z0-9_-]{6,18}$/ A Perl Compatible Regular Expression (PCRE) that filters the results. For example, `/^[a-z0-9_-]{6,18}$/` matches the local portion of an email address, if it contains between six and 18 characters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_pops_with_disk

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_pops_with_disk",
"module": "Email",
"result": {"data": [{"_diskquota": 0,
"_diskused": 483,
"diskquota": "unlimited",
"diskused": 0,
"diskusedpercent": 0,
"diskusedpercent20": 0,
"diskusedpercent_float": 0,
"domain": "example.com",
"email": "[email protected]",
"has_suspended": 0,
"hold_outgoing": 0,
"humandiskquota": "None",
"humandiskused": "483 bytes",
"login": "[email protected]",
"mtime": 1415894498,
"suspended_incoming": 0,
"suspended_login": 0,
"suspended_outgoing": 0,
"txtdiskquota": "unlimited",
"user": "user"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update email account password

This function changes an email account's password.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Default: "the cPanel account's main domain" Example: domain=example.com The email account's domain.
required	string or string Example: [email protected] The email account username or address.
password required	string Example: password=12345luggage The email account password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  passwd_pop \
  email='[email protected]' \
  password='12345luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "passwd_pop",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start email account outgoing mail

This function sends all of the outgoing mail from Exim's queue for an email account.

Note:

To set Exim to queue all outgoing mail for an email account, use the UAPI Email::hold_outgoing function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  release_outgoing \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "release_outgoing",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create default email address

This function configures a default (catchall) email address.

Important:

When you disable the Mail Receive role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The domain whose default email behavior you want to configure. Note: This parameter defaults to the cPanel account’s main domain.
failmsgs	string Default: "No such person at this address" Example: failmsgs=Failure echos loud. That address does not exist. Softly I regret. - an email failure haiku The failure message for the message’s sender. Note: Use this parameter if you used the `fail` method for the `fwdopt` parameter.
fwdemail	string <email> Example: [email protected] The email address to which the system forwards messages. Note: Use this parameter if you used the `fwd` method for the `fwdopt` parameter.
fwdopt required	string Possible Values: "fwd" "fail" "blackhole" "pipe" Example: fwdopt=fwd The method to use to handle unroutable mail. `fwd` — Forward messages to the `fwdemail` parameter’s address. `fail` — Bounce messages back to the sender, and include the `failmsgs` parameter’s failure message. `blackhole` — Send messages to the `/dev/null/` directory. This method does not generate a failure notice. `pipe` — Pipe mail to the `pipefwd` parameter’s application. This parameter requires the File Storage role.
pipefwd	string Example: pipefwd=mailscript.pl The application to which the system pipes messages. Note: Use this parameter if you used the `pipe` method for the `fwdopt` parameter. Important: This parameter requires the File Storage role.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  set_default_address \
  fwdopt='fwd'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_default_address",
"module": "Email",
"result": {"data": [{"dest": "[email protected]",
"domain": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Run email delivery route trace

This function traces the email delivery route to an email account.

Authorizations:

BasicAuth

query Parameters

recipient

required

string

Example: [email protected]

The email address to which to trace a message delivery path.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  trace_delivery \
  recipient='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "trace_delivery",
"module": "Email",
"result": {"data": {"address": "[email protected]",
"destinations": [{"address": "[email protected]",
"aliasfile": "/etc/valiases/example.com",
"destinations": [{"mailbox": "[email protected]",
"type": "local_delivery"
}
],
"type": "routed"
}
],
"type": "routed"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate email account password

This function verifies the password for an email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string <email> Example: [email protected] The email account address.
password required	string Example: password=123456luggage The email account password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  verify_password \
  email='[email protected]' \
  password='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "verify_password",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete email account's autoresponder

This function deletes an autoresponder.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_auto_responder \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_auto_responder",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete email address

This function deletes an email address.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Default: "The cPanel account's main domain." Example: domain=example.com The email account's domain. For example, `example.com` if the email address is `[email protected]`.
required	string or string Example: [email protected] The email account username or address. A valid email account username. For example, `user` if the email address is `[email protected]`. A valid email address.
flags	string Example: flags=passwd Whether to remove the mail account's home mail directory. If you do not specify a value, the function removes the mail account's home directory. `passwd` — Preserve the mail account's home directory. Any other value — Remove the mail account's home directory.
skip_quota	integer Default: 0 Possible Values: 0 1 Example: skip_quota=0 Whether to modify the mail account's quota file. `1` — Do not modify. `0` — Modify.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_pop \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_pop",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create email account's autoresponder

This function creates an autoresponder for an email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

body required	string Example: body=This is an autoresponder message. The contents of the autoresponder message's `Body` section.
charset	string Default: "utf-8" Example: charset=UTF-8 The character set.
domain required	string <domain> Example: domain=example.com The email account's domain. For example, `example.com` if the email address is `[email protected]`.
email required	string Example: email=user The email account name. For example, `user` if the email address is `[email protected]`.
from required	string Example: from=User Name The contents of the autoresponder message's `From:` field.
interval required	integer >= 0 Example: interval=24 The amount of time, in hours, that the server waits between autoresponder messages to the same address. Note: If you specify `0`, the system sends a message for each received email.
is_html required	integer Possible Values: 0 1 Example: is_html=1 Whether the body of the autoresponder message begins with an HTML Content-Type declaration. `1` — Include an HTML content type declaration. `0` — Do not include an HTML content type declaration.
start required	integer <unix_timestamp> Example: start=1410277881 When to enable the autoresponder.
stop required	integer <unix_timestamp> Example: stop=1410300000 When to disable the autoresponder. A time that is after the `start` time.
subject required	string Example: subject=Autoresponder Subject The contents of the autoresponder message's `Subject:` field.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_auto_responder \
  email='user' \
  from='User Name' \
  subject='Autoresponder Subject' \
  body='This is an autoresponder message.' \
  domain='example.com' \
  is_html='1' \
  interval='24' \
  start='1410277881' \
  stop='1410300000'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_auto_responder",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Import email accounts from CSV file

This function imports email accounts from an already uploaded CSV file.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain under which to add the email accounts.
id required	string Example: id=Leq58oid3sF3Moye3_YbJGqoMvCb7M4j The unique ID of the import operation. The cPanel API 2 CSVImport::uploadimport function generates this ID and stores it in the `CPVAR` attribute named `csvimportid`.
type required	string Possible Values: "email" "fwd" Example: type=email The type of email address to add. `email` — A regular email account. `fwd` — A forwarder.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CSVImport \
  doimport \
  id='Leq58oid3sF3Moye3_YbJGqoMvCb7M4j' \
  type='email' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "doimport",
"module": "CSVImport",
"result": {"data": {"results": [{"email": "[email protected]",
"reason": "OK",
"status": 1,
"type": "email"
},
{"email": "[email protected]",
"reason": "The account [email protected] already exists!",
"status": 0,
"type": "email"
}
]
},
"errors": ["1 error(s) were encountered while importing accounts."
],
"messages": null,
"metadata": { },
"status": 0,
"warnings": null
}
}

Add manual MX redirection

This function lets you create a manual Exim mail exchanger (MX) redirect for a domain. An MX redirection lets you bypass the domain's MX lookup via the Domain Name System (DNS). This function adds the manual redirect entries to the /etc/manualmx file.

Note:

To remove a domain's manual MX redirection, use the UAPI Email unset_manual_mx_redirect function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain='example.com' - Add a single manual MX redirect entry.
domain=example.com&domain-1=example1.com&domain-2=example2.com - Add multiple manual MX redirect entries.

The domain for which to add a manual MX redirect entry.

Note:

To add multiple domain entries, increment the parameter. For example, use the domain, domain-1, and domain-2 parameters.
For multiple domains, you must include its corresponding mx_host value.

required

string or string or string

Examples:

mx_host='mailhostexample' - Add a single manual MX host.
mx_host=mailhostexample&mx_host-1=mailhostexample&mx_host-2=mailhostexample - Add multiple manual MX hosts.

The domain, IPv4, or IPv6 address to redirect the domain value's emails to.

Note:

To add multiple MX hosts, increment the parameter. For example, use the mx_host, mx_host-1, and mx_host-2 parameters.
For multiple MX hosts, you must include its corresponding domain value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username Email set_manual_mx_redirects domain='example.com' mx_host='mailhostexample.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_manual_mx_redirects",
"module": "Email",
"result": {"data": {"example.com": "mailhostexample.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove manual MX redirection

This function lets you create a manual Exim mail exchanger (MX) redirect for a domain. An MX redirection lets you bypass the domain's MX lookup via the Domain Name System (DNS). This function adds the manual redirect entries to the /etc/manualmx file.

Note:

To remove a domain's manual MX redirection, use the UAPI Email unset_manual_mx_redirect function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain='example.com' - Add a single manual MX redirect entry.
domain=example.com&domain-1=example1.com&domain-2=example2.com - Add multiple manual MX redirect entries.

The domain for which to add a manual MX redirect entry.

Note:

To add multiple domain entries, increment the parameter. For example, use the domain, domain-1, and domain-2 parameters.
For multiple domains, you must include its corresponding mx_host value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username Email unset_manual_mx_redirects domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unset_manual_mx_redirects",
"module": "Email",
"result": {"data": {"example.com": "mailhostexample.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Stop cPanel account IMAP and POP3 connections

This function terminates all IMAP and POP3 connections for a cPanel account.

Note:

This function ends connections for every email address, which includes the default address.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  terminate_mailbox_sessions

Response samples

200

Content type

application/json

{"metadata": {"command": "terminate_mailbox_sessions",
"reason": "OK",
"result": 1,
"version": 1
}
}

Email Filtering

Email / Email Filtering

Return cPanel account's email filters total

This function returns the number of email filters for every email address on a cPanel account.

Important:

When you disable the Receive Mail role or the IP Blocker feature, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  count_filters

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "count_filters",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Disable email filter for email account

This function disables an email filter.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account required	string <email> Example: [email protected] The email address that owns the filter.
filtername required	string Example: filtername=coffee The filter's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  disable_filter \
  account='[email protected]' \
  filtername='coffee'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_filter",
"module": "Email",
"result": {"data": {"filtername": "coffee",
"updated": 1
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable email filter for email account

This function enables an email filter.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account required	string <email> Example: [email protected] The email address that owns the filter.
filtername required	string Example: filtername=coffee The filter's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  enable_filter \
  account='[email protected]' \
  filtername='coffee'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_filter",
"module": "Email",
"result": {"data": {"filtername": "coffee",
"updated": 1
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return email filter's information

This function retrieves an email filter's information.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account required	string <email> Example: [email protected] The email address that owns the filter.
filtername required	string Example: filtername=coffee The filter's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_filter \
  account='[email protected]' \
  filtername='coffee'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_filter",
"module": "Email",
"result": {"data": {"actions": [{"action": "deliver",
"dest": "/dev/null",
"number": 1
}
],
"filtername": "coffee",
"metadata": {"transformed": 1
},
"rules": [{"match": "contains",
"number": 1,
"opt": "or",
"part": "$message_body",
"val": "coconut"
}
]
},
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return account-level email filters

This function lists account-level mail filters. For more information about Exim filters, read Exim’s documentation.

Important:

When you disable the Mail Receive role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

string or string

The email address or cPanel account username for which to return a list of filters. If you do not specify this value, the function lists all of the cPanel account’s account-level filters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_filters

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_filters",
"module": "Email",
"result": {"data": [{"actions": [{"action": "string",
"dest": "/dev/null"
}
],
"enabled": 0,
"filtername": "coffee",
"rules": [{"match": "contains",
"opt": "or",
"part": "$message_body",
"val": "coconut"
}
],
"unescaped": true
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domains with domain-level email filters

This function lists all of the cPanel account's domains that use domain-level filters.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_filters_backups

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_filters_backups",
"module": "Email",
"result": {"data": [{"domain": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return system-level email filter file information

This function retrieves a .yaml.gz file that contains system-level filter information.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_system_filter_info

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_system_filter_info",
"module": "Email",
"result": {"data": {"filter_info": "filter_info.username.yaml.gz"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update email address's email filter order

This function modifies the filter order for an email address. For more information about Exim filters, read Exim's documentation.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

filter* required	string Example: filter=coffee A mail filter name. For each mail filter to reorder, supply a `filter` parameter, where `*` is a number that represents the filter's order. For example, to set `coffee` as the first email filter and `cheesecloth` as the second, set `coffee` as the `filter1` parameter's value, and `cheesecloth` as the value for the `filter2` parameter.
mailbox required	string Example: [email protected] The email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  reorder_filters \
  mailbox='[email protected]' \
  filter*='coffee'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "reorder_filters",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create email filter

This function creates a new email filter. For more information about Exim filters, read Exim's documentation.

Important:

When you disable the Receive Mail role, the system disables this function.

Create multiple rules

You may create up to 4,096 separate sets of conditions in one filter. To do this, append numbers to the parameter names.

To create a filter with two sets of actions and conditions, use the following parameters:

Assign the information for the first filter rule to the action1, dest1, match1, opt1, part1, and val1 parameters.
Assign the information for the second filter rule to the action2, dest2, match2, opt2, part2, and val2 parameters.

To create a filter that uses one set of actions but two sets of conditions, use the following parameters:

Assign the actions to the action1 and dest1 parameters.
Assign the first set of conditions to the match1, opt1, part1, and val1 parameters.
Assign the second set of conditions to the match2, opt2, part2, and val2 parameters.

Authorizations:

BasicAuth

query Parameters

account	string <email> Example: [email protected] The email address, for user-level filters. If you do not use this parameter, the function creates an account-level filter.
required	string Examples: action=action1=deliver action2=save - Use multiple filter actions. action=deliver - Use a single filter action. The filter's action. `deliver` - Deliver the message to the `dest` address. `fail` - Force a delivery failure. `finish` - Stop processing the message. `save` - Save the message to the `dest` file. `pipe` - Pipe the message to the `dest` application. Important:* You must increment each action. For example, pass the first action as `action1` and the second action as `action2`. This value requires the `FileStorage` role. For more information, read our How to Use Server Profiles documentation.
	string or string Default: "" Examples: dest[email protected] [email protected] - Use multiple destinations for filtered mail. dest[email protected] - Use a single destination for filtered mail. The destination for filtered mail. Important: This parameter is required if the action value is `deliver`, `save`, or `pipe`. You must increment each destination. For example, pass the first destination as `dest1` and the second destination as `dest2`.
filtername required	string Example: filtername=coffee The filter name.
required	string Examples: match=match1=contains match2=matches - Use multiple match types. match=contains - Use a single match type. The filter's match type. If the `val` parameter is a string, use a string operator. If the `val` parameter is an integer, use a numeric operator. String operators: `is` `matches` `contains` `does not contain` `begins` `does not begin` `ends` `does not end` `does not match` Numeric operators: `is above` `is not above` `is below` `is not below` Important: You must increment each match type. For example, pass the first match type as `match1` and the second match type as `match2`.
oldfiltername	string Example: oldfiltername=pool The name of an existing filter, to rename it. If you do not use this parameter, the function creates a new filter.
	string Default: "and" Examples: opt=opt1=and opt2=and - Use multiple connections between conditions. opt=and - Use a single connection between conditions. The connection between multiple conditions. Important: You must increment each connection. For example, pass the first connection as `opt1` and the second connection as `opt2`.
required	string Examples: part=part1=$header_from part2=$message_body - Query multiple email sections. part=$header_from - Query a single email section. The email section to query. `$h_x-Spam-Bar:` - Match against the message's spam score value, measured in plus(`+`) characters. `$h_x-Spam-Score:` - Match against the message's spam score value. `$h_X-Spam-Status:` - Match against whether the system detected the message as spam. `$h_List-Id:` - Match against the message's `List-ID` header value. `$header_from:` - Match against the `From:` section. `$header_subject:` - Match against the `Subject:` section. `$header_to:` - Match against the `To:` section. `$reply_address:` - Match against the `Reply To:` section. `$message_body:` - Match against the message's body. `$message_headers:` - Match against the message's headers. `foranyaddress $h_to:, $h_cc:` - Match against all message recipients. `not delivered` - Match if the message is not queued for delivery. `error_message` - Match if the incoming message is bounced. Important: You must increment each section. For example, pass the first section as `part1` and the second section as `part2`. Note: Generally, the recipient does not receive the `BCC` field in an email's header. For this reason you cannot use the `BCC` field in a filter.
required	string or integer Examples: val=val1=coconut val2=12 - Match multiple values. val=coconut - Match a single value. The value to match. Important: You must increment each value. For example, pass the first value as `val1` and the second value as `val2`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  store_filter \
  filtername='coffee' \
  action*='deliver' \
  match*='contains' \
  part*='$header_from' \
  val*='coconut'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "store_filter",
"module": "Email",
"result": {"data": {"account": "[email protected]"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Run test for main domain email filters

This function tests mail filters. The function only tests filters for the cPanel account's main domain, and only tests against the message's body. For more information about Exim filters, read Exim's documentation.

Note:

If the domain or account does not contain a filter file, this function will fail.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account	string <email> Example: [email protected] The email address, to test legacy cPanel filters in the filters directory. If you do not use this parameter, the function tests the main domain's filters in the `/etc/vfilters` directory.
msg required	string Example: msg=Test The string to test. The function uses this string as the body of an email message, to check whether filters would match the string.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  trace_filter \
  msg='Test'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "trace_filter",
"module": "Email",
"result": {"data": {"trace": "Warning: no message headers read\\nReturn-path copied from sender\\nSender = [email protected]\\nRecipient = [email protected]\\nTesting Exim filter file &quot;/etc/vfilters/example.com&quot;\\n\\nFiltering did not set up a significant delivery.\\n<b>Normal delivery will occur.\\n</b>"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete email account's email filter

This function deletes an email filter.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account required	string <email> Example: [email protected] The email address that owns the filter.
filtername required	string Example: filtername=coffee The filter's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_filter \
  account='[email protected]' \
  filtername='coffee'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_filter",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Email Forwarding

Email / Email Forwarding

Create email account forwarder

This function creates an email forwarder.

Important:

When you disable the MailReceive role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:

BasicAuth

query Parameters

domain required	string Example: domain=example.com The domain.
email required	string Example: [email protected] The email address to forward.
failmsgs	string Default: "No such person at this address" Example: failmsgs=Nobody home. The failure message for the message's sender. Note: Use this parameter if you used the fail method for the fwdopt parameter.
fwdemail	string Example: [email protected] The email address to which the system forwards messages. Note: You must use this parameter if you used the fwd method for the fwdopt parameter. You can pass multiple addresses to this parameter as a comma-separated list.
fwdopt required	string Example: fwdopt=fwd The method to use to handle the email address's mail.
fwdsystem	string Example: fwdsystem=user The system user to whom the system forwards messages. Note: You must use this parameter if you used the system method for the fwdopt parameter.
pipefwd	string Example: pipefwd=mailscript.pl The application to which the system pipes messages. Note: You must use this parameter if you used the pipe method for the fwdopt parameter. Important: This parameter requires the FileStorage role. For more information, read our How to Use Server Profiles documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_forwarder \
  domain='example.com' \
  email='[email protected]' \
  fwdopt='fwd'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_forwarder",
"module": "Email",
"result": {"data": [{"domain": "example.com",
"email": "[email protected]",
"forward": "[email protected]"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create domain-level forwarder

This function creates a domain-level forwarder.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

destdomain required	string <domain> Example: destdomain=forwardtome.com The domain to receive forwarded mail.
domain required	string <domain> Example: domain=example.com The domain on the cPanel account from which to forward mail.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_domain_forwarder \
  domain='example.com' \
  destdomain='forwardtome.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_domain_forwarder",
"module": "Email",
"result": {"data": "File updated \"/etc/vdomainaliases/example.com\"",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account's mail forwarder total

This function returns the number of forwarders for every email address on a cPanel account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  count_forwarders

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "count_forwarders",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete domain-level forwarder

This function deletes a domain-level forwarder.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

The domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_domain_forwarder \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_domain_forwarder",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete email account's email forwarder

This function deletes an email forwarder.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

address required	string <email> Example: [email protected] The forwarder's email address.
forwarder required	string Example: [email protected] The forwarder's destination. A valid email address. A script location. A system account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_forwarder \
  address='[email protected]' \
  forwarder='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_forwarder",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domain-level forwarders

This function lists domain-level forwarders.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

string <domain>

Example: domain=example.com

The domain name to query. If you do not use this parameter, the function returns all domain-level forwarders on the cPanel account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_domain_forwarders

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_domain_forwarders",
"module": "Email",
"result": {"data": [{"dest": "example.com",
"forward": "forwardtome.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domain's forwarders

This function lists a domain's forwarders.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain.
regex	string Example: regex=user A Perl Compatible Regular Expression (PCRE) that filters the results. If you do not use this parameter, the function returns results for all of the account's filters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_forwarders \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_forwarders",
"module": "Email",
"result": {"data": [{"dest": "[email protected]",
"forward": "[email protected]",
"html_dest": "[email protected]",
"html_forward": "[email protected]",
"uri_dest": "forwarded%40example.com",
"uri_forward": "user%40example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domains with domain-level forwarders

This function lists the domains with domain-level forwarders.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_forwarders_backups

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_forwarders_backups",
"module": "Email",
"result": {"data": [{"domain": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Email Server Information

Email / Email Server Information.

Return BlackBerry FastMail support status

This function checks whether BlackBerry® FastMail support is enabled.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  check_fastmail

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_fastmail",
"module": "Email",
"result": {"data": "2",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable cPanel account mailbox autocreation

This function disables the system's ability to automatically create mailboxes for a cPanel account.

Note:

When you enable the UAPI's Email::enable_mailbox_autocreate function, the system automatically creates mailboxes. The system creates a new mailbox when it receives an email address in plus address format and that mailbox does not exist. For example, receiving an email from the [email protected] address creates the newmailbox mailbox if the newmailbox mailbox does not exist.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email account address for which to disable mailbox autocreation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  disable_mailbox_autocreate \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_mailbox_autocreate",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable cPanel account mailbox autocreation

This function allows the system to automatically create mailboxes for a cPanel account. The system will create a new mailbox when it receives an email address in plus address format and that mailbox does not exist. For example, receiving an email from the user+newmailbox@example.com address creates the newmailbox mailbox if the newmailbox mailbox does not exist.

Note:

To disable this functionality, use the UAPI Email::disable_mailbox_autocreate function.

Authorizations:

BasicAuth

query Parameters

email

required

string

Example: [email protected]

The email account for which to enable mailbox autocreation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  enable_mailbox_autocreate \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_mailbox_autocreate",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start IMAP Full-Text Search scan for email account

This function requests that the IMAP Full-Text Search Indexing (powered by Apache Solr™) plugin rescan an email account.

Note:

To enable this function, you must install the IMAP Full-Text Search Indexing (powered by Apache Solr™) plugin in WHM's Manage Plugins interface (WHM >> Home >> cPanel >> Manage Plugins). For more information, read our install_dovecot_fts script documentation.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account

required

string <email>

Example: [email protected]

The email user's account name.

Note:

If you do not enter an email address, the function rescans the default email account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  fts_rescan_mailbox \
  account='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fts_rescan_mailbox",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return server's supported character encodings

This function lists the available character encodings.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  fetch_charmaps

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_charmaps",
"module": "Email",
"result": {"data": [{"map": "utf-8"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return mail server's supported character encodings

This function lists character encodings that the mail server supports.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_charsets

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_charsets",
"module": "Email",
"result": {"data": ["utf-8"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's mailbox autocreate status

This function checks whether a cPanel account will automatically create mailboxes when it receives an email address in plus address format.

Note:

To enable or disable this functionality, use the UAPI's Email::enable_mailbox_autocreate and Email::disable_mailbox_autocreate functions.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email account address to query.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_mailbox_autocreate \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_mailbox_autocreate",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether plaintext authentication is enabled

This function checks whether plaintext authentication is enabled on the Dovecot mail server.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  has_plaintext_authentication

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_plaintext_authentication",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update Mail Exchanger type

This function sets the Mail Exchanger (MX) type.

Note:

This function only affects the cPanel configuration. You must configure the mail exchanger's DNS entry separately.

Important:

When you disable the DNS role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

alwaysaccept	string Default: "auto" Possible Values: "auto" "local" "secondary" "remote" Example: alwaysaccept=auto The mail exchanger type. `auto` — Allow cPanel to determine the appropriate role. `local` — Always accept the domain's mail. `secondary` — Accept mail until a higher priority mail server is available. `remote` — Do not accept mail. Note: This parameter is redundant with the `mxcheck` parameter. Do not enter the `mxcheck` and `alwaysaccept` parameters at the same time. Undefined behavior may occur if this happens.
domain required	string <domain> Example: domain=example.com The mail exchanger's domain.
mxcheck	string Default: "auto" Possible Values: "auto" "local" "secondary" "remote" Example: mxcheck=auto The mail exchanger type. `auto` — Allow cPanel to determine the appropriate role. `local` — Always accept the domain's mail. `secondary` — Accept mail until a higher priority mail server is available. `remote` — Do not accept mail. Note: This parameter is redundant with the `alwaysaccept` parameter. Do not enter the `mxcheck` and `alwaysaccept` parameters at the same time. Undefined behavior may occur if this happens.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  set_always_accept \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_always_accept",
"module": "Email",
"result": {"data": {"checkmx": {"changed": 1,
"detected": "auto",
"isprimary": 0,
"issecondary": 0,
"local": 0,
"mxcheck": "auto",
"remote": 0,
"secondary": 0,
"warnings": ["Auto Detect of MX configuration not possible due to non-resolving MX entries. Defaulting to last known setting: local."
]
},
"detected": "auto",
"local": 0,
"mxcheck": "auto",
"remote": 0,
"results": "Set Always Accept Status to: local",
"secondary": 0,
"status": 1,
"statusmsg": "Set Always Accept Status to: local"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return eximstats SQLite database status

This function returns the status of the eximstats SQLite Database.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  stats_db_status

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "stats_db_status",
"module": "Email",
"result": {"data": "active",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Email Suspensions

Email / Email Suspensions

Suspend email account incoming (SMTP) mail

This function suspends incoming email for an account. The system will reject incoming email while the account is suspended.

Notes:

The user can still log in to the email account. To suspend a user's ability to log in to, send mail from, and read their account, use the UAPI Email::suspend_login function.
Use the UAPI Email::unsuspend_incoming function to allow the account to receive email.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

string <email>

Example: [email protected]

The email user's account name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  suspend_incoming

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "suspend_incoming",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Suspend email account outgoing mail

This function rejects outgoing mail for a suspended email account. This function does not disable a user's login credentials or access permissions to their email account.

Notes:

To suspend a user's login credentials and prevent authenticated connections to the email account, use the UAPI Email::suspend_login function.
To allow an email account to send mail, use the UAPI Email::unsuspend_outgoing function.
To hold outgoing mail in Exim's queue, use the UAPI Email::hold_outgoing function.

Important:

When you disable the Send Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  suspend_outgoing \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "suspend_outgoing",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Suspend email account login

This function suspends a user's ability to log in to their email account. This function immediately suspends the user's login credentials and prevents future authenticated connections to the email account.

Notes:

When you suspend an account, the user's account still receives email.
To suspend incoming email for an account, use the UAPI Email::suspend_incoming function.
To remove the login suspension for an account, use the UAPI Email::unsuspend_login function.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The email user's account name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  suspend_login \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "suspend_login",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Unsuspend email account login

This function restores a user's ability to log in to their email account.

Note:

To suspend a user's ability to log in, use the UAPI Email::suspend_login function.
To suspend incoming email for an account, use the UAPI Email::suspend_incoming function.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

string <email>

Example: [email protected]

The email user's account name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  unsuspend_login

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unsuspend_login",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Unsuspend email account incoming mail

This function unsuspends incoming email for an email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

string <email>

Example: [email protected]

The email user's account name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  unsuspend_incoming

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unsuspend_incoming",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Unsuspend email account outgoing mail

This function cancels the suspension action put in place by the UAPI Email::suspend_outgoing function for outgoing mail for an email account.

Note:

To suspend an email account and reject all outgoing mail, use the UAPI Email::suspend_outgoing function.

Authorizations:

BasicAuth

query Parameters

email

required

string

Example: [email protected]

The email account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  unsuspend_outgoing \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unsuspend_outgoing",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Mail Server Information

Email / Mail Server Information

Return outgoing mail (SMTP) SSL-secured port

This function retrieves Exim's SSL port.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Chkservd \
  get_exim_ports_ssl

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_exim_ports_ssl",
"module": "Chkservd",
"result": {"data": {"ports": [465
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return outgoing (SMTP) mail port

This function lists the ports on which Exim listens.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Chkservd \
  get_exim_ports

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_exim_ports",
"module": "Chkservd",
"result": {"data": {"ports": [25
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Mailbox Management

Email / Mailbox Management

Delete selected messages in mailbox

This function marks the selected mail messages as deleted.

Authorizations:

BasicAuth

query Parameters

required	string or string Examples: [email protected] - The `_mainaccount` alias, which represents the cPanel user's mailbox. account=example - The cPanel user's account name. [email protected] - A valid email account. The email account's name.
mailbox required	string Example: mailbox=INBOX.user@example_com The mailbox to operate on. Note: Use the `Mailboxes::get_mailbox_status_list` function to list possible values for the mailbox parameter. Because you cannot escape wildcard characters such as (`*`), we recommend that you use functions that use the `mailbox_guid` parameter instead. For example, the `Mailboxes::expunge_messages_for_mailbox_guid` function.
query required	string Example: query=savedbefore 52w The Dovecot query to execute. Note: The query parameter prevents accidental removal of all messages in the mailbox. For more information, read Dovecot's Search Query documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mailboxes \
  expunge_mailbox_messages \
  account='[email protected]' \
  mailbox='INBOX.user@example_com' \
  query='savedbefore 52w'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "expunge_mailbox_messages",
"module": "Mailboxes",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account's mailbox status

This function lists the account's mailbox size and globally unique identifier (GUID) by folder.

Authorizations:

BasicAuth

query Parameters

account

required

string

Example: [email protected]

The email account for which you you wish to request the status.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mailboxes \
  get_mailbox_status_list \
  account='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_mailbox_status_list",
"module": "Mailboxes",
"result": {"data": [{"guid": "1234560f0c58d158c92a000044f0d230",
"mailbox": "INBOX.marla_singer@example_com",
"messages": 0,
"vsize": 0
},
{"guid": "11234560f0c58d158c92a000044f0d23",
"mailbox": "INBOX.angel_face@example_com",
"messages": 0,
"vsize": 0
},
{"guid": "111234560f0c58d158c92a000044f0d2",
"mailbox": "INBOX.tyler_durden@example_com",
"messages": 0,
"vsize": 0
},
{"guid": "1111234560f0c58d158c92a000044f0d",
"mailbox": "INBOX.Trash",
"messages": 0,
"vsize": 0
},
{"guid": "11111234560f0c58d158c92a000044f0",
"mailbox": "INBOX.narrator@example_com",
"messages": 0,
"vsize": 0
},
{"guid": "111111234560f0c58d158c92a000044f",
"mailbox": "INBOX",
"messages": 0,
"vsize": 0
},
{"guid": "1111111234560f0c58d158c92a000004",
"mailbox": "INBOX.Sent",
"messages": 0,
"vsize": 0
},
{"guid": "11111111234560f0c58d158c92a00000",
"mailbox": "INBOX.Drafts",
"messages": 0,
"vsize": 0
},
{"guid": "111111111234560f0c58d158c92a0000",
"mailbox": "INBOX.robert_paulsen@example_com",
"messages": 0,
"vsize": 0
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable or disable Webmail mailbox UTF-8 encoding

This function enables or disables UTF-8-encoded mailbox names on Roundcube webmail for a cPanel user's email accounts.

Authorizations:

BasicAuth

query Parameters

enabled

required

integer

Possible Values: 0 1

Example: enabled=1

Whether to enable or disable UTF-8 character-encoded mailbox names.

1 - Enable UTF-8 encoded mailbox names.
0 - Disable UTF-8 encoded mailbox names.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mailboxes \
  set_utf8_mailbox_names \
  enabled='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_utf8_mailbox_names",
"module": "Mailboxes",
"result": {"data": {"success": 1
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return if cPanel account's mailboxes use UTF-8

This function determines whether a cPanel user currently uses UTF-8 character-encoded mailbox names.

Authorizations:

BasicAuth

query Parameters

user	string <username> Example: user=user The user for whom to determine whether they currently use UTF-8 character-encoded mailbox names. Note: This parameter defaults to the currently-logged in user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mailboxes \
  has_utf8_mailbox_names

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_utf8_mailbox_names",
"module": "Mailboxes",
"result": {"data": {"enabled": 1
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete selected messages in mailbox by GUID

This function marks the selected mailbox's messages as deleted.

Authorizations:

BasicAuth

query Parameters

required	string or string Examples: [email protected] - The `_mainaccount` alias, which represents the cPanel user's mailbox. account=example - The cPanel user's account name. [email protected] - A valid email account. The email account's name.
mailbox_guid required	string Example: mailbox_guid=2550860f0c58d158c92a000044f0d230 The mailbox's globally unique identifier (GUID). Use the `Mailboxes::get_mailbox_status_list` function to list possible values for the `mailbox_guid` parameter.
query required	string Example: query=savedbefore 52w The query to select which messages you wish to remove from the mailbox.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mailboxes \
  expunge_messages_for_mailbox_guid \
  account='[email protected]' \
  mailbox_guid='2550860f0c58d158c92a000044f0d230' \
  query='savedbefore 52w'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "expunge_messages_for_mailbox_guid",
"module": "Mailboxes",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Mailing Lists

Email / Mailing Lists

Add administrators to mailing list

This function grants mailing list administrative privileges to users.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

delegates required	string Examples: [email protected],[email protected] - Multiple delegates [email protected] - A single delegate. A list of the administrators to add. Note: Separate multiple email addresses with commas.
list required	string Example: list=mylist The mailing list.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_mailman_delegates \
  list='mylist' \
  delegates='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_mailman_delegates",
"module": "Email",
"result": {"data": {"delegates": ["[email protected], [email protected]"
],
"metadata": {"transformed": null
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account's mailing list total

This function returns the number of mailing lists for every email address on a cPanel account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  count_lists

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "count_lists",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Export cPanel account's Mailman mailing lists to a file

This function exports a cPanel account's Mailman mailing lists into a CSV file. This file is located in mail/exported_lists under the user's home directory.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  export_lists

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "export_lists",
"module": "Email",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete mailing list

This function deletes a Mailman mailing list.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

list

required

string

Example: list=mylist

The mailing list.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  delete_list \
  list='mylist'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_list",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create one-time password for a mailing list

This function generates a one-time password (OTP) for a mailing list.

Note:

The generated password expires after one use.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

list

required

string

Example: list=mylist

The mailing list.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  generate_mailman_otp \
  list='mylist'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "generate_mailman_otp",
"module": "Email",
"result": {"data": "LfFYLPRT_UoS4EDi9lGKuOFK8FaWQsozzPYn8WjM3",
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's mailing list disk usage

This function returns the total disk usage for the mailing lists of a cPanel account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_lists_total_disk_usage

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_lists_total_disk_usage",
"module": "Email",
"result": {"data": 1024,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return mailing list administrators

This function lists a mailing list's administrators.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

list

required

string

Example: list=mylist

The name of a Mailman mailing list on the cPanel account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_mailman_delegates \
  list='mylist'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_mailman_delegates",
"module": "Email",
"result": {"data": {"delegates": ["[email protected]"
],
"metadata": {"transformed": null
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account's mailing list privileges

This function checks an account's administrative privileges on mailing lists.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

delegate

required

string <email>

Example: [email protected]

The email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  has_delegated_mailman_lists \
  delegate='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_delegated_mailman_lists",
"module": "Email",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update mailing list password

This function changes a mailing list's password.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

list required	string Example: [email protected] The full name (including the domain) of a Mailman mailing list on the cPanel account.
password required	string Example: password=12345luggage The new password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  passwd_list \
  list='[email protected]' \
  password='12345luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "passwd_list",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's mailing lists

This function lists the account's Mailman mailing lists.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The domain to query. If you do not use this parameter, the function lists mailing lists for all of the cPanel account's domains.
regex	string Example: regex=user A Perl Compatible Regular Expression (PCRE) that filters the results.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  list_lists

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_lists",
"module": "Email",
"result": {"data": [{"accesstype": "public",
"advertised": 1,
"archive_private": 0,
"desthost": "172.16.254.1",
"diskused": 20379,
"humandiskused": "19.9\\u00a0KB",
"list": "[email protected]",
"listadmin": "[email protected],[email protected]",
"listid": "list_example.com",
"subscribe_policy": 1
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Remove account mailing list admin privileges

This function removes an account's mailing list administrative privileges.

Authorizations:

BasicAuth

query Parameters

delegates required	string Example: [email protected],[email protected] list of the administrators to remove.
list required	string Example: list=mylist The mailing list.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  remove_mailman_delegates \
  list='mylist' \
  delegates='[email protected],[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_mailman_delegates",
"module": "Email",
"result": {"data": {"delegates": ["[email protected]"
],
"metadata": {"transformed": null
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update mailing list privacy options

This function modifies a Mailman mailing list's privacy options.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

advertised required	integer Possible Values: 0 1 Example: advertised=1 Whether the Mailman directory page displays the list. `1` - Display. `0` - Does not display.
archive_private required	integer Possible Values: 0 1 Example: archive_private=1 Whether the mailing list archive is private. `1` - Private. `0` - Public.
list required	string Example: list=mylist The mailing list name.
subscribe_policy required	integer Possible Values: 1 2 3 Example: subscribe_policy=1 The level of control that the mailing list administrator has over new subscribers. `1` - Anyone can subscribe. The system sends a confirmation email. `2` - The administrator must approve subscriptions. The system does not send a confirmation email. `3` - The administrator must approve subscriptions. The system sends a confirmation email.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  set_list_privacy_options \
  list='mylist' \
  advertised='1' \
  archive_private='1' \
  subscribe_policy='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_list_privacy_options",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create mailing list

This function creates a Mailman mailing list.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain.
list required	string Example: list=newlist The mailing list name.
password required	string Example: password=12345luggage The mailing list password.
private	integer Default: 0 Possible Values: 0 1 Example: private=0 Whether the mailing list is private. `1` — Private. `0` — Public.
rebuildonly	integer Default: 0 Possible Values: 0 1 Example: rebuildonly=0 Whether to rebuild the mailing list. `1` — Rebuild the mailing list. `0` — Do not rebuild the mailing list.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_list \
  list='newlist' \
  password='12345luggage' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_list",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Signing and Encryption (GnuPG Keys)

Email / Signing and Encryption (GnuPG Keys)

Export GnuPG secret key

This function exports a GnuPG (GPG) secret key.

Authorizations:

BasicAuth

query Parameters

key_id required	string Example: key_id=48BEA5A16FCA746E The ID of the GPG secret key that you wish to retrieve.
passphrase	string Example: passphrase=whatever The passphrase of the GPG secret key that you wish to retrieve.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  export_secret_key \
  key_id='48BEA5A16FCA746E'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "export_secret_key",
"module": "GPG",
"result": {"data": {"key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v2.0.22 (GNU/Linux)\n\nlQNTBFzwFyMRCADgNf7GHvCgb2/HWBYVAzu408eXEO4ucWGfbD5c5BOHg7WBVOkh\nj+J0HYaeh9FwOXLJAzesiGtTU/HQ5wNkBbKRYR2oNEUbiefBgQhjllIGJNnFCQbD\nTcyxXjKUF4aQBw6InqzM9akVChLvGoCfom/y1fcwrQ5OQ46EEjhe9lSnj1E2DIi+\n0PvOsWeehChtn28WkmXPcl+XovfsCl5vh2RnJQeJwkSwBogA1GObj9fnPBbrIUt2\nF5JDaJ7/R8aDwV1Pg2mBmRqTBIKvx6gxEQgCL52OWCKVJfqy5oVGDl/2u0BGCaRt\n3Tnh9B14Lk8frBaOjYMtMq1Rl3rPDc3KCRnLAQC6dMNJCxIoyfeEFqj0HgwHETYn\nQNGwUaRrOGKLJbMnewf/Yq0S2R6YvMl8pDQeSExYJaqv/u2Hch6GM0f3CSvMnPSg\noB2c/h4MmhmiAbymSO5GBaM4Nx3NTNYU0JpghkTTJpucFZ8hK/aJ8PDQzBnS0zTY\nF8ZqSMFL84QB1NTd1nlJnilpKCkBC6NHUh76IyLQEsH7jgOG9L28qnLxm8bGHwaJ\nmhEH2Y859WzN9hUTZEMxdklI8uwdI+msI7md0uNYiWr5svtM+rrpU+LCZMG+nTCy\n6q0CNLXM0T0Fa642mYSqV307Ouv5rjGvfohIOo5X8ikBoEIOAQk6LX800OzzYGG4\nX75Q4irMuehEK3tId5VIRToy9MRLP6fyOVHwfhzD6Af/R2TJjIdEkEGdspuw9875\nN4z9xV2QNVNgURIOutrfeKSbb7gRLgV7TWpKWItMoEO1njzb4YqoHwcAASj4TDaT\niCYun6u12Mb97L0S3QDaD3sLk7P5sZvnO//k/YxbGISv+HGl5rSF87kVectLYpAL\nehL2EBmyxP4nxhSDOqhc0rbaqOZ+b4F1ns4NsUJjxIqQJZ+ovTqkmKnh3YbBeMAb\nsPcjyfQNmYE9qFXw17vJMm6ypNsuDIvxKCDq4QpO3/MujYX0Hg7aGOq4aWtndcL0\nPfpukTLvTA+AedMj+0QHWiP15bSxCJKqa0O62mKWnrzL0Tju8FKTwVHgRoW57GY/\nZQABALMunDJSN+b/VyFzqifGvopLxJFqA4un4WjGEY9jvJooD7e0JmJlbmRlciAo\naXMgZ3JlYXQpIDxiZW5kZXJAZXhhbXBsZS5jb20+iIEEExEIACkFAlzwFyMCGyMF\nCQHhM4AHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIXgAAKCRBIvqWhb8p0bgAlAP9f\n7rAobi4nA8AmwZSaXGFmgJLeGwuM/sBQDjSp8MJR6AEAqtxkTLaOApKAeqStWYfr\nOUoraI1BayhI/AiTZAEDhmidAj0EXPAXIxAIAOAmNwCp5CL0s33LBQn9TZmYqUBi\nwobN4iIamtzT4qKWKWDDU3QmZJAzEgzONPnfy7YaWJ282FYDwTfThTHS/53X/8rt\nIzxGRNbhKcbx9V/8diHnDMu8JudbrMaQVsEsOwUy3wPQEsw7R/H55IndqmNienzV\nmQwOcKzUeGrlSg5KirGrTAu+RpB3E9jXry3YfErmB+tJELJrwzpLhOLnyMM5Z0OB\nxSrGE8Z+kCEGNfHp7buet3/kQqFAjb9idM8Vxc78vnqOevPlIceCK8/TkETVIf/N\nmthxddKFL5DxLQg5TMvICEhKp1NYtkcvCLG1K74c/psucm+Rpmc/sTilk4sAAwUH\n/2DmCrxyFsOP77Gy1DzJow3TH7J09IWg5S3qwkh4WPmS82EHc/+4QuELf+RL2hnl\n5MAD869E+D71TkFFAIrJLwzUnGEMUuSscqxwKqCpBeBAyfTMig6hDenRfSAzsbgN\nYNHDl+0xz5txo0YdwYzmh5zeY1ysE/OQrO4Y+7tavQpufUVMycESssaPXkd6STEf\nvBNFVvKEXv+zv0L4eeEoQ+zZH4FISFnK4kfTI6BqdIJ6Qjh+di633XMwiMwKFAuE\nNyZvNLAnmQKn+AjR2dE8asbsBvmZH2wgVYjOE1VwxLnwOCBDTJhLtmzVgy5Ea6zZ\nnvkuBxHjUbkoPBDqRVLsDyMAAVIC+56gmf2bW2mDuoFFUW6KT6jorvvbmXSZHi1L\nAGhQj/Q83gRejq2g+DYiFlCIZwQYEQgADwUCXPAXIwIbDAUJAeEzgAAKCRBIvqWh\nb8p0btGLAPsFHEqEg/qrEpjFu/9B8KvBWBgqIJm9XtDgaVaaHjzR4AD/XcrEvMuc\nPVYssXICwKbDwxWEYqhpI6ms0IOob0PH8hE=\n=W2NA\n-----END PGP PRIVATE KEY BLOCK-----"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete GnuPG key pair

This function deletes a GnuPG (GPG) key pair.

Authorizations:

BasicAuth

query Parameters

key_id

required

string

Example: key_id=ACFFDB37176B680D

The ID of the GPG key that you wish to delete.

Note:

The function will delete all keys that match this ID.
- If you set this parameter to a public key, the function will delete the public key.
- If you set this parameter to a public and private key pair, the function will delete the public and private keys.
To obtain the desired key, call the UAPI GPG::list_secret_keys function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  delete_keypair \
  key_id='ACFFDB37176B680D'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_keypair",
"module": "GPG",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Export GnuPG public key

This function exports a GnuPG (GPG) public key.

Authorizations:

BasicAuth

query Parameters

key_id

required

string

Example: key_id=48BEA5A16FCA746E

The ID of the GPG key.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  export_public_key \
  key_id='48BEA5A16FCA746E'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "export_public_key",
"module": "GPG",
"result": {"data": {"key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v2.0.22 (GNU/Linux)\n\nmQMuBFzwFyMRCADgNf7GHvCgb2/HWBYVAzu408eXEO4ucWGfbD5c5BOHg7WBVOkh\nj+J0HYaeh9FwOXLJAzesiGtTU/HQ5wNkBbKRYR2oNEUbiefBgQhjllIGJNnFCQbD\nTcyxXjKUF4aQBw6InqzM9akVChLvGoCfom/y1fcwrQ5OQ46EEjhe9lSnj1E2DIi+\n0PvOsWeehChtn28WkmXPcl+XovfsCl5vh2RnJQeJwkSwBogA1GObj9fnPBbrIUt2\nF5JDaJ7/R8aDwV1Pg2mBmRqTBIKvx6gxEQgCL52OWCKVJfqy5oVGDl/2u0BGCaRt\n3Tnh9B14Lk8frBaOjYMtMq1Rl3rPDc3KCRnLAQC6dMNJCxIoyfeEFqj0HgwHETYn\nQNGwUaRrOGKLJbMnewf/Yq0S2R6YvMl8pDQeSExYJaqv/u2Hch6GM0f3CSvMnPSg\noB2c/h4MmhmiAbymSO5GBaM4Nx3NTNYU0JpghkTTJpucFZ8hK/aJ8PDQzBnS0zTY\nF8ZqSMFL84QB1NTd1nlJnilpKCkBC6NHUh76IyLQEsH7jgOG9L28qnLxm8bGHwaJ\nmhEH2Y859WzN9hUTZEMxdklI8uwdI+msI7md0uNYiWr5svtM+rrpU+LCZMG+nTCy\n6q0CNLXM0T0Fa642mYSqV307Ouv5rjGvfohIOo5X8ikBoEIOAQk6LX800OzzYGG4\nX75Q4irMuehEK3tId5VIRToy9MRLP6fyOVHwfhzD6Af/R2TJjIdEkEGdspuw9875\nN4z9xV2QNVNgURIOutrfeKSbb7gRLgV7TWpKWItMoEO1njzb4YqoHwcAASj4TDaT\niCYun6u12Mb97L0S3QDaD3sLk7P5sZvnO//k/YxbGISv+HGl5rSF87kVectLYpAL\nehL2EBmyxP4nxhSDOqhc0rbaqOZ+b4F1ns4NsUJjxIqQJZ+ovTqkmKnh3YbBeMAb\nsPcjyfQNmYE9qFXw17vJMm6ypNsuDIvxKCDq4QpO3/MujYX0Hg7aGOq4aWtndcL0\nPfpukTLvTA+AedMj+0QHWiP15bSxCJKqa0O62mKWnrzL0Tju8FKTwVHgRoW57GY/\nZbQmYmVuZGVyIChpcyBncmVhdCkgPGJlbmRlckBleGFtcGxlLmNvbT6IgQQTEQgA\nKQUCXPAXIwIbIwUJAeEzgAcLCQgHAwIBBhUIAgkKCwQWAgMBAh4BAheAAAoJEEi+\npaFvynRuACUA/1/usChuLicDwCbBlJpcYWaAkt4bC4z+wFAONKnwwlHoAQCq3GRM\nto4CkoB6pK1Zh+s5SitojUFrKEj8CJNkAQOGaLkCDQRc8BcjEAgA4CY3AKnkIvSz\nfcsFCf1NmZipQGLChs3iIhqa3NPiopYpYMNTdCZkkDMSDM40+d/LthpYnbzYVgPB\nN9OFMdL/ndf/yu0jPEZE1uEpxvH1X/x2IecMy7wm51usxpBWwSw7BTLfA9ASzDtH\n8fnkid2qY2J6fNWZDA5wrNR4auVKDkqKsatMC75GkHcT2NevLdh8SuYH60kQsmvD\nOkuE4ufIwzlnQ4HFKsYTxn6QIQY18entu563f+RCoUCNv2J0zxXFzvy+eo568+Uh\nx4Irz9OQRNUh/82a2HF10oUvkPEtCDlMy8gISEqnU1i2Ry8IsbUrvhz+my5yb5Gm\nZz+xOKWTiwADBQf/YOYKvHIWw4/vsbLUPMmjDdMfsnT0haDlLerCSHhY+ZLzYQdz\n/7hC4Qt/5EvaGeXkwAPzr0T4PvVOQUUAiskvDNScYQxS5KxyrHAqoKkF4EDJ9MyK\nDqEN6dF9IDOxuA1g0cOX7THPm3GjRh3BjOaHnN5jXKwT85Cs7hj7u1q9Cm59RUzJ\nwRKyxo9eR3pJMR+8E0VW8oRe/7O/Qvh54ShD7NkfgUhIWcriR9MjoGp0gnpCOH52\nLrfdczCIzAoUC4Q3Jm80sCeZAqf4CNHZ0TxqxuwG+ZkfbCBViM4TVXDEufA4IENM\nmEu2bNWDLkRrrNme+S4HEeNRuSg8EOpFUuwPI4hnBBgRCAAPBQJc8BcjAhsMBQkB\n4TOAAAoJEEi+paFvynRu0YsA/0rluXh9ij3Np4O/KWuL2L8zcOrJJ7mNFuw0wkpY\nfZ3NAP9ayHG+70XellsQ/E3lR8fkRwqDDRh43w7ukhJEfkcY9A==\n=yyST\n-----END PGP PUBLIC KEY BLOCK-----\n"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create GnuPG key

This function generates a GnuPG (GPG) key. The system saves the key in the user's .gnupg directory.

Note:

This function uses the system's entropy to generate the key. Systems with low entropy levels may cause long generation times or timeouts.

Authorizations:

BasicAuth

query Parameters

comment	string Default: null Example: comment=Username's Key A comment about the key.
email required	string <email> Example: [email protected] The user's email address.
expire	string Example: expire=1560363242 The desired expiration date of the key as a timestamp in Unix time format. Note: This will default to one year from the current date.
keysize	integer [ 1024 .. 4096 ] Default: 2048 Possible Values: 1024 2048 3072 4096 Example: keysize=2048 The new key's size, in bytes. Note: Large keys require more time to generate.
name required	string <username> Example: name=username The name of the user for whom to generate the key.
no_expire	integer Default: 0 Possible Values: 0 1 Example: no_expire=0 Whether to generate the key without an expiration date. `0` - The key will expire. `1` - The key will not expire.
passphrase required	string Default: null Example: passphrase=123456luggage The key's password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  generate_key \
  name='username' \
  email='[email protected]'
  passphrase='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "generate_key",
"module": "GPG",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Import GnuPG key

This function imports a GnuPG (GPG) key.

Authorizations:

BasicAuth

query Parameters

key_data

required

string

Example: key_data=%0A-----BEGIN%20PGP%20PUBLIC%20KEY%20BLOCK-----%0AVersion%3A%20GnuPG%20v2.0.14%20(GNU%2FLinux)%0A%0AmQENBFN0%2BOsBCADoFvyf8gHIKZ%2F%2B5KwbWb3Ht%2Fz1ukyQqFNGpBVIqHossmjmyF9e%0APn6iiZ0fHnt7r6XGGXaP%2BKKjIxAcqOTiFiP%2BHIx6GQubzVih6Ol0YNjzmK%2Ft4f%2B4%0AfSElEVnyzeyJa4LmC%2Fui%2FvvtptJ8JX6su7f11BwUTSyuqnk204AfN5uVpAcZNPT0%0A0qNNky1bxYvPUxU6Imvi1q3NtpFzqsQ4u%2FyZuLpUe7uwmgMPeO0lAms1kCa3Guot%0A3mfSt0vrUAMdcV4drY1FGtYZdYSa4rSTzpFuB7o9Ze%2BE3fUbCWs1%2B0FiN3JQNGO1%0AS2lnqjEqbpz2nHtA50elJRGqxZLEi8zkFqlTABEBAAG0Z2NQYW5lbCBTZWN1cml0%0AeSBUZWFtIC0gVEVTVCAoVEhJUyBJUyBBIFRFU1QgS0VZOyBETyBOT1QgVVNFIEZP%0AUiBBTllUSElORyBSRUFMISkgPHNlY3RlYW1zaXhAY3BhbmVsLm5ldD6JAT4EEwEC%0AACgFAlN0%2BOsCGwMFCQHhM4AGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEOhU%0A60c9RtoRkhMIAIe2yDKj55mGD3zbuGqxx6NNNIyiuEujw31N8yOS9BKTqGtIiK9i%0AGu4lzrzmHISKi0rjKmJdbckap7OouUoo9WR3ewjN6S5EHyjKfrrMwMzTWMPZOkTj%0A7A698X0vGc9yZ6KyBj8mM8J9duvNtRS285hfXfQxYO%2FuiyrJGBedI%2FWVZ3a7mcfq%0A7FhC8t6jU6sz9uIvYHAzywcVdmhEK5rS%2FuE%2F9e37h46jn2%2BkzlIWEe%2FYgpa%2BuWdT%0AO%2BOyqteW51LEjXLWMyP8AJEq8EoqbqKnm4Q1g0etOQ9trrkLUnPxaSwD5R6i4KLH%0AMR%2Fh7m%2FOoz8yOhUlrCGJwX7v9qDEdaYYFLQ%3D%0A%3DMEFZ%0A-----END%20PGP%20PUBLIC%20KEY%20BLOCK-----%0A

The key to import.

Note:

You must URI-encode this value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  import_key \
  key_data='%0A-----BEGIN%20PGP%20PUBLIC%20KEY%20BLOCK-----%0AVersion%3A%20GnuPG%20v2.0.14%20(GNU%2FLinux)%0A%0AmQENBFN0%2BOsBCADoFvyf8gHIKZ%2F%2B5KwbWb3Ht%2Fz1ukyQqFNGpBVIqHossmjmyF9e%0APn6iiZ0fHnt7r6XGGXaP%2BKKjIxAcqOTiFiP%2BHIx6GQubzVih6Ol0YNjzmK%2Ft4f%2B4%0AfSElEVnyzeyJa4LmC%2Fui%2FvvtptJ8JX6su7f11BwUTSyuqnk204AfN5uVpAcZNPT0%0A0qNNky1bxYvPUxU6Imvi1q3NtpFzqsQ4u%2FyZuLpUe7uwmgMPeO0lAms1kCa3Guot%0A3mfSt0vrUAMdcV4drY1FGtYZdYSa4rSTzpFuB7o9Ze%2BE3fUbCWs1%2B0FiN3JQNGO1%0AS2lnqjEqbpz2nHtA50elJRGqxZLEi8zkFqlTABEBAAG0Z2NQYW5lbCBTZWN1cml0%0AeSBUZWFtIC0gVEVTVCAoVEhJUyBJUyBBIFRFU1QgS0VZOyBETyBOT1QgVVNFIEZP%0AUiBBTllUSElORyBSRUFMISkgPHNlY3RlYW1zaXhAY3BhbmVsLm5ldD6JAT4EEwEC%0AACgFAlN0%2BOsCGwMFCQHhM4AGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEOhU%0A60c9RtoRkhMIAIe2yDKj55mGD3zbuGqxx6NNNIyiuEujw31N8yOS9BKTqGtIiK9i%0AGu4lzrzmHISKi0rjKmJdbckap7OouUoo9WR3ewjN6S5EHyjKfrrMwMzTWMPZOkTj%0A7A698X0vGc9yZ6KyBj8mM8J9duvNtRS285hfXfQxYO%2FuiyrJGBedI%2FWVZ3a7mcfq%0A7FhC8t6jU6sz9uIvYHAzywcVdmhEK5rS%2FuE%2F9e37h46jn2%2BkzlIWEe%2FYgpa%2BuWdT%0AO%2BOyqteW51LEjXLWMyP8AJEq8EoqbqKnm4Q1g0etOQ9trrkLUnPxaSwD5R6i4KLH%0AMR%2Fh7m%2FOoz8yOhUlrCGJwX7v9qDEdaYYFLQ%3D%0A%3DMEFZ%0A-----END%20PGP%20PUBLIC%20KEY%20BLOCK-----%0A'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "import_key",
"module": "GPG",
"result": {"data": {"key_id": "59E79B6904616529"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return current user's GnuPG public keys

This function lists the GnuPG (GPG) public keys for the currently-authenticated account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  list_public_keys

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_public_keys",
"module": "GPG",
"result": {"data": [{"algorithm": "DSA",
"bits": 2048,
"created": "1559238435",
"expires": "1590774435",
"id": "C801294347601B8F",
"type": "pub",
"user_id": "bender (is great) <[email protected]>"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return current user's GnuPG secret keys

This function lists the GnuPG (GPG) secret keys for the currently-authenticated account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  GPG \
  list_secret_keys

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_secret_keys",
"module": "GPG",
"result": {"data": [{"algorithm": "DSA",
"bits": 2048,
"created": 1559238435,
"expires": 1590774435,
"id": "738538C1",
"type": "sec",
"user_id": "username (John Doe) <[email protected]>"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Spam Filtering (Greylisting)

Email / Spam Filtering (Greylisting)

Disable Greylisting for all domains

This function disables Greylisting on a cPanel account's domains.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPGreyList \
  disable_all_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_all_domains",
"module": "cPGreyList",
"result": {"data": [{"dependencies": ["this.com",
"that.com",
"theother.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "this, that, the other",
"type": "main"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable Greylisting for all domains

This function enables Greylisting on all of the cPanel account's domains.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPGreyList \
  enable_all_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_all_domains",
"module": "cPGreyList",
"result": {"data": [{"dependencies": ["this.com",
"that.com",
"theother.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "this, that, and the other.",
"type": "main"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return whether Greylisting is enabled

This function checks whether Greylisting is enabled for the cPanel account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPGreyList \
  has_greylisting_enabled

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_greylisting_enabled",
"module": "cPGreyList",
"result": {"data": {"enabled": 0
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable Greylisting for specified domains

This function disables Greylisting on a cPanel account's selected domains.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Examples:

domains=domain=example.com domain=example1.com domain=example2.com - Multiple domains.
domains=example.com - A single domain.

The domain on which to disable Greylisting.

Note:

To disable Greylisting on multiple domains, use the domains parameter multiple times.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPGreyList \
  disable_domains \
  domains='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_domains",
"module": "cPGreyList",
"result": {"data": [{"dependencies": ["this.com",
"that.com",
"theother.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "this, that, the other",
"type": "main"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return Greylisting status for domains

This function returns Greylisting's status for a cPanel account's domains.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPGreyList \
  list_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_domains",
"module": "cPGreyList",
"result": {"data": [{"cPGreyList": {"total_disabled": 1,
"total_enabled": 0
},
"dependencies": ["this.com",
"that.com",
"theother.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "this, that, and the other.",
"type": "main"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable Greylisting for specified domains

This function enables Greylisting on a cPanel account's selected domains.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Examples:

domains=domain=example.com&domain=example1.com&domain=example2.com - Multiple domains.
domains=example.com - A single domain.

The domain on which to enable Greylisting.

Note:

To enable Greylisting on multiple domains, use the domains parameter multiple times.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPGreyList \
  enable_domains \
  domains='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_domains",
"module": "cPGreyList",
"result": {"data": [{"dependencies": ["example.com",
"example1.com",
"example2.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "example, example1, example2",
"type": "main"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Spam Management

Email / Spam Management

Disable Apache SpamAssassin for cPanel account

This function disables Apache SpamAssassin™ for a cPanel account.

Important:

When you disable the Spam Filter role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  disable_spam_assassin

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_spam_assassin",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": ["Apache SpamAssassin™ has been disabled."
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable spam box filtering for cPanel account

This function disables spam box filtering for a cPanel account. When you disable spam box filtering, the system sends all messages to the account's inbox.

Notes:

This function requires that your hosting provider enables Apache SpamAssassin™ on the server.
To enable spam box filtering, use the UAPI Email::enable_spam_box function.
For more information, read our Spam Filters documentation.

Important:

When you disable the Spam Filter role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  disable_spam_box

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_spam_box",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable spam box filtering auto-delete

This function disables the Apache SpamAssassin™ auto-delete spam feature.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  disable_spam_autodelete

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_spam_autodelete",
"module": "Email",
"result": {"data": {"spam_auto_delete": 0
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable spam box filtering for cPanel account

This function enables spam box filtering for a cPanel account. When you enable spam box filtering, the system sends messages marked as spam to a spam folder.

Notes:

This function requires that your hosting provider enables Apache SpamAssassin on the server.
To disable spam box filtering, use the UAPI Email::disable_spam_box function.
For more information, read our Spam Filters documentation.

Important:

When you disable the Spam Filter role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  enable_spam_box

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_spam_box",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable Apache SpamAssassin for cPanel account

This function enables Apache SpamAssassin™ for the account.

Important:

When you disable the Spam Filter role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  enable_spam_assassin

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_spam_assassin",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return email account Apache SpamAssassin settings

This function retrieves the Apache SpamAssassin™ settings for the account.

Important:

When you disable the SpamFilter role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account

string <email>

Example: [email protected]

Retrieve a specific user account's SpamAssassin settings.

Note:

If you do not specify this parameter, the function returns the settings for the default email account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  get_spam_settings

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_spam_settings",
"module": "Email",
"result": {"data": {"cpuser_spam_auto_delete": 1,
"cpuser_spam_auto_delete_score": 8,
"rewrites_subjects": 1,
"spam_as_acl": 1,
"spam_auto_delete": 0,
"spam_auto_delete_score": 8,
"spam_box_enabled": 0,
"spam_enabled": 1,
"spam_status_changeable": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete spam box contents

This function clears the spam box of all its contents for all email accounts.

Important:

This function deletes the Spam Box folder contents for every email address on the account, which includes the system user email account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SpamAssassin \
  clear_spam_box

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "clear_spam_box",
"module": "SpamAssassin",
"result": {"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return SpamAssassin™ symbolic test scores

This function lists the Apache SpamAssassin™ scores for each symbolic test.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
errors	any
func	string The name of the method called.
messages	any
module	string The name of the module called.
	object
status	any

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SpamAssassin \
  get_symbolic_test_names

Response samples

200

Content type

application/json

{"apiversion": 3,
"errors": null,
"func": "get_symbolic_test_names",
"messages": null,
"module": "SpamAssassin",
"result": {"data": [{"key": "ACT_NOW_ALL_CAPS",
"rule_type": "body_tests",
"score": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
},
"status": null
}

Return SpamAssassin™ settings

This function lists the Apache SpamAssassin™ settings for the account.

Note:

Additional customizations may appear in the returns. Form more information read the Apache SpamAssassin™ configuration file documentation.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SpamAssassin \
  get_user_preferences

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_user_preferences",
"module": "SpamAssassin",
"result": {"data": {"blacklist_from": ["[email protected]"
],
"required_score": [5.1
],
"score": ["ACT_NOW_CAPS 1"
],
"whitelist_from": ["[email protected]"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update SpamAssassin™ settings

This function sets the Apache SpamAssassin™ settings for the account.

Note:

Additional customizations may appear in the function's return. For more information, read the Apache SpamAssassin configuration file documentation.

Authorizations:

BasicAuth

query Parameters

preference

required

string

Example: preference=score

The variable that you want to manipulate.

score
required_score
whitelist_from
blacklist_from
A custom SpamAssassin variable.

Important:

You can only choose one of these possible values per call.
If you enter a value for the preference parameter, but you do not define a value for the value parameter, the function will remove any previous settings.

value

string

Examples:

value=value-0=ACT_NOW_CAPS 5.0 value-1=INVALID_DATE 3.2 - Define multiple variable values.
value=ACT_NOW_CAPS 5.0 - Define a single variable value.

The value for the preference of the variable that you want to manipulate.

A valid SpamAssassin "TEST_NAME SCORE" value when the value of the preference parameter is score, where:
- TEST_NAME represents the symbolic name of the test. For list of symbolic test names, run the UAPI SpamAssassin::get_symbolic_test_names function.
- SCORE represents the floating-point value that SpamAssassin assigns to the mail when the test result is true. The score value must be greater than 0, and less than 1000.
A valid floating-point number if the value of the preference parameter is required_score.
A valid email address if the value of the preference parameter is whitelist_from or blacklist_from.
A custom SpamAssassin variable value.

Note:

To enter multiple values, increment the parameter name. For example, use the value-0 and value-1 parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SpamAssassin \
  update_user_preference \
  preference='score'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update_user_preference",
"module": "SpamAssassin",
"result": {"data": {"blacklist_from": ["[email protected]"
],
"ok_locales": ["all"
],
"required_score": [5
],
"score": ["ACT_NOW_CAPS 5"
],
"whitelist_from": ["[email protected]"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update minimum spam score threshold value

This function sets a new minimum Apache SpamAssassin™ spam score threshold value.

Notes:

To disable spam filtering, use the UAPI Email::disable_spam_autodelete fuction.
For more information, read our Spam Filters documentation.

Important:

When you disable the Spam Filter role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account

string <email>

Example: [email protected]

The email account to apply a spam score threshold value.

Note:

If you do not specify a value, the function applies the new spam score threshold value to all accounts.

required_score

string >= 1

Default: 5

Example: required_score=8

Set a spam score threshold value.

Notes:

You must specify a value greater than 0, and lower than the domain owner's spam score threshold value.
You cannot enter 0 as a value for this parameter.
You can retrieve the domain owner‘s spam score threshold value via the cpuser_spam_auto_delete_score return from the UAPI Email::get_spam_settings function.
The default value, 5, is an aggressive spam score.
The lower the spam score, the more likely that Apache SpamAssassin will label messages as spam and delete them.
Some systems may wish to use a more lenient spam score (for example, 8 or 10).

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  add_spam_filter

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_spam_filter",
"module": "Email",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Spam Prevention (BoxTrapper)

Email / Spam Prevention (BoxTrapper)

Enable or disable BoxTrapper for email account

This function enables or disables BoxTrapper for an email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: [email protected] The account's name. This can be an email address or the cPanel user’s username. Warning: If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.
enabled required	integer Possible Values: 0 1 Example: enabled=1 Whether to enable or disable BoxTrapper for the email account. `1` - Enable BoxTrapper. `0` - Disable BoxTrapper.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  set_status \
  email='[email protected]' \
  enabled='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_status",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add email address to BoxTrapper blocked senders

This function blacklists email message senders.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string <email> Example: [email protected] The email address for which to blacklist messages. Warning: If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated user.
queuefile required	string Examples: queuefile=queuefile=file1&queuefile=file2 - Blacklist multiple filenames. queuefile=file1 - Blacklist one filename. The filename of the email message to blacklist.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  blacklist_messages \
  email='[email protected]' \
  queuefile='file1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "blacklist_messages",
"module": "BoxTrapper",
"result": {"data": [{"email": "[email protected]",
"failed": 1,
"matches": ["example.msg"
],
"operator": "blacklist",
"reason": "This is a failure message.",
"warning": 1
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Send messages in the BoxTrapper queue

This function delivers messages in the BoxTrapper queue.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

all_like	integer Default: 0 Possible Values: 0 1 Example: all_like=1 Whether to deliver all messages that resemble the `queuefile` parameter's value. `1` - Deliver all similar messages. `0` - Don't deliver all similar messages.
email required	string <email> Example: [email protected] The sender's cPanel account email address for which to deliver email messages. Warning: If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.
queuefile required	string Examples: queuefile=queuefile=example.msg&queuefile=example1.msg&queuefile=example2.msg - Deliver multiple email messages. queuefile=example.msg - Deliver a single email message. The filename of the email messages to deliver. Note: To deliver multiple email messages, pass this parameter multiple times.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  deliver_messages \
  email='[email protected]' \
  queuefile='example.msg'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "deliver_messages",
"module": "BoxTrapper",
"result": {"data": [{"email": "[email protected]",
"failed": 1,
"matches": ["example.msg"
],
"operator": "deliverall",
"reason": "This is a failure message.",
"warning": 1
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return specified BoxTrapper email template

This function retrieves a BoxTrapper email message template.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string <email> Example: [email protected] A valid email address on the cPanel account. Warning: If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.
template required	string Possible Values: "blacklist" "returnverify" "verifyreleased" "verify" Example: template=verify The message template. `blacklist` `returnverify` `verifyreleased` `verify` Note: For more information on each template, read our BoxTrapper documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_email_template \
  email='[email protected]' \
  template='verify'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_email_template",
"module": "BoxTrapper",
"result": {"data": "To: %email%\\nSubject: Re: %subject%\\n\\nThe user %acct% does not accept mail from your address.\\n\\nThe headers of the message sent from your address are shown below:\\n\\n%headers%\\n\",",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return message's top 200 lines in BoxTrapper queue

This function returns the first 200 lines of an email in the BoxTrapper queue.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: [email protected] The account’s name, either an email address or the cPanel user’s username. Important: If you call this function in Webmail, the system ignores this parameter.
queuefile required	string Example: queuefile=example.msg The message's filename.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_message \
  email='[email protected]' \
  queuefile='example.msg'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_message",
"module": "BoxTrapper",
"result": {"data": {"content": "From [email protected] Tue May 07 08:30:36 2019\nReceived: from user by example.com with local (Exim 4.92) (envelope-from <[email protected]>)\n    id 1hO0B1-0003Ev-Md for [email protected]; Tue, 07 May 2019 08:30:36 -0500\nFrom: [email protected]\nSubject: Message\nMessage-Id: <[email protected]>\nDate: Tue, 07 May 2019 08:30:35 -0500\n\nThis is an email message",
"contents": null,
"queuefile": "example.msg"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return account BoxTrapper blocklist rules

This function retrieves a list of BoxTrapper blocklist configuration rules. BoxTrapper will delete messages that match these rules and send a notification to the sender.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

A valid email address on the cPanel account.

Warning:

If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_blocklist \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_blocklist",
"module": "BoxTrapper",
"result": {"data": ["from blocklisted-email\\@domain\\.com"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return account BoxTrapper ignorelist rules

This function retrieves a list of BoxTrapper ignorelist configuration rules. BoxTrapper will delete messages that match these rules without sending a notification to the sender.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

A valid email address on the cPanel account.

Warning:

If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_ignorelist \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_ignorelist",
"module": "BoxTrapper",
"result": {"data": ["from ignored-email\\@domain\\.com"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add email account to Exim ignore list

This function marks email message senders for Exim to ignore.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string <email> Example: [email protected] The cPanel email account from which to ignore messages. Warning: If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.
queuefile required	string Examples: queuefile=queuefile-1=example1.msg queuefile-2=example2.msg queuefile-3=example3.msg - Ignore multiple email messages. queuefile=example.msg - Ignore a single email message. The filename of the email message to ignore. Note: To ignore multiple email messages, duplicate this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  ignore_messages \
  email='[email protected]' \
  queuefile='example.msg'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ignore_messages",
"module": "BoxTrapper",
"result": {"data": [{"email": "[email protected]",
"matches": ["example.msg"
],
"operator": "ignore"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return email account's BoxTrapper queued messages

This function returns a list of messages in the account's BoxTrapper queue.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

date	integer <unix_timestamp> Default: "the current time" Example: date=1556812881 The date for which to return queued messages.
email required	string <email> Example: [email protected] The email account for which to retrieve queued messages. Important: If you call this function in Webmail, the system ignores this parameter and defaults to the currently authenticated email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  list_queued_messages \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_queued_messages",
"module": "BoxTrapper",
"result": {"data": [{"from": "[email protected]",
"queuefile": "example.msg",
"subject": "Email Message Subject",
"time": 1556812881
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Restore default BoxTrapper email message template

This function restores the BoxTrapper email message templates to the system default setting.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

string <email>

Example: [email protected]

The account's email address.

Warning:

The email parameter is required when this function is called outside of webmail. If you call this function in Webmail, the email parameter is not required, and the system overrides this parameter with the current authenticated user's email address.

template

required

string

Possible Values: "blacklist" "verify" "verifyreleased" "returnverify"

Example: template=verify

The message template. Possible values:

blacklist - BoxTrapper responds with this message when a blacklisted address sends an email.
verify - BoxTrapper responds with this message when an address that does not exist on the whitelist or blacklist sends an email. This message requests a response to confirm that the sender is legitimate.
verifyreleased - BoxTrapper responds with this message when a person responds to the verify message with an email or a click on the verification link.
returnverify - BoxTrapper responds with this message when the verification process fails.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  reset_email_template \
  template='verify'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "reset_email_template",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Save BoxTrapper message template contents

This function saves the contents of a BoxTrapper message template.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

contents required	string Example: contents=To: %email% Subject: Re: %subject% The user %acct% does not accept mail from your address. The headers of the message sent from your address are shown below: %headers% The template file's contents. You can use variables in the template to include details about the original message. Important: You must include `To: %email%` in this parameter's value. If you use the `verify` template, you must include `Subject: verify#%msgid%` in this parameter's value. This value cannot exceed four kilobytes (KB). You must URI-encode this parameter's value when using the CLI.
email required	string <email> Example: [email protected] The account's email address. Warning: If you call this function in Webmail, the system overrides this parameter. Note: This parameter defaults to the current email address.
template required	string Possible Values: "blacklist" "returnverify" "verifyreleased" "verify" Example: template=blacklist The message template. `blacklist` `returnverify` `verifyreleased` `verify` Important: If you use the `verify` template, you must include `Subject: verify#%msgid%` in this parameter's value. Note: For more information about each template, read our BoxTrapper documentation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  save_email_template \
  email='[email protected]' \
  template='blacklist' \
  contents='To: %25email%25
Subject: Re: %25subject%25

The user %25acct%25 does not accept mail from your address.

The headers of the message sent from your address are shown below:

%25headers%25'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "save_email_template",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update account BoxTrapper ignorelist

This function sets the BoxTrapper ignorelist configuration rules. BoxTrapper will delete messages that match these rules without sending a notification to the sender.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

A valid email address on the cPanel account.

Warning:

If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.

rules

required

Array of strings

Examples:

rules=rules-1='ignored-email\@domain\.com' rules-2='from ignored-email2\@domain\.com' rules-3='to domain2\.com' - Set multiple rules.
rules=rules='ignored-email\@domain\.com' rules='from ignored-email2\@domain\.com' rules='to domain2\.com' - Set multiple rules.
rules=ignored-email\@domain\.com - Set a single rule.

An array of ignorelist rules.

Note:

You can set multiple ignore rules, duplicate or increment the parameter name. For example, rules-1, rules-2, and rules-3.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username BoxTrapper set_ignorelist email='[email protected]' rules-1='ignored-email\@domain\.com' rules-2='from ignored-email2\@domain\.com' rules-3='to domain2\.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_ignorelist",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add email address to BoxTrapper allowed senders

This function whitelists email messages.

Important:

When you disable the Receive Mail role, the system disables this function.

Note:

To retrieve email messages in the BoxTrapper queue from senders that you did not previously whitelist, use the UAPI BoxTrapper::deliver_messages function.

Authorizations:

BasicAuth

query Parameters

email

string <email>

Example: [email protected]

The cPanel account email address for which to whitelist messages.

Warning

If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.

queuefile

required

string

Examples:

queuefile=queuefile=ex1.msg&queuefile=ex2.msg&queuefile=ex3.msg - Whitelist multiple messages.
queuefile=example.msg - Whitelist a single message.

The filename of the email message to whitelist.

Note:

To get a list of filenames in an account's BoxTrapper queue, use the UAPI BoxTrapper::list_queued_messages function.

Note:

To whitelist multiple email messages, duplicate this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  whitelist_messages \
  queuefile='example.msg'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "whitelist_messages",
"module": "BoxTrapper",
"result": {"data": [{"email": "[email protected]",
"matches": ["example.msg"
],
"operator": "whitelist"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update account BoxTrapper blocklist

This function sets the BoxTrapper blocklist configuration rules. BoxTrapper will delete messages that match these rules and send a notification to the sender.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

A valid email address on the cPanel account.

Warning:

If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.

rules

required

Array of strings

Examples:

rules=rules-1='blocklisted-email\@domain\.com' rules-2='from blocklisted-email2\@domain\.com' rules-3='to domain2\.com' - Set multiple rules.
rules=rules='blocklisted-email\@domain\.com' rules='from blocklisted-email2\@domain\.com' rules='to domain2\.com' - Set multiple rules.
rules=blocklisted-email\@domain\.com - Set a single rule.

An array of blocklist rules.

Note:

You can set multiple block rules, duplicate or increment the parameter name. For example, rules-1, rules-2, and rules-3.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username BoxTrapper set_blocklist email='[email protected]' rules-1='blocklisted-email\@domain\.com' rules-2='from blocklisted-email2\@domain\.com' rules-3='to domain2\.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_blocklist",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete messages in the BoxTrapper queue

This function deletes messages in the BoxTrapper queue.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

all_like	integer Default: 0 Possible Values: 1 0 Example: all_like=1 Whether to delete all messages that resemble the `queuefile` parameter's value. `1` - Delete all messages resembling the `queuefile` parameter. `0` - Do not delete all messages resembling the `queuefile` parameter.
email required	string <email> Example: [email protected] The account's email address. Warning: If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.
queuefile required	string Examples: queuefile=queuefile=file1.msg&queuefile=file2.msg - Delete multiple filenames. queuefile=file1.msg - Delete a single filename. The filename of the email message who's sender to delete. Warning: To delete multiple email message senders, duplicate the parameter name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  delete_messages \
  email='[email protected]' \
  queuefile='file1.msg'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_messages",
"module": "BoxTrapper",
"result": {"data": [{"email": "[email protected]",
"failed": 1,
"matches": ["example.msg"
],
"operator": "delete",
"reason": "(XID d9myfd) The system failed to locate the requested message:",
"warning": 1
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return account BoxTrapper allowlist rules

This function retrieves a list of BoxTrapper allowlist configuration rules. BoxTrapper will deliver emails that match these rules.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

A valid email address on the cPanel account.

Warning:

If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_allowlist \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_allowlist",
"module": "BoxTrapper",
"result": {"data": ["from allowlisted-email\\@domain\\.com"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return all BoxTrapper forwarders

This function retrieves a list of email addresses to which BoxTrapper forwards email messages.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The account's email address.

Important:

If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_forwarders \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_forwarders",
"module": "BoxTrapper",
"result": {"data": ["[email protected], [email protected], [email protected]"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return email account's BoxTrapper configuration

This function retrieves an account's BoxTrapper configuration.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The account's email address.

Warning:

If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_configuration \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_configuration",
"module": "BoxTrapper",
"result": {"data": {"enable_auto_whitelist": 1,
"from_addresses": "[email protected],[email protected]",
"from_name": "User",
"queue_days": 14,
"spam_score": 2.5,
"whitelist_by_association": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether email account uses BoxTrapper

This function checks whether BoxTrapper is enabled for an email account.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

The account's email address.

Important:

If you call this function in Webmail, the system ignores this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_status \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_status",
"module": "BoxTrapper",
"result": {"data": 0,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return BoxTrapper email templates

This function lists the BoxTrapper email templates.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  list_email_templates

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_email_templates",
"module": "BoxTrapper",
"result": {"data": ["blacklist",
"returnverify",
"verify",
"verifyreleased"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return BoxTrapper log file and contents

This function returns the account's BoxTrapper log file and its contents.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

date	integer <unix_timestamp> Example: date=1556812881 The date for which to return the log file and its contents. Note: This parameter defaults to the current date.
email required	string <email> Example: [email protected] The account's email address. Important: If you call this function in Webmail, the system ignores this parameter and defaults to the currently authenticated email address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  get_log \
  email='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_log",
"module": "BoxTrapper",
"result": {"data": {"date": 1556812881,
"lines": ["Processing email with trusted transport method."
],
"path": "/home/user/etc/example.com/user/boxtrapper/log/05-02-2019.log"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update email account's BoxTrapper configuration

This function modifies an account's BoxTrapper configuration.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string <email> Example: [email protected] The account's email address. Warning: If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.
enable_auto_whitelist required	integer Possible Values: 0 1 Example: enable_auto_whitelist=1 Whether to enable automatic whitelisting for the account. `1` - Enable. `0` - Disable.
from_addresses required	string <email-csv> Example: [email protected],[email protected] A comma-separated list of email addresses that the system uses when it sends messages back to the original message senders.
from_name	string Example: from_name=User The name of the person who owns the email account.
queue_days required	integer >= 1 Example: queue_days=14 The number of days to retain log files and queued messages.
spam_score	number Example: spam_score=2.5 The account's Apache SpamAssassin™ threshold score. For more information about Apache SpamAssassin threshold scores, read our Spam Filters documentation. Note: This parameter defaults to the account's current configuration.
whitelist_by_association required	integer Possible Values: 0 1 Example: whitelist_by_association=1 Whether to whitelist the email addresses in a message's To and From sections, including carbon-copied (CC) recipients. `1` - Whitelist. `0` - Do not whitelist.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  save_configuration \
  email='[email protected]' \
  from_addresses='[email protected],[email protected]' \
  queue_days='14' \
  enable_auto_whitelist='1' \
  whitelist_by_association='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "save_configuration",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Run a specific BoxTrapper action for a message

This function performs a specified action on messages in the BoxTrapper queue.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

action required	string Possible Values: "deliver" "deliverall" "delete" "deleteall" "blacklist" "whitelist" "ignore" Examples: action=action=blacklist action=deleteall - Perform multiple actions. action=blacklist - Perform a single action. The action to perform on the email message file. To perform multiple actions on the specified email messages, pass this parameter multiple times. `deliver` — Deliver a specific message. `deliverall` — Deliver all messages from a sender. `delete` — Delete a message. `deleteall` — Delete all messages from a sender. `blacklist` — Blacklist the sender of an email message. `whitelist` — Whitelist the sender of an email message. `ignore` — Ignore email messages from a sender. Note: The function performs the actions on the email messages files in the order that you pass each action.
email	string <email> Example: [email protected] The account's email address. Warning: The `email` parameter is required when this function is called outside of Webmail. If you call this function in Webmail, the `email` parameter is not required, and the system overrides this parameter with the current authenticated user's email address.
queuefile required	string Examples: queuefile=email=example.msg email=example1.msg email=example2.msg - Process multiple email messages. queuefile=example.msg - Process a single email message. The filename of the email message to process. To process multiple email messages, pass this parameter multiple times.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  process_messages \
  queuefile='example.msg' \
  action='blacklist'

Response samples

200

Content type

application/json

Example

The function failed.

{"apiversion": 3,
"module": "BoxTrapper",
"result": {"data": [{"email": null,
"failed": 1,
"matches": ["example"
],
"reason": "(XID 2ymu8k) The system failed to locate the requested message:  example.msg"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": ["One or more of the operations failed."
]
}
}

Update account BoxTrapper allowlist

This function sets the BoxTrapper allowlist configuration rules. BoxTrapper will deliver emails that match these rules.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email

required

string <email>

Example: [email protected]

A valid email address on the cPanel account.

Warning:

If you call this function in Webmail, the system overrides this parameter. This parameter defaults to the current email address.

rules

required

Array of strings

Examples:

rules=rules-1='allowlisted-email\@domain\.com' rules-2='from allowlisted-email2\@domain\.com' rules-3='to domain2\.com' - Set multiple rules.
rules=rules='allowlisted-email\@domain\.com' rules='from allowlisted-email2\@domain\.com' rules='to domain2\.com' - Set multiple rules.
rules=allowlisted-email\@domain\.com - Set a single rule.

An array of allowlist rules.

Note:

You can set multiple allowlist rules, duplicate or increment the parameter name. For example, rules-1, rules-2, and rules-3.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username BoxTrapper set_allowlist email='[email protected]' rules-1='allowlisted-email\@domain\.com' rules-2='from allowlisted-email2\@domain\.com' rules-3='to domain2\.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_allowlist",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add email address to BoxTrapper forwarders

This function adds a list of email addresses to which BoxTrapper forwards email messages.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

email required	string Example: [email protected] The account's email address. Warning: If you call this function in Webmail, the system ignores this parameter and uses the currently-authenticated email address.
forwarder required	Array of any <email> [ items <email > ] Example: [email protected] The email addresses to which to forward email messages.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  BoxTrapper \
  set_forwarders \
  email='[email protected]' \
  forwarder='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_forwarders",
"module": "BoxTrapper",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Webmail Applications

Email / Webmail Applications

Return available webmail clients

This function lists the account's available webmail clients.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

theme

string

Default: "the server's default theme"

Example: theme=jupiter

The webmail theme.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebmailApps \
  list_webmail_apps

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_webmail_apps",
"module": "WebmailApps",
"result": {"data": [{"displayname": "Roundcube",
"icon": "/webmail/jupiter/images/roundcube_logo.png",
"id": "roundcube",
"url": "/cpsess##########/3rdparty/roundcube/index.php"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Webmail Sessions

Email / Webmail Sessions

Create user session with existing session

This function creates a temporary user session.

Important:

Because this function requires a valid cPanel session ID, you must call it via a cPanel or Webmail session URL. If you call this function via the command line or Template Toolkit, it will not create a temporary user session. You must use the WHM API 1 create_user_session function to create a temporary user session.
Third-party plugins that require access to temporary MySQL users must call this function via the URL. It will create the temporary users before they are available. You can find these users in the $ENV{'REMOTE_DBOWNER'} environment variable.
If you cannot update your system, update your scripts to call the Cgi::phpmyadminlink function. This will create a temporary user session for you.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

URL
LiveAPI Perl
LiveAPI PHP

https://hostname.example.com:2083/cpsess##########/execute/Session/create_temp_user

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_temp_user",
"module": "Session",
"result": {"data": {"created": 1,
"session_temp_user": "cpses_reviY3ZSQK"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create Webmail session with credentials

This function creates a temporary session with a password for the calling cPanel user to connect to Webmail.

Note:

The cPanel user must own the Webmail account.
This function works like the UAPI Session::create_webmail_session_for_mail_user function with one exception. This function requires a correct password to create the Webmail session. If you use an incorrect password or attempt to connect to a suspended account, the login will fail.

How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

$URL_AUTHTY represents the value from the hostname return.
- If the hostname return value is null, enter the hostname of the server that answered the API function.
- $token represents the value from the token return.
$session represents the value of the session return.

For example, an HTTP POST may resemble the following:

https://hostname.example.com:2096/cpsess2462418786/login

With a message body of:

session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137

Authorizations:

BasicAuth

query Parameters

domain required	string Example: domain=example.com The domain for the Webmail account.
locale	string Example: locale=en The locale that the new session will use. Note: You must only enter lowercase characters. This parameter defaults to the cPanel user's locale.
login required	string Example: login=username The Webmail account's username.
password required	string Example: password=luggage12345 The password for the Webmail account.
remote_address	string <ipv4> Example: remote_address=192.168.0.1 The session's account's client IP address. Note: If you run this function from the command line, this parameter is required. This parameter defaults to the API caller's IP address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Session \
  create_webmail_session_for_mail_user_check_password \
  login='username' \
  domain='example.com' \
  password='luggage12345'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_webmail_session_for_mail_user_check_password",
"module": "Session",
"result": {"data": {"hostname": "hostname.example.com",
"session": "username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137",
"token": "/cpsess2462418786"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create Webmail session

Create a temporary session for a cPanel user to connect to Webmail.

Note:

The cPanel user must own the Webmail account.

How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

$URL_AUTHTY represents the value from the hostname return.
- If the hostname return value is null, enter the hostname of the server that answered the API function.
- $token represents the value from the token return.
$session represents the value of the session return.

For example, an HTTP POST may resemble the following:

https://hostname.example.com:2096/cpsess2462418786/login

With a message body of:

session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137

Authorizations:

BasicAuth

query Parameters

domain required	string Example: domain=example.com The domain for the Webmail account.
locale	string Example: locale=en The locale that the new session will use. Note: You must only enter lowercase characters. This parameter defaults to the cPanel user's locale.
login required	string Example: login=username The Webmail account's username.
remote_address	string <ipv4> Example: remote_address=192.168.0.1 The session's client IP address. Note: If you run this function from the command line, this parameter is required. This parameter defaults to the API caller's IP address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Session \
  create_webmail_session_for_mail_user \
  login='username' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_webmail_session_for_mail_user",
"module": "Session",
"result": {"data": {"hostname": "hostname.example.com",
"session": "username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137",
"token": "/cpsess2462418786"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create Webmail session for current user

Create a temporary session to connect to Webmail for the authenticated cPanel user.

How to use this API

After you successfully call this API, you will need to log in to Webmail. To do this, send an HTTP POST to https://$URL_AUTHTY:2096$token/login with a message body of session=$session where:

$URL_AUTHTY represents the value from the hostname return.
- If the hostname return value is null, enter the hostname of the server that answered the API function.
- $token represents the value from the token return.
$session represents the value of the session return.

For example, an HTTP POST may resemble the following:

https://hostname.example.com:2096/cpsess2462418786/login

With a message body of:

session=username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_MAIL_USER,728fb86a7df1cf20690c65f349ac3137

Authorizations:

BasicAuth

query Parameters

locale	string Example: locale=en The locale that the new session will use. Use UAPI `Locale::list_locales` to see a list of valid locales. Note: You must only enter lowercase characters. This parameter defaults to the cPanel user's locale.
remote_address	string <ipv4> Example: remote_address=192.168.0.1 The session's client IP address. Note: If you run this function from the command line, this parameter is required. This parameter defaults to the API caller's IP address.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Session \
  create_webmail_session_for_self

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_webmail_session_for_self",
"module": "Session",
"result": {"data": {"hostname": "hostname.example.com",
"session": "username:D7NiAZv1nf4bXeg9:CREATE_WEBMAIL_SESSION_FOR_SELF,728fb86a7df1cf20690c65f349ac3137",
"token": "/cpsess2462418786"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

FTP Accounts

Files / FTP Accounts

Create FTP account

This function creates an FTP account.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

disallowdot	integer Default: 1 Possible Values: 0 1 Example: disallowdot=1 Whether to strip dots (`.`) from the username. `1` — Strip dots. `0` — Do not strip dots.
domain	string <domain> Example: domain=example.com The FTP user's associated domain. This must be a domain that the cPanel account owns. Note: This parameter defaults to the cPanel account's primary domain.
homedir	string <path> Example: homedir=exampleftp The path to the FTP account's root directory, relative to the cPanel account's home directory. If you don't set this, it defaults to a directory with the same name as the FTP account.
pass	string Example: pass=123456luggage The new FTP account password. Note: You can use the `pass_hash` parameter in place of this parameter. However, you cannot use both the `pass` and `pass_hash` parameters in the same request.
pass_hash	string Default: "" Example: pass_hash=$6$1sOyHP5ZDYp3pGUz$R0TSgfPRHfDjT5PP5RJGv39FhiGTNNPvM7IFpCBjXijMmlMZk9yI8T3LqGuntc9fdKb5eX.lGL7wBS9e4DAWn/ The account's password hash. Note: You can use this parameter in place of the `pass` parameter. However, you cannot use both the `pass` and `pass_hash` parameters in the same request. You can find your server's password hash type in the `/etc/sysconfig/authconfig` file.
quota	integer >= 0 Default: 0 Example: quota=42 The FTP account's maximum disk usage quota, in megabytes (MB). Note: A value of `0` grants the FTP account unlimited disk space.
user required	string Example: user=username The new FTP account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  add_ftp \
  user='username2' \
  pass='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_ftp",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete FTP account

This function deletes an FTP account.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

destroy	integer Default: 0 Possible Values: 0 1 Example: destroy=1 Whether to delete the FTP account's home directory. `1` — Delete the home directory. `0` — Do not delete the home directory.
domain	string <domain> Example: domain=example.com The user's associated domain. Note: This parameter defaults to the cPanel account's primary domain.
user required	string Example: user=username The FTP account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  delete_ftp \
  user='username2'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_ftp",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether an FTP account exists

This function checks whether an FTP account exists.

Note:

This function returns only metadata if the FTP account exists, or an error if the FTP account does not exist.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The user's associated domain. Note: This parameter defaults to the cPanel account's primary domain.
user required	string Example: user=us_chickens The FTP account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  ftp_exists \
  user='us_chickens'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ftp_exists",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return FTP account's welcome message

This function retrieves the cPanel account's FTP welcome message.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  get_welcome_message

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_welcome_message",
"module": "Ftp",
"result": {"data": "Greetings, Professor Falken.",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return FTP account's quota

This function checks an FTP account's quota.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

account required	string Example: account=user1 The FTP account's username.
domain	string <domain> Example: domain=example.com The user's associated domain. Note: This parameter defaults to the cPanel account's primary domain.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  get_quota \
  account='user1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_quota",
"module": "Ftp",
"result": {"data": "unlimited",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return FTP accounts

This function lists FTP account information.

Important:

When you disable the FTP role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:

BasicAuth

query Parameters

include_acct_types	string Example: include_acct_types=main\|anonymous A list of the FTP account types to include in the function's results. `anonymous` `logaccess` `main` `sub` If you do not specify this parameter, this function returns all FTP account types. Note: Separate multiple types with the pipe character (`\|`). In browser-based calls, use `%7C`.
skip_acct_types	string Example: skip_acct_types=main\|anonymous A list of the FTP account types to exclude from the function's results. `anonymous` `logaccess` `main` `sub` If you do not specify this parameter, this function does not exclude any account types. Note: Separate multiple types with the pipe character (`\|`). In browser-based calls, use `%7C`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  list_ftp

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_ftp",
"module": "Ftp",
"result": {"data": [{"homedir": "/home/user/public_html/ftp/",
"type": "main",
"user": "ftpaccount"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return FTP accounts and disk usage

This function lists FTP account and disk usage information.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

include_acct_types	string Example: include_acct_types=main\|anonymous A pipe-delimited list of the FTP account types to include in the function's results. If you do not specify this parameter, the function returns all FTP account types. Valid types for this list are: `anonymous` `logaccess` `main` `sub`
skip_acct_types	string Example: skip_acct_types=main\|anonymous A pipe-delimited list of the FTP account types to exclude from the function's results. If you do not specify this parameter, the function does not exclude any account types. Valid types for this list are: `anonymous` `logaccess` `main` `sub`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  list_ftp_with_disk

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_ftp_with_disk",
"module": "Ftp",
"result": {"data": [{"_diskquota": "476.84",
"_diskused": "2.34",
"accttype": "sub",
"deleteable": 1,
"dir": "/home/user/public_ftp",
"diskquota": "476.84",
"diskused": "2.34",
"diskusedpercent": 21,
"diskusedpercent20": 20,
"htmldir": null,
"humandiskquota": "477 MB",
"humandiskused": "2 MB",
"login": "ftpaccount",
"reldir": "public_ftp",
"serverlogin": "[email protected]"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update FTP account's password

This function changes an FTP account's password.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string Example: domain=example.com The user's associated domain. Note: This parameter defaults to the cPanel account's primary domain
pass required	string Example: pass=12345luggage The FTP account's new password.
user required	string Example: user=ftpaccount The FTP account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  passwd \
  user='ftpaccount' \
  pass='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "passwd",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update FTP account's home directory

This function changes the home directory for FTP accounts.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The user's associated domain. Note: The default value is the cPanel account's primary domain.
homedir	string <path> Default: "user@domain/" Example: homedir=example1/ The FTP account's home directory Note: This parameter defaults to the `user@domain` subdirectory in the cPanel account's home directory with the name, where user and domain represent the `user` and `domain` parameters.
user required	string Example: user=example1 The FTP account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  set_homedir \
  user='example1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_homedir",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update FTP welcome message

This function sets the FTP welcome message.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

message

required

string

Example: message=Greetings, Professor Falken.

The cPanel account's new FTP welcome message.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  set_welcome_message \
  message='Greetings, Professor Falken.'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_welcome_message",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update FTP account's quota

This function changes an FTP account's quota.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The user's associated domain. Note: The default value is the cPanel account's primary domain.
kill	integer Default: 0 Possible Values: 0 1 Example: kill=0 Whether to disable quotas for the FTP account. `1` - Disable quotas. `0` - Enable quotas. Note: If you disable quotas for an FTP account, you grant that account unlimited disk space.
quota	integer >= 0 Default: 0 Example: quota=500 The new quota, in megabytes. Note: Setting this parameter to `0` grants the account unlimited disk space.
user required	string Example: user=ftpaccount The FTP account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  set_quota \
  user='ftpaccount'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_quota",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

FTP Server Settings

Files / FTP Server Settings

Return if anonymous FTP transfers allowed

This function checks whether the account allows inbound anonymous FTP transfers.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  allows_anonymous_ftp_incoming

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "allows_anonymous_ftp_incoming",
"module": "Ftp",
"result": {"data": {"allows": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return if anonymous FTP connections allowed

This function checks whether the account allows anonymous FTP connections.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  allows_anonymous_ftp

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "allows_anonymous_ftp",
"module": "Ftp",
"result": {"data": {"allows": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return FTP server's information

This function retrieves the extended information about the server's FTP daemon.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  get_ftp_daemon_info

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_ftp_daemon_info",
"module": "Ftp",
"result": {"data": {"enabled": 1,
"name": "pure-ftpd",
"supports": {"login_without_domain": 0,
"quota": 1
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return FTP server's port

This function returns the FTP port.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  get_port

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_port",
"module": "Ftp",
"result": {"data": {"port": 21
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Stop FTP session

This function kills FTP sessions.

Important:

When you disable the FTP Role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

login

string

Default: "all"

Example: login=weeones

The username for the session's FTP account.

Note:

To stop all FTP sessions for the cPanel account, set this parameter to the all value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  kill_session

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "kill_session",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether server uses ProFTPD or Pure-FTPd

This function checks whether the server uses ProFTPD or Pure-FTPd.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  server_name

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "server_name",
"module": "Ftp",
"result": {"data": "pure-ftpd",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return FTP server's active sessions

This function lists the FTP server's active sessions.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  list_sessions

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_sessions",
"module": "Ftp",
"result": {"data": [{"cmdline": "pure-ftpd (IDLE)",
"file": "",
"host": "localhost",
"login": "Tue Apr 23 16:23:23 2020",
"pid": 6735,
"status": "IDLE",
"user": "ftpaccount"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable or disable anonymous FTP logins

This function enables or disables anonymous FTP logins.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

set	integer Default: 0 Possible Values: 0 1 Example: set=0 Whether to enable or disable anonymous FTP logins. `1` - Enable. `0` - Disable.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  set_anonymous_ftp

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_anonymous_ftp",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable or disable anonymous incoming FTP transfers

This function enables or disables inbound anonymous FTP transfers.

Important:

When you disable the FTP role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

set	integer Default: 0 Possible Values: 0 1 Example: set=0 Whether to enable or disable inbound anonymous FTP transfers. `1` - Enable. `0` - Disable.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Ftp \
  set_anonymous_ftp_incoming

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_anonymous_ftp_incoming",
"module": "Ftp",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Image Tools

Files / Image Tools

Create image thumbnails

This function creates thumbnails from images. The function saves the new thumbnail images in a thumbnails subdirectory inside the original directory. The system prepends thumbnail filenames with tn_ (for example, tn_picture.jpg).

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

dir required	string Example: dir=images The path to the directory where the image resides. When you pass this parameter, the function creates a thumbnail directory directly below the image directory. NOTE: This parameter can use an absolute directory path or a path relative to the user's home directory.
height_percentage required	integer [ 1 .. 99 ] Example: height_percentage=25 The percentage by which to reduce the thumbnails' height.
width_percentage required	integer [ 1 .. 99 ] Example: width_percentage=25 The percentage by which to reduce the thumbnails' width.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ImageManager \
  create_thumbnails \
  dir='images' \
  width_percentage='25' \
  height_percentage='25'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_thumbnails",
"module": "ImageManager",
"result": {"data": [{"failed": 1,
"file": "/home/cptest1/public_html/images/610_290.jpg",
"reason": "too many pixels",
"thumbnail_file": "/home/cptest1/public_html/images/thumbnails/tn_610_290.jpg"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Save resized image

This function resizes a specified image.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

height required	integer >= 1 Example: height=300 The height to which to set the image size.
image_file required	string Example: image_file=/images/image.jpg The name of the file to scale. Note: Use the absolute filepath or a filepath relative to the user's home directory.
save_original_as	string Example: save_original_as=images/original.jpg The path to the directory in which to save a copy the original image file. Note: If you don't pass this parameter, the function doesn't save a copy of the original image. Use the absolute filepath or a filepath relative to the user's home directory.
width required	integer >= 1 Example: width=200 The width to which to set the image size.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ImageManager \
  resize_image \
  image_file='images/image.jpg' \
  width='200' \
  height='300'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "resize_image",
"module": "ImageManager",
"result": {"data": "/home/cptest1/images/myimage.jpg",
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return image dimensions

This function returns the dimensions of the image file that you specify.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

image_file

required

string

Example: image_file=image/myimage.jpg

The path to the file to measure.

Note:

Use the absolute filepath or a path relative to the user's home directory.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ImageManager \
  get_dimensions \
  image_file='image/myimage.jpg'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_dimensions",
"module": "ImageManager",
"result": {"data": {"height": 300,
"width": 261
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create image with new format

This function converts an image to a new file format.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

image_file required	string Example: image_file=images/myimage.jpg The image file to convert, relative to the cPanel account's `/home` directory.
type required	string Example: type=png The format to which to convert the images.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ImageManager \
  convert_file \
  image_file='images/myimage.jpg' \
  type='png'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "convert_file",
"module": "ImageManager",
"result": {"data": {"converted_file": "/home/cptest1/images/myimage.png"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Manage Files

Files / Manage Files

Delete .trash folder content

This function purges content from the .trash folder in the user's home directory.

Important:

When you disable the FileStorage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

older_than

integer >= 0

Default: 0

Example: older_than=31

The maximum age in days of content that the function will not purge.

Note:

A value of 0 will purge everything from the user's .trash folder.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  empty_trash

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "empty_trash",
"module": "Fileman",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return autocomplete file and directory names

This function returns any files and directories that begin with a specified string.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

dirsonly	integer Default: 0 Possible Values: 1 0 Whether to include only directories in the output. `1` — Only include directories. `0` — Include directories and files.
html	integer Default: 1 Possible Values: 0 1 Example: html=1 Whether to return HTML-encoded results. `1` — Return HTML-encoded output. `0` — Return plaintext output.
list_all	integer Default: 1 Possible Values: 1 0 Whether to return all files and directories inside the specified directory. If you set this parameter's value to `1`, you must set the `path` parameter's value to a full directory path. `1` — Return all files and directories inside the specified directory. `0` — Return partial file and directory name matches.
path required	string Example: path=public The prefix of the paths to complete.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  autocompletedir \
  path='public'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "autocompletedir",
"module": "Fileman",
"result": {"data": [{"file": "public_ftp"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return file content

This function retrieves a file's content.

Important:

When you disable the File Storage role, the system disables this function.

Note:

JSON strings must be valid UTF-8. To retrieve a non-UTF-8 file via JSON, we recommend that you give ISO-8859-1 as from_charset and UTF-8 as to_charset, then decode the return payload’s content as UTF-8.

Authorizations:

BasicAuth

query Parameters

dir required	string <path> Example: dir=/home/user/public.html The file path to the directory that contains the selected file.
file required	string Example: file=example.html The file to retrieve.
from_charset	string Default: "_DETECT_" Example: from_charset=_DETECT_ The file’s character encoding. This parameter defaults to `_DETECT_`, which indicates a request to detect the file’s character encoding.
to_charset	string Default: "_LOCALE_" Example: to_charset=_LOCALE_ The output character encoding. This parameter defaults to `_LOCALE_`, which indicates a request to use the session locale’s character encoding. Important: Contexts that serialize the API response as JSON require this value to be `utf-8` or `US-ASCII`. Behavior is undefined if the request indicates any other encoding.
update_html_document_encoding	integer Default: 1 Possible Values: 0 1 Example: update_html_document_encoding=1 Whether to update the file's HTML document encoding. `1` — Update the file's HTML document encoding. `0` — Don't update the file's HTML encoding.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  get_file_content \
  dir='/home/user/public_html' \
  file='example.html'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_file_content",
"module": "Fileman",
"result": {"data": {"content": "`hi`",
"dir": "/home/user/public_html",
"filename": "example.html",
"from_char": "UTF-8",
"from_charset": null,
"path": "/home/user/public_html/example.html",
"to_char": "UTF-8",
"to_charset": null
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return file or directory information

This function returns the information for a specified file or directory.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

check_for_leaf_directories	integer Default: 0 Possible Values: 0 1 Example: check_for_leaf_directories=1 Whether to flag directories that contain subdirectories. `1` - Flag directories that contain subdirectories. `0` - Do not flag directories that contain subdirectories.
include_hash	integer Default: 0 Possible Values: 0 1 Example: include_hash=0 Whether to return a hash of the file's information. `1` - Return a hash of the file's information. `0` - Do not return a hash of the file's information.
include_mime	integer Default: 0 Possible Values: 0 1 Example: include_mime=1 Whether to return the file's MIME type. `1` - Return the file's MIME type. `0` - Do not return the file's MIME type.
include_permissions	integer Default: 0 Possible Values: 0 1 Example: include_permissions=1 Whether to parse the file owner's read and write permissions. `1` - Parse the file owner's read and write permissions. `0` - Do not parse the file owner's read and write permissions.
path required	string <path> Example: path=public_html The directory from which to list files.
show_hidden	integer Default: 0 Possible Values: 0 1 Example: show_hidden=1 Whether to include hidden files in the output. `1` - Include hidden files. `0` - Do not include hidden files.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  get_file_information \
  path='public_html'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_file_information",
"module": "Fileman",
"result": {"data": {"absdir": "/home/user",
"ctime": 1400573272,
"exists": 1,
"file": "cgi-bin",
"fullpath": "/home/user/public_html/cgi-bin",
"gid": 503,
"hash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
"humansize": "5 KB",
"isleaf": 1,
"mimename": "publichtml",
"mimetype": "text/plain",
"mode": "16872",
"mtime": 1400573272,
"nicemode": 755,
"path": "/home/user/public.html",
"phash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
"rawmimename": "text/plain",
"rawmimetype": "text/plain",
"read": 1,
"size": 4096,
"type": "file",
"uid": 502,
"write": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return directory content

This function returns a sorted list of files and directories.

Important:

When you disable the FileStorage role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:

BasicAuth

query Parameters

check_for_leaf_directories	integer Default: 0 Possible Values: 0 1 Example: check_for_leaf_directories=1 Whether to return directories that contain subdirectories. `1` — Return subdirectories. `0` — Do not retain subdirectories.
dir required	string Example: dir=public_html The directory from which to list files.
include_hash	integer Default: 0 Possible Values: 0 1 Example: include_hash=0 Whether to include a hash of the file's information in the return. `1` — Generate a hash. `0` — Do not generate a hash.
include_mime	integer Default: 0 Possible Values: 0 1 Example: include_mime=1 Whether to return the file's MIME type. `1` — Include MIME type. `0` — Do not include MIME type. Note: If you set this value to `0` but also include the `mime_types` or `raw_mime_types` parameters, the function overrides your specified value and sets this parameter to `1`.
include_permissions	integer Default: 0 Possible Values: 0 1 Example: include_permissions=0 Whether to parse the file owner's read and write permissions. `1` — Parse file permissions. `0` — Do not parse file permissions.
limit_to_list	integer Possible Values: 0 1 Example: limit_to_list=0 Whether to return only entries that begin with the `filepath-` prefix. `1` — Return only files that begin with the `filepath-` prefix. `0` — Return all files. If you do not use this parameter, the function returns all filenames.
mime_types	string Example: mime_types=text-plain The MIME types to return. If you use this parameter, the function returns the specified MIME types and sets the `include_mime` parameter's value to `1`. If you do not use this parameter, the function returns all MIME types.
only_these_files	string Example: only_these_files=cpbackup-exclude.conf A comma-separated list of files to return. If you do not use this parameter, the function returns all files.
raw_mime_types	string Example: raw_mime_types=text/plain The raw MIME types to return. If you use this parameter, the function returns the specified MIME types and sets the `include_mime` parameter's value to `1`. If you do not use this parameter, the function returns all MIME types.
show_hidden	integer Default: 0 Possible Values: 0 1 Example: show_hidden=1 Whether to include hidden files in the output. `1` — Include hidden files. `0` — Do not include hidden files.
types	Array of strings Example: types=file\|dir A pipe-separated list of file types to return. `file` — A file. `dir` — A directory. `char` — A character special device. `block` — A block special device. `fifo` — A named pipe (FIFO). `link` — A symbolic link. `socket` — A Unix domain socket. If you do not use this parameter, the function returns all file types.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  list_files \
  dir='public_html'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_files",
"module": "Fileman",
"result": {"data": {"dirs": [{"absdir": "/home/user",
"ctime": 1400573272,
"exists": 1,
"file": "cgi-bin",
"fullpath": "/home/user/public_html/cgi-bin",
"gid": 503,
"hash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
"humansize": "5 KB",
"isleaf": 1,
"isparent": 1,
"mimename": "text-plain",
"mimetype": "text/plain",
"mode": "16877",
"mtime": 1400573272,
"nicemode": 755,
"path": "/home/user/public.html",
"phash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
"rawmimename": "text-plain",
"rawmimetype": "text/plain",
"read": 1,
"size": 4096,
"type": "file",
"uid": 502,
"write": 1
}
],
"files": [{"absdir": "/home/user",
"ctime": 1400573272,
"exists": 1,
"file": "cgi-bin",
"fullpath": "/home/user/public_html/cgi-bin",
"gid": 503,
"hash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
"humansize": "5 KB",
"isleaf": 1,
"isparent": 1,
"mimename": "text-plain",
"mimetype": "text/plain",
"mode": "16877",
"mtime": 1400573272,
"nicemode": 755,
"path": "/home/user/public.html",
"phash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
"rawmimename": "text-plain",
"rawmimetype": "text/plain",
"read": 1,
"size": 4096,
"type": "file",
"uid": 502,
"write": 1
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update buffer encoding

This function converts a buffer from one encoding language to another.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

content required	string Example: content=hi The file's contents.
discard_illegal	integer Possible Values: 0 1 Example: discard_illegal=1 Whether to discard any characters that do not transcode correctly. `1` - Discard invalid characters. `0` - Transcode invalid characters in the default character set encoding.
from_charset	string Example: from_charset=UTF-8 The file's current character set encoding.
to_charset	string Example: to_charset=ASCII The character set encoding in which to encode the file.
transliterate	integer Possible Values: 0 1 Example: transliterate=0 Whether to transcode invalid characters to valid characters in the new character set encoding. `1` - Transcode invalid characters in the new character set encoding. `0` - Return an error message.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  transcode \
  content='hi'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "transcode",
"module": "Fileman",
"result": {"data": {"charset": "ASCII",
"content": "hi"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Save file

This function saves a file in a directory and encodes it in a character set.

Important:

When you disable the File Storage role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

content	string Example: content=hi The new file's contents. If you do not use this parameter, the function creates a blank file.
dir	string <path> Example: dir=/home/username/public_html The directory that contains the selected file. Note: This parameter defaults to the currently-authenticated user's `/home` directory.
fallback	integer Default: 1 Possible Values: 0 1 Example: fallback=0 Whether the function will return an error or save in the default character set if it cannot save in the specified character set. `1` — Save in the default character set. `0` — Return an error.
file required	string Example: file=example.html The files to retrieve.
from_charset	string Default: "UTF-8" Example: from_charset=UTF-8 The character set encoding of the `content` parameter's value.
to_charset	string Default: "UTF-8" Example: to_charset=ASCII The character set encoding in which to encode the file.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  save_file_content \
  file='example.html'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "save_file_content",
"module": "Fileman",
"result": {"data": {"from_charset": "UTF-8",
"path": "/home/user/public_html/example.html",
"to_charset": "ASCII"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Upload files

This function uploads files.

Note:

For more information about how to use this function in your custom code, read our Use UAPI's Fileman::upload_files Function in Custom Code tutorial.

Important:

When you disable the File Storage role, the system disables this function.

You cannot call this function through WHM API 1's uapi_cpanel function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

To implement Fileman::upload_files, read our Use UAPI's `Fileman::upload_files` Function in Custom Code tutorial.

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "upload_files",
"module": "Fileman",
"result": {"data": {"content": "",
"filename": "example.png"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

WebDisk Settings

Files / WebDisk Settings

Update Web Disk home directory location

This function changes the home directory for a Web Disk account.

Important:

When you disable the Web Disk role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

homedir required	string <path> Example: homedir=example1/ The Web Disk account's home directory.
private	integer Default: 0 Possible Values: 0 1 Example: private=0 Whether to set the Web Disk directory's permissions to public or private. `1` - Private (`0700`) `0` - Public (`0755`)
user required	string <email> Example: [email protected] The Web Disk account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebDisk \
  set_homedir \
  user='[email protected]' \
  homedir='example1/'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_homedir",
"module": "WebDisk",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete Web Disk account

This function deletes a Web Disk account.

Important:

When you disable the Web Disk role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

destroy required	integer Possible Values: 0 1 Example: destroy=1 Whether to recursively delete the Web Disk account's folder and all of its contents. `1` - Delete the folder for the Web Disk account `0` - Do not delete the folder for the Web Disk account.
user required	string <email> Example: [email protected] The Web Disk account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebDisk \
  delete_user \
  user='[email protected]' \
  destroy='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_user",
"module": "WebDisk",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update Web Disk account password

This function changes the Web Disk account's password.

Important:

When you disable the Web Disk role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

enabledigest	integer Default: 0 Possible Values: 0 1 Example: enabledigest=0 Whether to enable Digest Authentication. `1` - Enable Digest Authentication. `0` - Disable Digest Authentication.
password required	string Example: password=123456luggage The Web Disk account's password.
user required	string <email> Example: [email protected] The Web Disk account username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebDisk \
  set_password \
  user='[email protected]' \
  password='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_password",
"module": "WebDisk",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update Web Disk home directory permissions

This function changes the Web Disk home directory's permissions.

Important:

When you disable the Web Disk role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

perms required	string Possible Values: "ro" "rw" Example: perms=rw The Web Disk account's home directory file permissions. `ro` — Read-only permissions. `rw` — Read and write permissions.
user required	string <email> Example: [email protected] The Web Disk account's username.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WebDisk \
  set_permissions \
  user='[email protected]' \
  perms='rw'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_permissions",
"module": "WebDisk",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Deployment Settings

GIT Management / Deployment Settings

Create Git deployment task

This function deploys the changes from a cPanel-managed repository.

Important:

The system logs messages for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the time in Unix epoch time. The system pulls changes with the --ff-only option and will only succeed if the branch's HEAD commit is up-to-date or Git can fast forward it. For more information about our suggested deployment configuration and how users can set it up, read our Guide to Git™ - Deployment documentation. Before deployment, repositories must meet the following requirements:

A valid checked-in .cpanel.yml file in the top-level directory.
One or more local or remote branches.
A clean working tree.

If a repository does not meet these requirements, the system will not display deployment information. Also, it will disable deployment functionality. For more information, read our Guide to Git™ - Deployment documentation.

Authorizations:

BasicAuth

query Parameters

repository_root

required

string <path>

Example: repository_root=/home/user/public_html/example

The repository's directory.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControlDeployment \
  create \
  repository_root='/home/user/public_html/example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "VersionControlDeployment",
"result": {"data": {"deploy_id": "12",
"log_path": "/home/user/.cpanel/logs/vc_1525289545.785367_git_deploy.log",
"repository_root": "/home/username/example",
"sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"task_id": "00000000/5a9ec8dd4c345d",
"timestamps": {"queued": "1525289545.16293"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete Git deployment task

This function deletes a deployment task. For more information, read our Guide to Git - Deployment documentation.

Authorizations:

BasicAuth

query Parameters

deploy_id

required

string

Example: deploy_id=13

The Task Queue system's task ID number.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControlDeployment \
  delete \
  deploy_id='13'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete",
"module": "VersionControlDeployment",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return Git deployment task status

This function retrieves the status of deployment tasks. Before deployment, repositories must meet the following requirements:

A valid checked-in .cpanel.yml file in the top-level directory.
One or more local or remote branches.
A clean working tree.

If a repository does not meet these requirements, the system will not display deployment information. Also, it will disable deployment functionality. For more information, read our Guide to Git™ - Deployment documentation.

Important:

The system logs messages for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the time in Unix epoch time.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControlDeployment \
  retrieve

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "retrieve",
"module": "VersionControlDeployment",
"result": {"data": [{"deploy_id": 13,
"log_path": "/home/user/.cpanel/logs/vc_1525289448.759720_git_deploy.log",
"repository_root": "/home/username/example",
"repository_state": {"author": "Jane Doe <[email protected]>",
"branch": "master",
"date": 1410277881,
"identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
"message": "This is a commit."
},
"sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"task_id": "00000000/5aea11e886a5d8",
"timestamps": {"active": "1525289448.83553",
"canceled": "1525289448.83553",
"failed": "1525289448.83553",
"queued": "1525289448.83553",
"succeeded": "1525289448.83553"
}
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Repository Management

GIT Management / Repository Management

Create Git repository

This function creates a new Git™ repository on a cPanel account.

For more information about support for version control in cPanel & WHM, read our Git Version Control and Guide to Git documentation.
For a list of configuration changes, repository restrictions, and troubleshooting steps, read our Guide to Git - For System Administrators documentation.

Important:

The system logs errors for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_create.log file, where TIMESTAMP represents the time of the error in Unix epoch time.

Authorizations:

BasicAuth

query Parameters

name required	string Example: name=example The new repository's display name.
repository_root required	string <path> Example: repository_root=/home/user/public_html/example The absolute path to the directory in which to store the repository, relative to the user's `home` directory. Note: If the directory does not exist, the system will create it. If the specified directory already contains a repository, the system will automatically add it to the list of cPanel-managed repositories. This feature enforces several restrictions on repository paths. For more information, read our Guide to Git - For System Administrators documentation.
	object Example: source_repository={"remote_name":"origin","url":"ssh://clone.domain.com/cloneme"} A JSON-formatted object containing information about the source repository that the system will clone. Note: If you do not include source repository data, the function creates an empty repository.
type required	string Value: "git" Example: type=git The repository type. `git` — A Git repository. Note: `git` is the only possible value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControl \
  create \
  type='git' \
  name='example' \
  repository_root='/home/user/public_html/example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "VersionControl",
"result": {"data": {"available_branches": ["master",
"olive"
],
"branch": "master",
"clone_urls": {"read_only": ["https://[email protected]/home/user/example"
],
"read_write": ["ssh://[email protected]/home/user/example"
]
},
"last_update": null,
"name": "example",
"repository_root": "/home/user/public_html/example",
"source_repository": {"remote_name": "remote",
"url": "http://[email protected]/home/user/domain"
},
"tasks": [{"action": "create",
"args": {"log_file": "/home/username/.cpanel/logs/vc_1234567890.123456_git_deploy.log",
"repository_root": "/home/user/example"
},
"id": "00000000/5a9ec8dd4c345d",
"sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"subsystem": "VersionControl"
}
],
"type": "git"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete Git repository

This function deletes a cPanel account's Git™ repository. For more information about support for version control in cPanel & WHM, read our Git Version Control and Guide to Git documentation.

Warning:

When you call this function, the system permanently deletes the entire contents of the specified directory. You cannot recover this data after deletion.
You cannot use this function to delete any repositories that do not appear in the cache of repositories (for example, repositories that contain invalid characters or exist within cPanel-controlled directories).

Authorizations:

BasicAuth

query Parameters

repository_root

required

string

Example: repository_root=/home/user/example

The absolute directory path in the user's home directory containing the repository to delete.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControl \
  delete \
  repository_root='/home/user/example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete",
"module": "VersionControl",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update Git repository settings

This function modifies a Git™ repository's basic settings. For more information about support for version control in cPanel & WHM, read our Git Version Control and Guide to Git documentation.

Note:

This function only pulls changes from the remote repository if you specify a branch value.
You cannot modify the type, repository_root, or url values for existing repositories.
You must include the repository_root parameter in order to identify the repository to update.
All other input parameters are optional. Use them to assign the new values to the account. If you do not include a parameter or specify its existing value, no change will occur.

Authorizations:

BasicAuth

query Parameters

branch	string Example: branch=master The new branch to use. If you do not specify a value, the function does not update this parameter. Remember: This function only pulls changes from the remote repository if you specify this value.
name	string Example: name=example The repository's new display name. If you do not specify a value, the function does not update this parameter.
repository_root required	string <path> Example: repository_root=/home/user/public_html/example The absolute directory path that contains the repository to update.
	object Example: source_repository={"remote_name":"origin"} A JSON-encoded object containing information about the source repository. If you do not specify a value, the function does not update this parameter. Important: You cannot modify the source repository's URL. You must JSON-encode the contents of this object.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControl \
  update \
  repository_root='/home/user/public_html/example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update",
"module": "VersionControl",
"result": {"data": {"available_branches": ["master"
],
"branch": "master",
"clone_urls": {"read_only": ["https://[email protected]/home/user/example"
],
"read_write": ["ssh://[email protected]/home/user/example"
]
},
"deployable": 1,
"last_deployment": {"deployment_date": 1569844800,
"repository_state": {"author": "User Name <[email protected]>",
"date": 1569844800,
"identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb121",
"message": "I'm committing some particularly cromulent code."
}
},
"last_update": {"author": "Jane Doe <[email protected]>",
"date": 1569844800,
"identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
"message": "I'm committing some particularly cromulent code."
},
"name": "example",
"repository_root": "/home/user/example",
"tasks": [{"action": "create",
"args": {"repository_root": "/home/user/example"
},
"id": "00000000/5a9ec8dd4c345d",
"subsystem": "VersionControl"
}
],
"type": "git"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return Git repositories

This function lists Git™ repositories on a cPanel account. For more information about support for version control in cPanel & WHM, read our Git Version Control and Guide to Git documentation.

Important:

This feature does not allow the following characters in repository paths: \ * | " ' < > & @ ` $ { } [ ] ( ) ; ? : = % #
This function does not allow repositories that exist in the following cPanel-controlled directories:
- .cpanel
- .htpasswds
- .ssh
- .trash
- access-logs
- cgi-bin
- etc
- logs
- perl5
- mail
- spamassassin
- ssl
- tmp
- var

Users can create repositories in some of these directories on the command line. They may appear in the list of repositories in Gitweb, but users may see an error message if they try to access them.

Authorizations:

BasicAuth

query Parameters

fields

string

Default: "*"

Example: fields=name,type,branch,last_update

A comma-separated list of desired return values.

Note:

Use a wildcard (*) to list all possible return values.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  VersionControl \
  retrieve

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "retrieve",
"module": "VersionControl",
"result": {"data": [{"available_branches": ["master"
],
"branch": "master",
"clone_urls": {"read_only": ["https://[email protected]/home/user/example"
],
"read_write": ["ssh://[email protected]/home/user/example"
]
},
"deployable": 1,
"last_deployment": {"deployment_date": 1598774400,
"repository_state": {"author": "User Name <[email protected]>",
"date": 1598774400,
"identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
"message": "I'm committing some particularly cromulent code."
}
},
"last_update": {"author": "Jane Doe <[email protected]>",
"date": 1598774400,
"identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
"message": "I'm committing some particularly cromulent code."
},
"name": "example",
"repository_root": "/home/user/example",
"tasks": [{"action": "create",
"args": {"log_file": "/home/user/.cpanel/logs/vc_1526305129.123456_git_create.log",
"repository_root": "/home/user/example"
},
"id": "00000000/5a9ec8dd4c345d",
"sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"subsystem": "VersionControl"
}
],
"type": "git"
},
{"available_branches": ["master"
],
"branch": "master",
"deployable": 1,
"last_update": {"author": "June Due <[email protected]>",
"clone_urls": {"read_only": ["https://[email protected]/home/user/example"
],
"read_write": ["ssh://[email protected]/home/user/example"
]
},
"date": 1599730200,
"identifier": "4ee0b73ddf78213c41fcc185acfab68ced99046d",
"last_deployment": {"deployment_date": 1599730200,
"repository_state": {"author": "User Name <[email protected]>",
"date": 1599730200,
"identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
"message": "I'm committing some particularly cromulent code."
}
},
"message": "My code makes more sense, actually.",
"tasks": [{"action": "create",
"args": {"log_file": "/home/user/.cpanel/logs/vc_1526305129.123456_git_create.log",
"repository_root": "/home/user/example"
},
"id": "00000000/5a9ec8dd4c345d",
"sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"subsystem": "VersionControl"
}
]
},
"name": "example2",
"repository_root": "/home/user/example2",
"type": "git"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

InProductSurvey

The InProductSurvey module for cPanel UAPI.

Return in-product survey banner data

This function returns whether the in-product survey banner should display for the current user and the survey link.

Notes:

The function selects a link template based on whether the authenticated user is a webmail user or a cPanel/Team user.
A display value of 0 means you should not render the banner UI.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
--user=username \
InProductSurvey \
get_in_product_survey_url

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_in_product_survey_url",
"module": "InProductSurvey",
"result": {"data": {"display": "1",
"link": "https://survey.example.tld/some/generated/link",
"max_dismiss": "3",
"new_user": "0",
"submit_event": "survey_submitted",
"server_type": "cpanel",
"user_type": "cpanel"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Database Information

MySQL and MariaDB / Database Information

Return MySQL server host information and version

This function returns information about the account's MySQL® host.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  get_server_information

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_server_information",
"module": "Mysql",
"result": {"data": {"host": "192.0.2.1",
"is_remote": 1,
"version": "5.6.23"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return MySQL server host information

This function returns information about the account's MySQL® host.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  locate_server

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "locate_server",
"module": "Mysql",
"result": {"data": {"is_remote": 1,
"remote_host": "192.0.2.1"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Database Management

MySQL and MariaDB / Database Management

Update MySQL® privileges

This function updates privileges for all MySQL® databases and users on an account.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  update_privileges

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update_privileges",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate MySQL database integrity

This function checks for errors in all of the tables in a MySQL® database.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=example_test

The database's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  check_database \
  name='example_test'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_database",
"module": "Mysql",
"result": {"data": [{"msg_text": "OK",
"msg_type": "status",
"table": "table1"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete MySQL database

This function deletes a MySQL® database.

Important:

when you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=example

The database's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  delete_database \
  name='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_database",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create MySQL database

This function creates a MySQL® database.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name required	string Example: name=newdb The new database's name.
prefix-size	integer Default: 16 Possible Values: 8 16 Example: prefix-size=16 The desired prefix size.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  create_database \
  name='newdb'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_database",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return MySQL database schema

This function returns a string that you can give to MySQL® to recreate a particular database’s schema.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

dbname

required

string

Example: dbname=username_example_db

The database's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  dump_database_schema \
  dbname='username_example_db'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "dump_database_schema",
"module": "Mysql",
"result": {"data": "-- MySQL dump 10.13  Distrib 5.7.26, for Linux (x86_64)\n--\n-- Host: localhost    Database:username_example_db\n-- ------------------------------------------------------\n-- Serverversion\t5.7.26\n\n/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT*/;\n/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;\n/*!40101 SET@OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;\n/*!40101 SET NAMES utf8mb4*/;\n/*!40103 SET @OLD_TIME_ZONE=@@TIME_ZONE */;\n/*!40103 SET TIME_ZONE='+00:00'*/;\n/*!40014 SET @OLD_UNIQUE_CHECKS=@@UNIQUE_CHECKS, UNIQUE_CHECKS=0 */;\n/*!40014 SET@OLD_FOREIGN_KEY_CHECKS=@@FOREIGN_KEY_CHECKS, FOREIGN_KEY_CHECKS=0 */;\n/*!40101 SET@OLD_SQL_MODE=@@SQL_MODE, SQL_MODE='NO_AUTO_VALUE_ON_ZERO' */;\n/*!40111 SE@OLD_SQL_NOTES=@@SQL_NOTES, SQL_NOTES=0 */;\n\n--\n-- Current Database:`username_example_db`\n--\n\nCREATE DATABASE /*!32312 IF NOT EXISTS*/ `username_example_d/*!40100 DEFAULT CHARACTER SET latin1 */;\n\nUSE `username_example_db`;\n/*!40103 SETTIME_ZONE=@OLD_TIME_ZONE */;\n\n/*!40101 SET SQL_MODE=@OLD_SQL_MODE */;\n/*!40014 SETFOREIGN_KEY_CHECKS=@OLD_FOREIGN_KEY_CHECKS */;\n/*!40014 SET UNIQUE_CHECKS=@OLD_UNIQUE_CHECKS*/;\n/*!40101 SET CHARACTER_SET_CLIENT=@OLD_CHARACTER_SET_CLIENT */;\n/*!40101 SETCHARACTER_SET_RESULTS=@OLD_CHARACTER_SET_RESULTS */;\n/*!40101 SETCOLLATION_CONNECTION=@OLD_COLLATION_CONNECTION */;\n/*!40111 SET SQL_NOTES=@OLD_SQL_NOTES*/;\n\n-- Dump completed on 2019-06-06  9:44:04\n",
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return MySQL databases

This function lists an account's MySQL® databases.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  list_databases

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_databases",
"module": "Mysql",
"result": {"data": [{"database": "user_db",
"disk_usage": 673,
"users": ["db_user",
"db2_user"
]
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update MySQL database name

This function renames a MySQL® database.

MySQL does not allow you to rename a database. When cPanel & WHM "renames" a database, the system performs the following steps:

The system creates a new database.
The system moves data from the old database to the new database.
The system recreates grants and stored code in the new database.
The system deletes the old database and its grants.

Warning:

It is potentially dangerous to rename a MySQL database. We strongly recommend that you perform a backup of the database before you attempt to rename it.
If any of the first three steps fail, the system returns an error and attempts to restore the database's original state. If the restoration process fails, the API function's error response describes these additional failures.
In rare cases, the system creates the second database successfully, but fails to delete the old database or grants. The system treats the rename action as a success; however, the API function returns warnings that describe the failure to delete the old database or grants.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

newname

required

string <= 64 characters

Example: newname=newlyrenamed

The database's new name.

Important:

If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (_). For example, for the dbuser database on the user cPanel account, pass in a value of user_dbuser.
The maximum length of the database name is 64 characters. However, due to the method that cPanel & WHM uses to store MySQL database names, each underscore character requires two characters of that limit. Therefore, if you enable database prefixing, the maximum length of the database name is 63 characters, which includes both the database prefix and the underscore character. Each additional underscore requires another two characters of that limit.

oldname

required

string

Example: oldname=mydb

The database's current name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  rename_database \
  oldname='mydb' \
  newname='newlyrenamed'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rename_database",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Repair MySQL database tables

This function repairs all of the tables in a MySQL® database.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=example_db

The database's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  repair_database \
  name='example_db'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "repair_database",
"module": "Mysql",
"result": {"data": [{"msg_text": "OK",
"msg_type": "status",
"table": "table1"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create a randomly named MySQL username/database set.

This function creates a randomly named MySQL® database and user. This allows a 3rdparty tool to create its own DB without needing any knowledge of cPanel internals such as quotas or other limits. These will simply be passed back as an error.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

prefix

string

Example: prefix=wp

An optional string to prepend to the randomly generated database name. This is in addition to the cPanel user which will appear prior to this. The prefix should be 6 characters or less and be only alphanumeric characters. WARNING: longer prexies lead to less entropy in the random username. Keep it short if you can!

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  setup_db_and_user \
  prefix='wp'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "setup_db_and_user",
"module": "Mysql",
"result": {"data": {"database": "cpuser_wp_gwl7vpix28owo855yjomc7rsghkbjv0d0kf45kcvzip9tyxw9kdd",
"database_user": "cpuser_wp_dji1jdt7nhjiwjcjju45",
"database_user_password": ";1t/U:wnFkCRL9q68]/+<TX=.C#7]n",
"hostname": "localhost",
"port": 3306
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remote Databases

MySQL and MariaDB / Remote Databases

Enable remote MySQL host access

This function authorizes a remote MySQL® host to access the account's databases.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

required

string or string or string or string

Example: host=192.168.1.6

The remote MySQL server's hostname or IP address.

You may use the following IP address formats:

192.168.1.6 — IP address.
192.168.%.% — Range with the percent (%) symbol as a wildcard.
192.168.0.0/16 — Range in CIDR format.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  add_host \
  host='192.168.1.6'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_host",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add remote MySQL host note

This function adds a note about a remote MySQL® server.

Important:

If you attempt to add a note to an unauthorized remote MySQL server, the function will fail.
When you disable the MySQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

required	string or string or string or string Example: host=192.168.1.6 The remote MySQL server's hostname or IP address. You may use the following IP address formats: `192.168.1.6` — IP address. `192.168.%.%` — Range with the percent (%) symbol as a wildcard. `192.168.0.0/16` — Range in CIDR format.
note required	string Example: note=A remote mysql server for storing my data note that describes the remote MySQL server.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  add_host_note \
  host='192.168.1.6' \
  note='A remote mysql server for storing my data'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_host_note",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable remote MySQL host access

This function removes a remote MySQL® host's access to the account's databases.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

host

required

string

Example: host=remote.example.com

The remote MySQL server's hostname, IP Address, or IP address range.

Note: You may use the following IP address formats:

192.168.1.6 — IP address. 192.168.%.% — Range with the percent (%) symbol as a wildcard. 192.168.0.0/16 — Range in CIDR format.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  delete_host \
  host='remote.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_host",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return remote MySQL host notes

This function returns the notes associated with the account's remote MySQL® hosts.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  get_host_notes

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_host_notes",
"module": "Mysql",
"result": {"data": {"1.2.3.45": "The combination on my luggage",
"12.34.56.78": "Located somewhere in the Ford Galaxy",
"8.8.8.8": "Located on Spaceball 1"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

User Management

MySQL and MariaDB / User Management

Create MySQL user

This function creates a MySQL® database user.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name required	string Example: name=dbuser A valid database username. Important: To learn more about database username limits, check your database type: MySQL 5.6 MySQL version 5.6 limits the database username to 16 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (`_`). The server only applies the first eight characters of the cPanel account's username. For example: A `db_` database prefix allows MySQL usernames of up to 13 characters. An `example_` database prefix allows MySQL usernames of up to eight characters. MySQL 5.7+ MySQL versions 5.7 and later limit the database username to 32 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (`_`). The server only applies the first eight characters of the cPanel account's username. For example: A `db_` database prefix allows MySQL usernames of up to 29 characters. An `example_` database prefix allows MySQL usernames of up to 24 characters. MariaDB MariaDB limits the database username to 47 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (`_`). The server only applies the first eight characters of the cPanel account's username. For example: A `db_` database prefix allows MariaDB usernames of up to 44 characters. An `example_` database prefix allows MariaDB usernames of up to 39 characters.
password required	string Example: password=12345luggage The new user's password.
prefix-size	integer Default: 16 Possible Values: 8 16 Example: prefix-size=16 The desired prefix size.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  create_user \
  name='dbuser' \
  password='12345luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_user",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete MySQL user

This function deletes a MySQL® user.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=example

The MySQL user's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  delete_user \
  name='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_user",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return MySQL user privileges

This function lists a MySQL® database user's privileges.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

database required	string Example: database=mydb The database name.
user required	string Example: user=dbuser The database user's name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (`_`). For example, for the `dbuser` user on the `user` cPanel account, pass in a value of `user_dbuser`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  get_privileges_on_database \
  user='dbuser' \
  database='mydb'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_privileges_on_database",
"module": "Mysql",
"result": {"data": ["CREATE"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return MySQL name length restrictions

This function lists a MySQL® database's name, username length restrictions, and database prefix.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  get_restrictions

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_restrictions",
"module": "Mysql",
"result": {"data": {"max_database_name_length": 64,
"max_username_length": 16,
"prefix": "user_"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return MySQL users

This function lists an account's MySQL® database users.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  list_users

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_users",
"module": "Mysql",
"result": {"data": [{"databases": ["user_database1",
"user_database2"
],
"shortuser": "user1",
"user": "example_user1"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return MySQL user routines

This function returns a database user's MySQL® routines.

Important:

When you disable the MySQL/MariaDB role and remote MySQL is not configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

database_user

string

Example: database_user=db_user

The database user for whom to return MySQL routines. If you don't specify a database user, this function returns the MySQL routines for all database users.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  list_routines

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_routines",
"module": "Mysql",
"result": {"data": ["cptest_newdb.hello",
"cptest_newdb.my_routine"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update MySQL username

This function renames a MySQL® database user.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

newname

required

string

Example: newname=mynewusername

The user's new name.

Important:

To learn more about database username limits, check your database type:

MySQL 5.6

MySQL version 5.6 limits the database username to 16 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username.

For example:

A db_ database prefix allows MySQL usernames of up to 13 characters.
An example_ database prefix allows MySQL usernames of up to eight characters.

MySQL 5.7+

MySQL versions 5.7 and later limit the database username to 32 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username.

For example:

A db_ database prefix allows MySQL usernames of up to 29 characters.
An example_ database prefix allows MySQL usernames of up to 24 characters.

MariaDB

MariaDB limits the database username to 47 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username.

For example:

A db_ database prefix allows MariaDB usernames of up to 44 characters.
An example_ database prefix allows MariaDB usernames of up to 39 characters.

oldname

required

string

Example: oldname=dbuser

The user's current name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  rename_user \
  oldname='dbuser' \
  newname='mynewusername'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rename_user",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove MySQL user privileges

This function revokes a MySQL® database user's privileges.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

database required	string Example: database=mydb The database's name.
user required	string Example: user=dbuser The database user's name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (`_`). For example, for the `dbuser` user on the `user` cPanel account, pass in a value of `user_dbuser`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  revoke_access_to_database \
  user='dbuser' \
  database='mydb'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "revoke_access_to_database",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update MySQL user password

This function sets a MySQL® database user's password.

Important:

When you disable the MySQL role and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

password required	string Example: password=12345luggage The user's new password.
user required	string Example: user=dbuser The MySQL database user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  set_password \
  user='dbuser' \
  password='12345luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_password",
"module": "Mysql",
"result": {"data": {"failures": [{"error": "string",
"host": "string"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update MySQL user privileges

This function sets a MySQL® database user's privileges.

Important:

When you disable the MySQL/MariaDB role, and remote MySQL is not already configured, the system disables this function.

Authorizations:

BasicAuth

query Parameters

database required	string Example: database=cpuser_dbname The database's name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (`_`). For example, for the `db` database on the `user` cPanel account, pass in a value of `user_db`.
privileges	string Example: privileges=DELETE,UPDATE,CREATE,ALTER `ALL PRIVILEGES` A comma-separated list of one or more of the following individual privileges: `ALTER` `ALTER ROUTINE` `CREATE` `CREATE ROUTINE` `CREATE TEMPORARY TABLES` `CREATE VIEW` `DELETE` `DROP` `EVENT` `EXECUTE` `INDEX` `INSERT` `LOCK TABLES` `REFERENCES` `SELECT` `SHOW VIEW` `TRIGGER` `UPDATE` Note: This list replaces, rather than adds to, the existing privilege list. In browser-based and command line calls, separate multiple values with `%2C` and replace spaces with `%20`.
user required	string Example: user=cpuser_dbuser The database user's name. Important: If database prefixing is enabled, you must prefix this value with the account prefix and an underscore (`_`). For example, for the `dbuser` user on the `user` cPanel account, pass in a value of `user_dbuser`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mysql \
  set_privileges_on_database \
  user='cpuser_dbuser' \
  database='cpuser_dbname'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_privileges_on_database",
"module": "Mysql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Pushbullet

The Pushbullet module for UAPI.

Validate Pushbullet token

This function sends a Pushbullet™ test message to determine that the token is valid and that the account holder can receive the message.

Authorizations:

BasicAuth

query Parameters

access_token

required

string

Example: access_token=a1b2c3d4e5f6g7h8i9j0

The Pushbullet access token.

Note:

Your Pushbullet token is available on Pushbullet's My Account page under the Access Token heading.
This is confidential information that your server sends via a secure channel.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Pushbullet \
  send_test_message \
  access_token='a1b2c3d4e5f6g7h8i9j0'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "send_test_message",
"module": "Pushbullet",
"result": {"data": {"message_id": "554d2cbd-efe61da3cacb",
"payload": {"active": true,
"body": "This message confirms that “hostname.example.com“ (192.168.0.20)\ncan send a message to you via Pushbullet.\n\nThis message was sent on Monday, May 18, 2015 at 7:12:20 PM UTC.",
"created": 1431976341.38872,
"direction": "self",
"dismissed": false,
"iden": "ujw5ScArtjUsjAeRXXMLGS",
"modified": 1431976341.39182,
"receiver_email": "[email protected]",
"receiver_email_normalized": "[email protected]",
"receiver_iden": "ujw5ScArtjU",
"sender_email": "[email protected]",
"sender_email_normalized": "[email protected]",
"sender_iden": "ujw5ScArtjU",
"sender_name": "Firstname Lastname",
"title": "Test message (ID: 555a3994-173a4a271062d)",
"type": "note"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

NVData

The NVData module for UAPI.

Antivirus Protection (ClamAV)

Optional Applications / Antivirus Protection (ClamAV)

Return virus scan types

This function gets the available local paths that a cPanel account is permitted to scan.

Note:

The system determines the available scan types based on what the system administrator has set in WHM's Configure ClamAV® page.

Note:

You must run the APIs in this order:

Run ClamScanner::start_scan to start the virus scan.
Run ClamScanner::get_scan_status in a loop until the scan is finished.
Run ClamScanner::list_infected_files to get a report of the complete list of infected files.
Decide how you want to handle each infected file.
Run ClamScanner::disinfect_files to queue the disinfection of the files.
Run ClamScanner::check_disinfection_status in a loop until you get a done status.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ClamScanner \
  get_scan_paths

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_scan_paths",
"module": "ClamScanner",
"result": {"data": {"id": "home",
"message": "Scan Entire Home Directory"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start virus scan

This function starts a ClamAV® scan on a directory.

Note:

You must run the APIs in this order:

Run ClamScanner::start_scan to start the virus scan.
Run ClamScanner::get_scan_status in a loop until the scan is finished.
Run ClamScanner::list_infected_files to get a report of the complete list of infected files.
Decide how you want to handle each infected file.
Run ClamScanner::disinfect_files to queue the disinfection of the files.
Run ClamScanner::check_disinfection_status in a loop until you get a done status.

Authorizations:

BasicAuth

query Parameters

scan_type

required

any

Possible Values: "home" "mail" "public_html" "public_ftp"

Example: scan_type=home

The type of directory to scan.

home — User's entire home directory
mail — User's email directory
public_html — User's web directory
public_ftp — User's ftp directory

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ClamScanner \
  start_scan \
  scan_type='home'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "start_scan",
"module": "ClamScanner",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return infected file list

This function lists infected files from a ClamAV® virus scan.

Note:

You must run the APIs in this order:

Run ClamScanner::start_scan to start the virus scan.
Run ClamScanner::get_scan_status in a loop until the scan is finished.
Run ClamScanner::list_infected_files to get a report of the complete list of infected files.
Decide how you want to handle each infected file.
Run ClamScanner::disinfect_files to queue the disinfection of the files.
Run ClamScanner::check_disinfection_status in a loop until you get a done status.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ClamScanner \
  list_infected_files

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_infected_files",
"module": "ClamScanner",
"result": {"data": [{"file": "/home/username/infected_file.txt",
"virus_type": "Eicar-Signature"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Request virus scan status

This function gets the status of a ClamAV® scan on a directory.

Note:

You must run the APIs in this order:

Run ClamScanner::start_scan to start the virus scan.
Run ClamScanner::get_scan_status in a loop until the scan is finished.
Run ClamScanner::list_infected_files to get a report of the complete list of infected files.
Decide how you want to handle each infected file.
Run ClamScanner::disinfect_files to queue the disinfection of the files.
Run ClamScanner::check_disinfection_status in a loop until you get a done status.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ClamScanner \
  get_scan_status

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_scan_status",
"module": "ClamScanner",
"result": {"data": {"current_file": "/home/username/afilename.txt",
"infected_files": ["/home/username/afile/witha/virus.txt",
"/home/username/we/gotcha.exe"
],
"scan_complete": 1,
"scanned_file_count": 135,
"scanned_file_size": 6022,
"time_started": "1608593571",
"total_file_count": 135,
"total_file_size_MiB": 3640222
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start disinfecting files with viruses

This function applies the disinfection option selected by the user for each infected file.

Note:

You must run the APIs in this order:

Run ClamScanner::start_scan to start the virus scan.
Run ClamScanner::get_scan_status in a loop until the scan is finished.
Run ClamScanner::list_infected_files to get a report of the complete list of infected files.
Decide how you want to handle each infected file.
Run ClamScanner::disinfect_files to queue the disinfection of the files.
Run ClamScanner::check_disinfection_status in a loop until you get a done status.

Authorizations:

BasicAuth

Request Body schema: application/json

object

The user provides the actions to perform on each specific infected file found in the scan.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

Payload
CLI
HTTP Request (Wire Format)

Content type

application/json

{"actions": {"home/unsure": "ignore",
"home/virus1": "delete",
"home/virus2": "quarantine"
}
}

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disinfect_files",
"module": "ClamScanner",
"result": {"data": {"log": "/home/user/.clamavconnector.disinfection.log",
"task_id": "00000000/5a9ec8dd4c345d"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Request disinfection process status

This function checks the status of the previously queued disinfection of infected files.

Note:

You must run the APIs in this order:

Run ClamScanner::start_scan to start the virus scan.
Run ClamScanner::get_scan_status in a loop until the scan is finished.
Run ClamScanner::list_infected_files to get a report of the complete list of infected files.
Decide how you want to handle each infected file.
Run ClamScanner::disinfect_files to queue the disinfection of the files.
Run ClamScanner::check_disinfection_status in a loop until you get a done status.

If you want to display the progress, you can render the ClamScanner::check_disinfection_status returned 'result{data}{details}' array where the type is step.

Each step record indicates the action taken on a specific file in the set being processed.

Authorizations:

BasicAuth

query Parameters

last_id

integer >= 1

Example: last_id=10

The unique id of the message you last received from this same log.

The API will return only the records after the specified last_id.

If this parameter is not provided, the entire log is returned.

Note:

For improved performance, we recommend applications include the last record ID (last_id) from a previous call to this API, so only messages since the previous API call are returned.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ClamScanner \
  check_disinfection_status

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_disinfection_status",
"module": "ClamScanner",
"result": {"data": {"details": [{"file": "/home/user/virus",
"id": 2,
"message": "string",
"state": "deleted",
"type": "step"
}
],
"log": "/home/user/.clamavconnector.disinfection.log",
"status": "done"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Calendar and Contacts (DAV)

Optional Applications / Calendar and Contacts (DAV)

Disable global address book

This function disables the shared global address book for the current cPanel account's webmail accounts.

Authorizations:

BasicAuth

query Parameters

name	string Example: name=user cPanel account username or a Webmail user's email address. If you do not specify a user, this parameter defaults to the currently-authenticated user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DAV \
  disable_shared_global_addressbook

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_shared_global_addressbook",
"module": "DAV",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether global address book is enabled

This function checks whether the shared global address book is enabled on the current cPanel account's webmail accounts.

Authorizations:

BasicAuth

query Parameters

name	string Example: name=user cPanel account user name or a Webmail user's email address. If you do not specify a user, this parameter defaults to the currently-authenticated user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DAV \
  has_shared_global_addressbook

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_shared_global_addressbook",
"module": "DAV",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable global address book

This function enables the shared global address book for the current cPanel account's webmail accounts.

Authorizations:

BasicAuth

query Parameters

name	string Example: name=user cPanel account username or a Webmail user's email address. If you do not specify a user, this parameter defaults to the currently-authenticated user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DAV \
  enable_shared_global_addressbook

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_shared_global_addressbook",
"module": "DAV",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether DAV is enabled

This function checks whether the DAV service is enabled.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DAV \
  is_dav_service_enabled

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_dav_service_enabled",
"module": "DAV",
"result": {"data": {"enabled": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return CalDAV and CardDAV connection information

This function returns the connection information to set up the CalDAV and CardDAV clients.

Authorizations:

BasicAuth

query Parameters

string or string

A cPanel account or valid email account user.

If you do not include this parameter, the function defaults to the current authenticated user.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DAV \
  get_calendar_contacts_config

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_calendar_contacts_config",
"module": "DAV",
"result": {"data": {"activesync": {"enabled": 1,
"port": 2091,
"server": "example.com",
"user": "username"
},
"no_ssl": {"calendars": [{"description": "Custom calendar 1.",
"name": "Calendar 1",
"path": "/calendars/example/calendar:ZcG9JBH68WXxfMVUgvSrUw1",
"url": "http://example.com:2079/calendars/example/calendar:ZcG9JBH68WXxfMVUgvSrUw1"
}
],
"contacts": [{"description": "Custom address book 1.",
"name": "Custom 1",
"path": "/addressbooks/example/contacts:E-KKA5uQZyQJbTBKcGP3OQ6",
"url": "https://example.com:2080/addressbooks/example/contacts:E-KKA5uQZyQJbTBKcGP3OQ6"
}
],
"free_busy": "http://server.example.com:2079/kronolith/fb.php?u=example",
"full_server": "http://example.com:2079/rpc/principal/example",
"port": 2079,
"server": "http://example.com:2079"
},
"ssl": {"calendars": [{"description": "Custom calendar 2.",
"name": "Calendar 2",
"path": "/calendars/example/calendar:ZcG9JBH68WXxfMVUgvSrUw1",
"url": "http://example.com:2080/calendars/example/calendar:ZcG9JBH68WXxfMVUgvSrUw1"
}
],
"contacts": [{"description": "Custom address book 2.",
"name": "Address book 2",
"path": "/addressbooks/example/contacts:E-KKA5uQZyQJbTBKcGP3OQ6",
"url": "https://example.com:2080/addressbooks/example/contacts:E-KKA5uQZyQJbTBKcGP3OQ6"
}
],
"free_busy": "http://server.example.com:2080/kronolith/fb.php?u=example",
"full_server": "http://example.com:2080/rpc/principal/example",
"is_self_signed": 1,
"port": 2080,
"server": "https://example.com:2080"
},
"user": "username"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether Horde is enabled

This function checks whether Horde is enabled. Since Horde is no longer installed with the product, the return value will only ever be 0.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DAV \
  is_horde_enabled

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_horde_enabled",
"module": "DAV",
"result": {"data": {"enabled": 0
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Share a calendar

This function adds a share for the specified calendar.

Authorizations:

BasicAuth

query Parameters

calendar required	string Example: calendar=calendar The calendar to share.
delegatee required	string Example: [email protected] The person to whom you will share the calendar.
delegator required	string Example: [email protected] The owner of the calendar, who wishes to share it to another user.
readonly	integer Possible Values: 0 1 Example: readonly=1 If set, the provided access will be read-only.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CPDAVD \
  add_delegate \
  delegator='[email protected]' \
  delegatee='[email protected]' \
  calendar='calendar'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_delegate",
"module": "CPDAVD",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

List calendar sharing.

This function lists the sharing configuration in calendars for this account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CPDAVD \
  list_delegates

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_delegates",
"module": "CPDAVD",
"result": {"data": [{"calendar": "calendar",
"calname": "cPanel CalDAV Calendar",
"delegatee": "[email protected]",
"delegator": "[email protected]",
"readonly": 0
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove a share.

This function removes a share for the specified calendar.

Authorizations:

BasicAuth

query Parameters

calendar required	string Example: calendar=calendar The calendar that was shared.
delegatee required	string Example: [email protected] The person to whom the calendar was shared.
delegator required	string Example: [email protected] The owner of the calendar, who wishes to remove the sharing.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CPDAVD \
  remove_delegate \
  delegator='[email protected]' \
  delegatee='[email protected]' \
  calendar='calendar'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_delegate",
"module": "CPDAVD",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Perform an operation on a calendar, task list or address book.

This function creates, updates, or deletes a collection.

Authorizations:

BasicAuth

query Parameters

account required	string Example: [email protected] The owner of the calendar.
action required	string Possible Values: "create" "update" "delete" Example: action=delete The action to perform (create, update, or delete a collection).
calendar-color	string Example: calendar-color=#ee5555 The color of the calendar, if applicable.
collection_type required	string Possible Values: "calendar" "tasks" "addressbook" Example: collection_type=calendar The collection type.
description	string Example: description=This is my calendar. The description of the collection.
name	string Example: name=My Calendar The name of the collection. Required when creating a collection.
path required	string Example: path=/calendars/[email protected]/mycalendar The path to the collection.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CPDAVD \
  manage_collection \
  account='[email protected]' \
  action='delete' \
  path='/calendars/[email protected]/mycalendar' \
  collection_type='calendar'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "manage_collection",
"module": "CPDAVD",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update calendar sharing

This function lists the users that are available for use with CalDAV and CardDAV

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CPDAVD \
  list_users

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_users",
"module": "CPDAVD",
"result": {"data": [{"[email protected]": {"addressbook": {"description": "Default Address Book automatically created for your account.",
"displayname": "cPanel CardDAV Address Book",
"protected": 1,
"type": "VADDRESSBOOK"
},
"calendar": {"calendar-color": "#ff6c2c",
"description": "Default Calendar automatically created for your account.",
"displayname": "cPanel CalDAV Calendar",
"protected": 1,
"type": "VCALENDAR"
}
}
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update calendar sharing.

This function updates a share for the specified calendar.

Authorizations:

BasicAuth

query Parameters

calendar required	string Example: calendar=calendar The calendar to share.
delegatee required	string Example: [email protected] The person to whom you will share the calendar.
delegator required	string Example: [email protected] The owner of the calendar, who wishes to change the details of the sharing.
readonly	integer Possible Values: 0 1 Example: readonly=1 If set, the provided access will be read-only.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CPDAVD \
  update_delegate \
  delegator='[email protected]' \
  delegatee='[email protected]' \
  calendar='calendar'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update_delegate",
"module": "CPDAVD",
"result": {"data": {"shared": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Calendar and Contacts Server

Optional Applications / Calendar and Contacts Server

Remove calendar delegation

This function removes a delegate from another user's calendar.

Note:

You must install the Calendar and Contacts Server cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

delegatee required	string <email> Example: [email protected] The user from whom you wish to remove delegation rights.
delegator required	string <email> Example: [email protected] The calendar's owner.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CCS \
  remove_delegate \
  delegator='[email protected]' \
  delegatee='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_delegate",
"module": "CCS",
"result": {"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update calendar delegation

This function updates the delegation of a user's calendar to another user.

Note:

You must install the Calendar and Contacts Server cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

delegatee required	string <email> Example: [email protected] The user to whom you delegated the calendar.
delegator required	string <email> Example: [email protected] The calendar's owner.
readonly	integer Default: 0 Example: readonly=1 Whether the delegatee will only have read-only access on the calendar. `1` - Read-only access. `0` - Full access.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CCS \
  update_delegate \
  delegator='[email protected]' \
  delegatee='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update_delegate",
"module": "CCS",
"result": {"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

List cPanel account's calendar users

This function lists all calendar users on the cPanel account.

Note:

You must install the Calendar and Contacts Server cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CCS \
  list_users

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_users",
"module": "CCS",
"result": {"data": {"[email protected]": "0882362A-0B98-11E8-BAF5-D988266709C1",
"[email protected]": "96F1EB2F-A501-11EA-A3EF-A553B2E4FFA8",
"[email protected]": "195C8A51-E1B3-11E6-8715-F54FA4E00DDD",
"[email protected]": "028F4AB1-0F1A-11E7-AEC7-E08FECEC8036"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add calendar delegation

This function delegates a user's calendar to another user.

Note:

You must install the Calendar and Contacts Server cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

delegatee required	string <email> Example: [email protected] The user to whom you wish to delegate the calendar.
delegator required	string <email> Example: [email protected] The calendar's owner.
readonly	integer Default: 0 Possible Values: 1 0 Example: readonly=1 Whether the delegatee will only have read-only access on the calendar. `1` - Read-only access. `0` - Full access.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CCS \
  add_delegate \
  delegator='[email protected]' \
  delegatee='[email protected]'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_delegate",
"module": "CCS",
"result": {"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

List cPanel account's calendar delegates

This function lists all calendar delegates on the cPanel account.

Note:

You must install the Calendar and Contacts Server cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  CCS \
  list_delegates

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_delegates",
"module": "CCS",
"result": {"data": [{"delegatee": "[email protected]",
"delegator": "[email protected]",
"read_only": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

cPanel Addons (cPAddons)

Optional Applications / cPanel Addons (cPAddons)

Return deployed cPAddons instance's settings

This function lists a cPAddons instance's settings.

Authorizations:

BasicAuth

query Parameters

unique_id

required

string

Example: unique_id=cPanel::Blogs::WordPressX.0.1486754861

The unique identifier of the cPAddon.

Note:

To find this identifier, run the list_addon_instances function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPAddons \
  get_instance_settings \
  unique_id='cPanel::Blogs::WordPressX.0.1486754861'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_instance_settings",
"module": "cPAddons",
"result": {"data": {"addon": "cPanel::Blogs::WordPressX",
"admin_user": "string",
"autoupdate": 0,
"db_name": "example_wp",
"db_type": "mysql",
"db_user": "example_wp",
"domain": "example.com",
"installdir": "/home/example/public_html/wordpress",
"url_to_install": "http://example.com/wordpress/"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return deployed cPAddons instances

This function lists an account's deployed cPAddons instances.

Authorizations:

BasicAuth

query Parameters

addon

string

Example: addon=cPanel::Blogs::WordPressX

The cPAddon for which to return the instances data.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPAddons \
  list_addon_instances

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_addon_instances",
"module": "cPAddons",
"result": {"data": [{"addon": "cPanel::Blogs::WordPressX",
"domain": "example.com",
"installdir": "/home/example/public_html/wordpress",
"instance": "cPanel::Blogs::WordPressX.0",
"unique_id": "cPanel::Blogs::WordPressX.0.1486754861"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return available cPAddons

This function lists an account's available cPAddons.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  cPAddons \
  get_available_addons

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_available_addons",
"module": "cPAddons",
"result": {"data": [{"description": "WordPress (cPanel)",
"module": "cPanel::Blogs::WordPress"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

WordPress Manager Backups

Optional Applications / WordPress Manager Backups

Return all WordPress sites' backup status

This function checks for any active WordPress® site backups on the cPanel account.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressBackup \
  any_running

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "any_running",
"module": "WordPressBackup",
"result": {"data": {"any_running": 0,
"sites": [{"id": "null",
"site": "example.com",
"type": "backup"
}
],
"sse_url": "/sse/WordPressBackup"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Stop WordPress site backup

This function cancels a WordPress® site backup.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

required

string or string

Example: site=example.com

The WordPress site's URL without the protocol prefix.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressBackup \
  cancel \
  site='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "cancel",
"module": "WordPressBackup",
"result": {"data": {"ok": 0,
"site": "example.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete WordPress backup temporary files

This function releases any system resources from a previous WordPress® site backup.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

site

required

string

Example: site=example.com/wordpress

The WordPress site's URL without the protocol prefix.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressBackup \
  cleanup \
  site='example.com/wordpress'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "cleanup",
"module": "WordPressBackup",
"result": {"data": {"ok": 1,
"site": "example.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress site backup status

This function checks for an active WordPress® site backup.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

site

required

string

Example: site=example.com example.com/wordpress

The WordPress site's URL without http://.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressBackup \
  is_running \
  site='example.com

example.com/wordpress'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_running",
"module": "WordPressBackup",
"result": {"data": {"action_id": "example.com__2018-10-10T10:53:31-0500",
"is_running": 0
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress site backups

This function retrieves a list of available WordPress® site backups of a single site.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

site

required

string

Example: site=example.com/wordpress

The WordPress site's URL without the protocol prefix.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressBackup \
  get_available_backups \
  site='example.com/wordpress'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_available_backups",
"module": "WordPressBackup",
"result": {"data": {"available": [{"date": 1539267197000,
"file": "example.com__2018-10-10T10:53:31-0500.tar.gz",
"path": "/home/example/wordpress-backups/example.com__2018-10-10T10:53:31-0500.tar.gz",
"site": "example.com"
}
],
"dir": "/home/example/wordpress-backups"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Backup WordPress site

This function starts a single WordPress® site backup.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

required

string or string

Example: site=example.com

The WordPress site's URL without the protocol prefix.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressBackup \
  start \
  site='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "start",
"module": "WordPressBackup",
"result": {"data": {"backup_id": "example.com__2018-10-10T10:53:31-0500",
"site": "example.com",
"sse_url": "/sse/WordPressBackup"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress site restore status

This function returns whether a WordPress® site backup restoration is in progress.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.
The output of this function changes, depending on the state of the backup restoration.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressRestore \
  any_running

Response samples

200

Content type

application/json

Example

Example output of a backup restore in progress.

{"data": {"any_running": 1,
"sites": [{"id": null,
"site": "example.com",
"type": "restore"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}

Delete restored WordPress site's temporary files

This function cleans up any temporary system resources after a WordPress® site backup restoration.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

site

required

string

Examples:

site=example.com - Just a domain.
site=example.com/wordpress - Domain with path.

The WordPress site's URL without the protocol prefix.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressRestore \
  cleanup \
  site='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "cleanup",
"module": "WordPressRestore",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Restore WordPress site

This function starts a single WordPress® site backup restoration.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

backup_path required	string <path> Example: backup_path=/home/example/wordpress-backups/example.com__2018-11-13T11:11:31-0600.tar.gz The file path to the backup archive.
site required	string Examples: site=example.com - Just a domain. site=example.com/wordpress - Domain with path. The WordPress site's URL to restore.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressRestore \
  start \
  site='example.com' \
  backup_path='/home/example/wordpress-backups/example.com__2018-11-13T11:11:31-0600.tar.gz'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "start",
"module": "WordPressRestore",
"result": {"data": {"restore_id": "example.com__2018-11-15T08:03:22-0600"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

WordPress Manager Settings

Optional Applications / WordPress Manager Settings

Stop WordPress site scan

This function cancels a scan that you start with the WordPressInstanceManager::start_scan function.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  cancel_scan

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "cancel_scan",
"module": "WordPressInstanceManager",
"result": {"data": 0,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update WordPress site admin password

This function updates a WordPress® cPAddon instance's administrator password.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

id required	string Example: id=cPanel__Blogs__WordPressX.0.1491917088 The cPAddon instance's unique ID. Note: You can retrieve an instance ID with the `get_instances` function.
password required	string Example: password=luggage12345 The cPAddon instance's new administrator password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  change_admin_password \
  id='cPanel__Blogs__WordPressX.0.1491917088' \
  password='luggage12345'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "change_admin_password",
"module": "WordPressInstanceManager",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove scan log after completed scan

This function cleans up the scan log file after you complete a scan with the WordPressInstanceManager::start_scan function. To read more information about the complete scan process, read our UAPI Functions - WordPressInstanceManager::start_scan documentation.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

guid

required

string

Example: guid=B3A27B96-51F7-11E8-92E3-CC90C4F823F0

The scan’s unique ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  cleanup_scan \
  guid='B3A27B96-51F7-11E8-92E3-CC90C4F823F0'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "cleanup_scan",
"module": "WordPressInstanceManager",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update WordPress site automatic update settings

This function configures a WordPress cPAddon instance's automatic updates settings. If you enable automatic updates for a legacy WordPress cPAddon instance, the function will convert it to use the RPM-based WordPress cPAddon.

Important:

This function changes the instance's automatic update setting in the wp-config.php file. Before you run this function, you should verify that a filter does not exist for the automatic update settings. Use the get_instance_by_id function and view the autoupdate.core.has_filter return to determine if a filter exists.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

autoupdate.core.major required	integer Possible Values: 0 1 Example: autoupdate.core.major=0 Whether to enable automatic updates for major releases. `1` - Enable. `0` - Disable.
autoupdate.core.minor required	integer Possible Values: 0 1 Example: autoupdate.core.minor=0 Whether to enable automatic updates for minor releases. `1` - Enable. `0` - Disable.
id required	string Example: id=cPanel__Blogs__WordPressX.0.1491917088 The cPAddon instance's unique ID. Note: You can retrieve an instance ID with the `get_instances` function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  configure_autoupdate \
  id='cPanel__Blogs__WordPressX.0.1491917088' \
  autoupdate.core.major='0' \
  autoupdate.core.minor='0'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "configure_autoupdate",
"module": "WordPressInstanceManager",
"result": {"data": {"after": {"addon_config": "/home/example/.cpaddons/cPanel::Blogs::WordPressX.0.yaml",
"addon_name": "cPanel::Blogs::WordPressX",
"addon_type": "modern",
"admin_url": "example.com/wordpress-41/wp-login.php",
"admin_username": "wpadmin",
"available_version": "4.9.1",
"current_version": "4.9.1",
"db_name": "example_wp1",
"db_prefix": "example",
"db_server": "localhost",
"db_type": "mysql",
"db_username": "example_wp1",
"domain": "example.com",
"full_path": "/home/example/public_html/wordpress-41",
"homedir": "/home/example",
"id": "cPanel__Blogs__WordPress.1.1509732223",
"initial_install_version": "4.1",
"migrated_from": "cPanel::Blogs::WordPress",
"migrated_on": 1513965986,
"rel_path": "wordpress-41",
"site_url": "example.com/wordpress-41"
},
"before": {"addon_config": "/home/example/.cpaddons/cPanel::Blogs::WordPressX.0.yaml",
"addon_name": "cPanel::Blogs::WordPress",
"addon_type": "legacy",
"admin_url": "example.com/wordpress-41/wp-login.php",
"admin_username": "wpadmin",
"available_version": "4.9.1",
"current_version": "4.9.1",
"db_name": "example_wp1",
"db_prefix": "example",
"db_server": "localhost",
"db_type": "mysql",
"db_username": "example_wp1",
"domain": "example.com",
"full_path": "/home/example/public_html/wordpress-41",
"homedir": "/home/example",
"id": "cPanel__Blogs__WordPress.1.1509732223",
"initial_install_version": "4.1",
"rel_path": "wordpress-41",
"site_url": "example.com/wordpress-41"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress site settings

This function retrieves a WordPress® instance's configuration.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.
This function retrieves some data that the system stored during the WordPress installation. That data may not reflect the most recent user changes.

Authorizations:

BasicAuth

query Parameters

id

required

string

Example: id=cPanel__Blogs__WordPressX.0.1528208546

The WordPress instance's unique ID.

Note:

You can retrieve an instance ID with the get_instances function.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  get_instance_by_id \
  id='cPanel__Blogs__WordPressX.0.1528208546'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_instance_by_id",
"module": "WordPressInstanceManager",
"result": {"data": {"addon_config": "/home/example/.cpaddons/cPanel::Blogs::WordPressX.0.yaml",
"addon_name": "cPanel::Blogs::WordPressX",
"addon_type": "modern",
"admin_url": "example.com/wp-login.php",
"admin_username": "admin",
"admins": [{"ID": 1,
"display_name": "admin",
"user_email": "[email protected]",
"user_login": "admin",
"user_nicename": "admin",
"user_status": 0
}
],
"autoupdate": true,
"autoupdate.core.has_filter": false,
"autoupdate.core.major": false,
"autoupdate.core.minor": true,
"available_version": "4.9.6",
"created_on": 1528208546,
"current_version": "4.9.5",
"db_name": "example_wp2",
"db_prefix": "wp",
"db_server": "localhost",
"db_type": "mysql",
"db_username": "example_wp",
"domain": "example.com",
"full_path": "/home/example/public_html",
"homedir": "/home/example",
"id": "cPanel__Blogs__WordPressX.0.1528208546",
"initial_install_version": "4.7.2",
"recent": 1,
"rel_path": " ",
"site_url": "example.com/wordpress"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress Manager plugin version

This function retrieves the WordPress Manager plugin's version.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  get_api_version

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_api_version",
"module": "WordPressInstanceManager",
"result": {"data": {"version": "1.0.1-0"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return latest wordpress.org updates

This function returns the available WordPress® updates from wordpress.org.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

query Parameters

cache_time	integer >= 0 Default: 86400 Example: cache_time=3600 The length of time in seconds to cache the database between requests to wordpress.org.
force	integer Default: 0 Possible Values: 0 1 Example: force=0 Whether to force a reload from the remote API. Otherwise, the function returns information stored in local cache. `1` — Force reload `0` — Read local cashe.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  get_latest_wordpress_version_from_wordpress_org

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_latest_wordpress_version_from_wordpress_org",
"module": "WordPressInstanceManager",
"result": {"data": {"offers": [{"current": null,
"download": null,
"locale": null,
"mysql_version": null,
"new_bundled": null,
"packages": {"full": null,
"new_bundled": null,
"no_content": null,
"partial": null,
"rollback": null
},
"partial_version": null,
"php_version": null,
"response": null,
"version": null
}
],
"translations": ["string"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress sites

This function lists an account's WordPress® instances.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.
This function retrieves data that the system stored during the WordPress installation. That data may not reflect the most recent user changes.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  get_instances

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_instances",
"module": "WordPressInstanceManager",
"result": {"data": {"errors": ["string"
],
"instances": [{"addon_config": "/home/example/.cpaddons/cPanel::Blogs::WordPressX.0.yaml",
"addon_name": "cPanel::Blogs::WordPressX",
"addon_type": "modern",
"admin_url": "example.com/wp-login.php",
"admin_username": "admin",
"available_version": null,
"created_on": 1528208546,
"current_version": null,
"db_name": "example_wp",
"db_prefix": "wp",
"db_server": "localhost",
"db_type": "mysql",
"db_username": "example_wp",
"domain": "example.com",
"full_path": "/home/example/public_html",
"homedir": "/home/example",
"id": "cPanel__Blogs__WordPressX.0.1528208546",
"import_guid": "8AF1767E-68CD-11E8-90D1-96B06D626D05",
"imported_on": 1528209264,
"initial_install_version": "4.9.6",
"migrated_from": "cPanel::Blogs::WordPress",
"migrated_on": 1528209264,
"recent": 1,
"rel_path": " ",
"site_url": "example.com"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return WordPress site scan results

This function checks the status of a completed scan and reports the results. To find more information about the scan process, read our UAPI documentation for WordPressInstanceManager::start_scan.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  get_scan_results

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_scan_results",
"module": "WordPressInstanceManager",
"result": {"data": {"instances": [{"addon_config": "/home/example/.cpaddons/cPanel::Blogs::WordPressX.0.yaml",
"addon_name": "cPanel::Blogs::WordPressX",
"addon_type": "modern",
"admin_url": "example.com/wp-login.php",
"admin_username": "admin",
"available_version": "4.9.5",
"current_version": "4.9.5",
"db_name": "example_wp",
"db_prefix": "wp",
"db_server": "localhost",
"db_type": "mysql",
"db_username": "example_wp",
"domain": "example.com",
"full_path": "/home/example/public_html",
"homedir": "/home/example",
"id": "cPanel__Blogs__WordPressX.0.1528208546",
"initial_install_version": "4.9.6",
"rel_path": "public_html",
"site_url": "example.com"
}
],
"is_running": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start WordPress sites scan

This function scans for WordPress® instances installed on a cPanel account. The system will populate cPanel's WordPress Manager interface with any newly discovered instances.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Server Sent Events (SSE)

This function uses the following SSE events:

register — The scan operation discovered a WordPress instance and registered it. The data is a JSON-encoded object containing the attributes of the instance, with the same format used in the UAPI get_instances and UAPI get_instance_by_id functions.
found — The scan operation found a WordPress instance. If the WordPress instance is newly discovered, the system will also generate a register event for the instance. The data is a JSON-encoded object containing the following:
- path — The absolute file path to the instance.
done — The scan is finished. The data is a JSON-encoded object that contains:
- found — An array of strings that represents the absolute path to the discovered instances and any instances that the system already registered.
- converted — An array of converted instances that the system returns in the same format provided in the UAPI get_instances and UAPI get_instance_by_id functions.
terminated — The system or user terminated the scan.
timedout — The scan timed out before it completed.
register-failed — The system failed to build the instance registry. The data is a JSON-encoded string that contains the error message.
register-load-failed — The system could not load the registry after building the instance registry. The data is a JSON-encoded string that contains the error message.

For more information about server sent events, read Mozilla's Using server-sent events documentation.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  start_scan

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "start_scan",
"module": "WordPressInstanceManager",
"result": {"data": {"guid": "B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"log": "/home/example/.cpanel/plugins/wordpress/scans/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
"sse_url": "/sse/WordPressScan/B3A27B96-51F7-11E8-92E3-CC90C4F823F0"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Verify WordPress cPAddon availability

This function verifies that the RPM-based WordPress® cPAddon exists on the system.

Note:

You must install the WordPress Manager cPanel plugin to access this API function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressInstanceManager \
  is_installable_addon_available

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_installable_addon_available",
"module": "WordPressInstanceManager",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

PostgreSQL Database Management

PostgreSQL / Database Management

Create PostgreSQL database

This function creates a PostgreSQL® database.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=database

The database's name.

Note:

If database prefixing is enabled, this parameter must include the database prefix for the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  create_database \
  name='database'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_database",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete PostgreSQL database

This function deletes a PostgreSQL® database.

Important:

When you disable the Postgres role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=database

The database's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  delete_database \
  name='database'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_database",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return PostgreSQL name length restrictions

This function retrieves the PostgreSQL® user and database name length restrictions.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  get_restrictions

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_restrictions",
"module": "Postgresql",
"result": {"data": {"max_database_name_length": 63,
"max_username_length": 63,
"prefix": "example_"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return PostgreSQL databases

This function lists an account's PostgreSQL® databases.

Important:

When you disable the Postgres role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  list_databases

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_databases",
"module": "Postgresql",
"result": {"data": [{"database": "user_db",
"disk_usage": 673,
"users": ["db_user"
]
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update PostgreSQL database name

This function renames a PostgreSQL® database.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

newname required	string Example: newname=database2 The database's new name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.
oldname required	string Example: oldname=database The database's current name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  rename_database \
  oldname='database' \
  newname='database2'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rename_database",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

PostgreSQL User Management

PostgreSQL / User Management

Update PostgreSQL® privileges

This function synchronizes PostgreSQL® database user privileges on an account.

Some versions of PostgreSQL are ANSI SQL-92 compliant and do not support recursive grants, wildcard grants, or future grants. If you use phpPgAdmin, or manually create new tables, and you want multiple PostgreSQL users to access your PostgreSQL tables, you may either call this API function or click Synchronize Grants in the PostgreSQL Databases interface (Home >> Databases >> PostgreSQL Databases) after you add a table.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  update_privileges

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update_privileges",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create PostgreSQL user

This function creates a PostgreSQL® database user.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name required	string Example: name=dbuser The database user's name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.
password required	string Example: password=123456luggage The new user's password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  create_user \
  name='dbuser' \
  password='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create_user",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete PostgreSQL user

This function deletes a PostgreSQL® user.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=example

The PostgreSQL user's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  delete_user \
  name='example'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_user",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable all user privileges on PostgreSQL database

This function grants all privileges for a PostgreSQL® database to a database user.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

database required	string Example: database=example_database The database's name. Note If database prefixing is enabled, this value must include the database prefix for the account.
user required	string Example: user=example_dbuser The database user's name. Note If database prefixing is enabled, this value must include the database prefix for the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  grant_all_privileges \
  user='example_dbuser' \
  database='example_database'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "grant_all_privileges",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update PostgreSQL username

This function renames a PostgreSQL® database user.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

newname required	string Example: newname=dbuser2 The database user's new name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.
oldname required	string Example: oldname=dbuser The database user's current name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.
password required	string Example: password=123456luggage The database user's new password.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  rename_user \
  oldname='dbuser' \
  newname='dbuser2' \
  password='123456luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rename_user",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return PostgreSQL users

This function lists an account's PostgreSQL® database users.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  list_users

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_users",
"module": "Postgresql",
"result": {"data": ["example_user1",
"example_user2"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Update PostgreSQL username without password

This function renames a PostgreSQL® database user.

Warning:

If you rename a PostgreSQL user, you must set the password for the database user. This is required because of the md5 hash that PostgreSQL creates to store user passwords.
We strongly recommend that you use the Postgresql::rename_user function instead of this one.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

newname required	string Example: newname=dbuser2 The database user's new name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.
oldname required	string Example: oldname=dbuser The database user's current name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  rename_user_no_password \
  oldname='dbuser' \
  newname='dbuser2'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rename_user_no_password",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove PostgreSQL user privileges

This function revokes all privileges for a PostgreSQL® database from a database user.

Important:

When you disable the PostgreSQL role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

database required	string Example: database=example_database The database's name. Note If database prefixing is enabled, this value must include the database prefix for the account.
user required	string Example: user=example_dbuser The database user's name. Note If database prefixing is enabled, this value must include the database prefix for the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  revoke_all_privileges \
  user='example_dbuser' \
  database='example_database'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "revoke_all_privileges",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update PostgreSQL user password

This function changes a PostgreSQL® database user's password.

Important:

When you disable the Postgres role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

password required	string Example: password=12345luggage The user's new password.
user required	string Example: user=dbuser The database user's name. Note: If database prefixing is enabled, this parameter must include the database prefix for the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Postgresql \
  set_password \
  user='dbuser' \
  password='12345luggage'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_password",
"module": "Postgresql",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Bandwidth

The Bandwidth module for UAPI.

Return services monitored in bandwidth data

This function returns a list of the server's enabled protocols.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Bandwidth \
  get_enabled_protocols

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_enabled_protocols",
"module": "Bandwidth",
"result": {"data": ["imap"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return cPanel account's bandwidth usage report

This function queries an account's bandwidth data and returns a report.

Note:

This function also returns the bandwidth use of a distributed cPanel account.

Authorizations:

BasicAuth

query Parameters

domains	string <domain> Examples: - Get data for multiple domains and UNKNOWN. - Get data for a specific domain. A pipe-separated list of domains for which to provided data. Note: If you do not include this parameter, the function will return data for all domains on the cPanel account. The `UNKNOWN` "pseudo-domain" refers to data recorded without a specific domain. All traffic except HTTP traffic is recorded without a specific domain.
end	integer <unix_timestamp> Example: end=1446664809 The end date of the report window.
required	string or string Examples: - domain\|protocol\|year - domain\|year - protocol\|year_month - year_month_day How to group the data in the report, in pipe-separated format. This list must contain one or both of the following parameters: A pipe-separated list that contains one or both of the following parameters: `domain` `protocol` This parameter can also include only one of the following start time interval types: `year` `year_month` `year_month_day` `year_month_day_hour` `year_month_day_mour_minute` Note: This parameter accepts a maximum of three values. The function nests the return objects in the order that you declare the values in this parameter.
interval	string Default: "daily" Possible Values: "daily" "hourly" "5min" Example: interval=daily Length of time between bandwidth data samples. `daily` `hourly` `5min` Note: The interval's retention period determines availability of the interval's data. Use the `Bandwidth::get_retention_periods` API to determine an interval's retention period.
protocols	string Examples: - Get data for multiple protocols. - Get data for a specific protocol. A pipe-separated list of the protocols for which to provide data. `http` `imap` `smtp` `pop3` `ftp`
start	integer <unix_timestamp> Example: start=1445664609 The start date of the report window.
timezone	string <olson_timezone_name> Example: timezone=America/Chicago The timezone in which to report the data.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Bandwidth \
  query \
  grouping='domain|protocol|year'

Response samples

200

Content type

application/json

Example

domain

grouping=domain

{"data": {"UNKNOWN": 70447164,
"example.com": 815258916235,
"parkedexample.com": 18861122614,
"subdomain.example.com": 11407,
"subdomain2.example.com": 683533
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1
}

Return bandwidth retention period

This function retrieves the retention periods for bandwidth data.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Bandwidth \
  get_retention_periods

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_retention_periods",
"module": "Bandwidth",
"result": {"data": [{"interval": "5min",
"retention": 2678400
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Known SSH Hosts Management

Security / Known SSH Hosts Management

Create host

This function registers a host in the cPanel account's /home/user/.ssh/known_hosts file.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: host_name=hostname.example.com The hostname or IP address to add.
port	integer Default: 22 Example: port=1234 The SSH port to use, if the system uses a non-standard SSH port.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  KnownHosts \
  create \
  host_name='hostname.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "KnownHosts",
"result": {"data": {"host": [{"host": "hostname.example.com",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==",
"line": "host.example.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==",
"meta": {"algorithm": "ssh-rsa",
"body": "AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==",
"md5": "b6030e39979ed0e724cea3773e014209",
"md5-printable": "MD5:b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09",
"sha256": "44e405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b 3b3fc44",
"sha256-printable": "SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ"
}
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete host

This function removes a host from the cPanel account's /home/user/.ssh/known_hosts file.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: host_name=host.example.com The hostname or IP address of the host to delete.
port	integer >= 1 Default: 22 Example: port=1234 The SSH port to use.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  KnownHosts \
  delete \
  host_name='host.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete",
"module": "KnownHosts",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update host in the known_hosts file

This function updates a host's entry in the cPanel account's /home/user/.ssh/known_hosts file.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: host_name=host.example.com The host to update.
port	integer [ 1 .. 65535 ] Default: 22 Example: port=1234 The SSH port to use.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  KnownHosts \
  update \
  host_name='host.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "update",
"module": "KnownHosts",
"result": {"data": {"host": [{"host": "host.example.com",
"key": "ssh-rsa AAAAB3NzaC1yc2AEEEEDAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
"line": "host.example.com ssh-rsa AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"meta": {"algorithm": "ssh-rsa",
"body": "EEEEB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9\\bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
"md5": "b6030e39868ed0e724cea3773e014219",
"md5-printable": "MD5:b6:03:0e:39:97:2e:d0:e7:24:ab:c3:77:3d:01:42:09",
"sha256": "55a405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b3b3fc55",
"sha256-printable": "SHA256:RPLFvPThGrW4RuWLoL9tq9I9zJ42fK3XywyRtbOz/EQ"
}
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Validate host

This function checks whether a host's public key exists in the cPanel account's /home/user/.ssh/known_hosts file.

Authorizations:

BasicAuth

query Parameters

required	string or string Example: host_name=host.example.com The host to query.
port	integer [ 1 .. 65535 ] Default: 22 Example: port=1234 The SSH port to use.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  KnownHosts \
  verify \
  host_name='host.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "verify",
"module": "KnownHosts",
"result": {"data": {"errors": ["The example.com host does not exist in the known_hosts file."
],
"failure_type": "new",
"host": [{"host": "host.example.com",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==",
"line": "host.example.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==",
"meta": {"algorithm": "ssh-rsa",
"body": "AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==",
"md5": "b6030e39979ed0e724cea3773e014209",
"md5-printable": "MD5:b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09",
"sha256": "44e405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b3b3fc44",
"sha256-printable": "SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ"
}
}
],
"status": 0
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Login Information

Security / Login Information

Return last authenticated login IP address

This function returns the IP address of the user who most recently logged in.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LastLogin \
  get_last_or_current_logged_in_ip

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_last_or_current_logged_in_ip",
"module": "LastLogin",
"result": {"data": ["192.168.0.1"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return web server's hostname

This function retrieves a web server's hostname.

Authorizations:

BasicAuth

query Parameters

name	string Default: "host" Value: "host" Example: name=host The web server environment variable to retrieve. You can only retrieve the web server's hostname. `host` is the only possible value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Variables \
  get_session_information

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_session_information",
"module": "Variables",
"result": {"data": {"host": "example.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

cPanel Server Information

Server Information / cPanel Server Information

Return service and device status

This function returns the status of each cPanel service (daemon), device, and server health check point on your server.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ServerInformation \
  get_information

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_information",
"module": "ServerInformation",
"result": {"data": [{"name": "apache_php_fpm",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "cpanel-dovecot-solr",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "cpanellogd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "cpdavd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "cphulkd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "cpsrvd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "crond",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "dnsadmin",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "exim",
"status": 1,
"type": "service",
"value": "up",
"version": "exim-4.92-1.cp1180.x86_64"
},
{"name": "ftpd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "httpd",
"status": 1,
"type": "service",
"value": "up",
"version": "2.4.39"
},
{"name": "imap",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "ipaliases",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "lmtp",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "mailman",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "mysql",
"status": 1,
"type": "service",
"value": "up",
"version": "5.7.25"
},
{"name": "named",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "nscd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "pop",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "queueprocd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "rsyslogd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "spamd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "sshd",
"status": 1,
"type": "service",
"value": "up"
},
{"name": "Server Load",
"status": 1,
"type": "metric",
"value": "1.73"
},
{"name": "CPU Count",
"status": 1,
"type": "metric",
"value": "2"
},
{"name": "Memory Used",
"status": 1,
"type": "device",
"value": "44.12%"
},
{"name": "Swap",
"status": 1,
"type": "device",
"value": "0.73%"
},
{"name": "Disk / (/)",
"status": 1,
"type": "device",
"value": "26%"
},
{"name": "Disk /tmp (/tmp)",
"status": 1,
"type": "device",
"value": "0%"
},
{"name": "Disk /var/tmp (/var/tmp)",
"status": 1,
"type": "device",
"value": "0%"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return server's configuration settings

This function retrieves the configuration settings for the cPanel & WHM server on which an account exists. This is useful, for example, to verify which applications and functionality are available on the account.

Authorizations:

BasicAuth

query Parameters

name

string

Possible Values: "default_theme" "email_filter_storage_directory" "allow_park_subdomain_on_hostname" "allow_remote_domains" "allow_unregistered_domains" "apache_port" "apache_ssl_port" "api_shell" "awstats_browser_update" "awstats_reverse_dns" "cpanel_root_directory" "database_prefix_required" "display_cpanel_doclinks" "dnsadmin_app" "empty_trash_days" "enable_file_protect" "file_upload_maximum_bytes" "file_upload_must_leave_bytes" "file_usage" "ftp_server" "htaccess_check_recurse" "invite_sub" "ipv6_listen" "local_nameserver_type" "logout_redirect_url" "mailbox_storage_format" "mail_server" "minimum_password_strength" "minimum_password_strength_mysql" "mysql_host" "mysql_version" "php_maximum_execution_time" "php_post_maximum_size" "php_system_default_version" "php_upload_maximum_filesize" "php_loader" "php_open_basedir_home" "phpmyadmin_disable_search_info_schema" "docroots_in_public_html_only" "require_ssl" "allow_reset_password" "allow_reset_password_for_subaccounts" "disable_analog" "skip_apache_clients_optimizer" "disable_awstats" "skip_mailbox_warnings_check" "disable_boxtrapper" "skip_bandwidth_limit_check" "disable_mailman" "disable_roundcube" "disable_spamassassin" "disable_spambox" "disable_webalizer" "ssl_default_key_type" "use_information_schema" "use_mail_for_mailman_url" "is_mod_userdir_enabled" "version"

Examples:

name=name=allow_park_subdomain_on_hostname&name=allow_remote_domains&name=allow_reset_password - Get multiple configuration settings.
name=allow_park_subdomain_on_hostname - Get a single configuration setting.

The server configuration settings to return.

Click to view information about the available server configuration settings.

default_theme - The cPanel interface's default theme.
email_filter_storage_directory - The location of the Exim email filter storage directory.
allow_park_subdomain_on_hostname - Whether the system allows users to park subdomains of the server's hostname.
allow_remote_domains - Whether the system allows users to create addon domains or aliases that resolve to other servers.
allow_unregistered_domains - Whether the system allows users to add domains they didn't register with a domain name registrar.
apache_port - The IP address or IP address with a firewall port number that Apache® uses to listen for requests and serve web pages over an unsecured connection.
apache_ssl_port - The port or IP address that Apache uses to listen for requests and serve web pages over a secure connection.
api_shell - Whether the user can access cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell).
awstats_browser_update - Whether the user can update their AWStats software.
awstats_reverse_dns - Whether the AWStats statistical analysis software interprets visitors' domain names as IP addresses.
cpanel_root_directory - The cPanel root directory.
database_prefix_required - Whether the account requires database prefixing.
display_cpanel_doclinks - Whether the system displays links to cPanel feature documentation in the cPanel interface.
dnsadmin_app - The application that processes DNS management requests.
empty_trash_days - The minimum age of files that the system will automatically purge from .trash folders in user home directories.
enable_file_protect - Whether EasyApache 4's FileProtect option is enabled.
file_upload_maximum_bytes - The maximum file size, in megabytes (MB), that a user can upload to a server.
file_upload_must_leave_bytes - The minimum filesystem quota that the system requires after a file uploads to a server.
file_usage - Whether file usage information displays in the cPanel Home interface's statistics bar.
ftp_server - The FTP server.
htaccess_check_recurse - The maximum number of directories deep to look for .htaccess files when you change the PHP handler.
invite_sub - Whether cPanel account users can send invitations to new Subaccount users via cPanel's User Manager interface (cPanel >> Home >> Preferences >> User Manager).
ipv6_listen - Whether the cpsrvd daemon and other cPanel & WHM services listen on IPv6.
local_nameserver_type - The DNS nameserver's type.
logout_redirect_url - The logout redirection URL.
mailbox_storage_format - The mailbox storage format for new accounts.
mail_server - The mailserver type.
minimum_password_strength - The minimum strength for cPanel account passwords.
minimum_password_strength_mysql - The minimum strength for MySQL® or MariaDB® passwords.
mysql_host - The MySQL or MariaDB hostname or IP address.
mysql_version - The MySQL or MariaDB version.
php_maximum_execution_time - The number of seconds that a PHP script can run before the system terminates it.
php_post_maximum_size - The maximum size, in megabytes (MB), of a POST request.
php_system_default_version - The system's default version of PHP.
php_upload_maximum_filesize - The maximum file size, in megabytes (MB), that a PHP script may upload.
php_loader - The PHP loaders through which the system executes internal PHP scripts.
php_open_basedir_home - Whether PHP open_basedir protection is enabled on the server.
phpmyadmin_disable_search_info_schema - Whether the user can search for the phpMyAdmin information schema.
docroots_in_public_html_only - Whether the system restricts users from creating addon domains and subdomains outside of their public_html directory.
require_ssl - Whether the system requires passwords and other sensitive information use SSL encryption.
allow_reset_password - Whether cPanel's Reset Password feature is enabled for the account.
allow_reset_password_for_subaccounts - Whether cPanel's Reset Password feature is enabled for subaccounts on the account.
disable_analog - Whether users can access the Analog Stats interface (cPanel >> Home >> Metrics >> Analog Stats).
skip_apache_clients_optimizer - Whether the Apache Client Optimizer is enabled.
disable_awstats - Whether the AWStats software is enabled.
skip_mailbox_warnings_check - Whether mailbox usage warnings are enabled.
disable_boxtrapper - Whether BoxTrapper is enabled.
skip_bandwidth_limit_check - Whether the system automatically suspends HTTP service for accounts that exceed their bandwidth limit.
disable_mailman - Whether Mailman mailing lists are enabled.
disable_roundcube - Whether Roundcube webmail is enabled.
disable_spamassassin - Whether the Apache SpamAssassin™ spam filter is enabled.
disable_spambox - Whether Apache SpamAssassin's spam box feature is enabled.
disable_webalizer - Whether the Webalizer statistics program is enabled.
ssl_default_key_type - The default SSL/TLS encryption algorithm used by the system.
use_information_schema - Whether the system uses the MySQL® INFORMATION_SCHEMA view. This view includes disk usage by all MySQL tables in the disk usage totals.
use_mail_for_mailman_url - Whether the system prefixes Mailman URLs with the mail prefix. For example, http://mail.domain.com/mailman.
is_mod_userdir_enabled - Whether the Apache mod_userdir Tweak is enabled.
version - The system's Linux® kernel version.

Note:

If you don't use this parameter, this function returns all of the server's configuration settings.
To retrieve multiple variables, increment this parameter. For example, name-1=variable, name-2=variable, name-3=variable.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Variables \
  get_server_information

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_server_information",
"module": "Variables",
"result": {"data": {"allow_park_subdomain_on_hostname": 0,
"allow_remote_domains": 1,
"allow_reset_password": 1,
"allow_reset_password_for_subaccounts": 1,
"allow_unregistered_domains": 1,
"apache_port": "192.0.2.0:80",
"apache_ssl_port": "192.0.2.0:443",
"api_shell": 0,
"awstats_browser_update": 0,
"awstats_reverse_dns": 0,
"cpanel_root_directory": "/usr/local/cpanel",
"database_prefix_required": 1,
"default_theme": "jupiter",
"disable_analog": 0,
"disable_awstats": 0,
"disable_boxtrapper": 0,
"disable_mailman": 0,
"disable_roundcube": 0,
"disable_spamassassin": 0,
"disable_spambox": 0,
"disable_webalizer": 0,
"display_cpanel_doclinks": 0,
"dnsadmin_app": "dnsadmin",
"docroots_in_public_html_only": 1,
"email_filter_storage_directory": "/etc/vfilters",
"empty_trash_days": "disabled",
"enable_file_protect": 1,
"file_upload_maximum_bytes": null,
"file_upload_must_leave_bytes": 5,
"file_usage": 0,
"ftp_server": "disabled",
"htaccess_check_recurse": 2,
"invite_sub": 1,
"ipv6_listen": 0,
"is_mod_userdir_enabled": 1,
"local_nameserver_type": "powerdns",
"logout_redirect_url": "https://cpanel.net",
"mail_server": "dovecot",
"mailbox_storage_format": "maildir",
"minimum_password_strength": 65,
"minimum_password_strength_mysql": 65,
"mysql_host": "localhost",
"mysql_version": "5.7",
"php_loader": "ioncube",
"php_maximum_execution_time": 90,
"php_open_basedir_home": 0,
"php_post_maximum_size": 55,
"php_system_default_version": "ea-php73",
"php_upload_maximum_filesize": 50,
"phpmyadmin_disable_search_info_schema": 0,
"require_ssl": 1,
"skip_apache_clients_optimizer": 0,
"skip_bandwidth_limit_check": 0,
"skip_mailbox_warnings_check": 1,
"ssl_default_key_type": "rsa-2048",
"use_information_schema": 1,
"use_mail_for_mailman_url": 0,
"version": "3.4"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Notifications

The Notifications module for UAPI.

Return server notifications total

This function returns the number of server-wide notifications on an account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Notifications \
  get_notifications_count

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_notifications_count",
"module": "Notifications",
"result": {"data": 3,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Password Strength

Server Information / Password Strength

Return minimum required password strength

This function retrieves an application's minimum required password strength.

Authorizations:

BasicAuth

query Parameters

app

required

string

Possible Values: "cpaddons" "createacct" "ftp" "htaccess" "mysql" "passwd" "pop" "postgres" "sshkey" "webdisk" "virtual"

Example: app=webdisk

The application's name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PasswdStrength \
  get_required_strength \
  app='webdisk'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_required_strength",
"module": "PasswdStrength",
"result": {"data": {"strength": 0
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

SSH

The SSH module for UAPI.

Return whether cPanel account has shell access

This function returns whether the cPanel account has shell access and the account's shell path.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSH \
  get_shell

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_shell",
"module": "SSH",
"result": {"data": {"has_terminal_access": true,
"shell": "/bin/bash"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return SSH port

This function retrieves the server's SSH port.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSH \
  get_port

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_port",
"module": "SSH",
"result": {"data": {"port": 22
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

ServiceProxy

The ServiceProxy module for UAPI.

Return a cPanel account’s service proxying setup

This function reports a cPanel account's service proxying configuration.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ServiceProxy \
  get_service_proxy_backends

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_service_proxy_backends",
"module": "ServiceProxy",
"result": {"data": [{"backend": "example.com",
"service_group": "Mail"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove cPanel account service proxying

This function removes a cPanel account's service proxying.

Note:

If the Web Server role is active on the server, this function rebuilds the cPanel user's web virtual hosts (vhosts) and restarts the web server.
If the system cannot rebuild the cPanel user's vhosts, the API call will still succeed. However, the function returns a failure warning in the metadata.
To set a service proxying for a cPanel account, use the UAPI set_service_proxy_backends function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ServiceProxy \
  unset_all_service_proxy_backends

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unset_all_service_proxy_backends",
"module": "ServiceProxy",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Add cPanel account service proxying

This function lets you configure a cPanel account's service proxying.

Note:

If the Web Server role is active on the server, this function rebuilds the user's web virtual hosts (vhosts) and restarts the web server.
If the system cannot rebuild the user's vhosts, the API call will still succeed. However, the function returns a failure warning in the metadata.
To remove an account's service proxying, use the UAPI unset_all_service_proxy_backends function.

Authorizations:

BasicAuth

query Parameters

	string or string The hostname or IP address to assign as the server that handles the account's service proxy requests. This parameter defaults to the existing service proxy configuration, if one exists.
service_group	string Value: "Mail" Examples: service_group=Mail&service-group-1=Mail&service-group-2=Mail - Add multiple service backend groups. service_group=Mail - Add a single service backend group. The name of a service group for which to assign a proxy backend. The corresponding `service_group_backend` value will be the service group's new proxy backend. `Mail` — The Mail service group. This parameter defaults to the existing setting, if one exists. Note: When you call this parameter, you must include a corresponding `service_group_backend` value. To add multiple `service_group` values, increment the parameter name. For example, `service_group`, `service_group-1`, and `service_group-2`.
	string or string Examples: service_group_backend=mail.example.com&service_group_backend-1=mail.example1.com&service_group_backend-2=mail.example2.com - Add multiple service group backend servers. service_group_backend=mail.example.com - Add a single service group backend server. The hostname or IP address of the server to assign as the corresponding `service_group` value's proxy backend server. This parameter defaults to the existing setting, if one exists. Note: When you call this parameter, you must include a corresponding `service_group` value. To add multiple `service_group_backend` values, increment the parameter name. For example, `service_group_backend`, `service_group_backend-1`, and `service_group_backend-2`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ServiceProxy \
  set_service_proxy_backends

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_service_proxy_backends",
"module": "ServiceProxy",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Auto-generated SSL Certificates

SSL Certificates / Auto-generated SSL Certificates

Disable AutoSSL for domains

This function disables AutoSSL for the domains that you specify.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains

required

string <domain>

Example: domains=example.com,example2.com

A comma-separated list of domains for which to disable AutoSSL.

Note:

For browser-based calls, use a URI encoded comma (%2C).

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  add_autossl_excluded_domains \
  domains='example.com,example2.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_autossl_excluded_domains",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return AutoSSL disabled domains

This function lists the domains with AutoSSL disabled.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  get_autossl_excluded_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_autossl_excluded_domains",
"module": "SSL",
"result": {"data": [{"excluded_domain": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domains with AutoSSL problems

This function retrieves a list of domains that possess AutoSSL problems.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  get_autossl_problems

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_autossl_problems",
"module": "SSL",
"result": {"data": [{"domain": "example.com",
"problem": "example.com contains 400 domains, which exceeds the maximum number (200) of domains allowed for the \"Sectigo\" AutoSSL provider. This system will include those 200 domains on the certificate that appear to be the website's most important. To allow AutoSSL to secure each domain, divide the 400 domains among separate websites. (The websites can all serve the same content from the same document root.)",
"time": "2018-06-07T05:30:09Z"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether AutoSSL check in progress

This function verifies whether the autossl_check task is in progress for the current user.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  is_autossl_check_in_progress

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_autossl_check_in_progress",
"module": "SSL",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable AutoSSL for specifed domains

This function enables AutoSSL for the domains that you specify.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Examples:

domains=domains=example1.com,example2.com - Multiple domains.
domains=example.com - A single domain.

Enable AutoSSL for this domain.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  remove_autossl_excluded_domains \
  domains='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "remove_autossl_excluded_domains",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable AutoSSL for specifed domains

This function disables AutoSSL for every domain that you specify.

Warning:

This function replaces the list of any domains that you previously excluded. To add domains to the list of excluded domains, use the UAPI function SSL::add_autossl_excluded_domains.

Important:

When you disable the the Calendar and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains

string

Example: domains=example.com,example.net

A comma-separated list of domains for which to disable AutoSSL.

Note:

If you do not include this parameter, the function will enable AutoSSL for every domain on the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  set_autossl_excluded_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_autossl_excluded_domains",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start AutoSSL for current user

This function initiates an AutoSSL check for the user.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  start_autossl_check

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "start_autossl_check",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

cPanel Account SSL Management

SSL Certificates / cPanel Account SSL Management

Return whether domains can redirect to secure URL

This function determines whether the system can automatically redirect domains on a cPanel account to use SSL.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  can_ssl_redirect

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "can_ssl_redirect",
"module": "SSL",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether shared SSL certificate exists Deprecated

This function checks whether a shared SSL certificate is associated with the account.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  check_shared_cert

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_shared_cert",
"module": "SSL",
"result": {"data": 0,
"errors": null,
"messages": null,
"metadata": { },
"status": 0,
"warnings": null
}
}

Remove SSL for domain

This function removes SSL from a domain.

Note:

This function removes domains from the current certificate to end SSL coverage for those domains. To delete certificates from SSL storage, use the UAPI function SSL::delete_cert instead.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

The domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  delete_ssl \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_ssl",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": ["The SSL host was successfully removed."
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Request best SSL certificate

This function retrieves the best-available certificate for the domain. The function also retrieves the certificate's associated private key and CA bundle, if available.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

The domain name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  fetch_best_for_domain \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_best_for_domain",
"module": "SSL",
"result": {"data": {"cab": "-----BEGIN CERTIFICATE-----\nMIID/DCCAuSgZwBBAvIFANEXIaYwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL\nZXhhbXBsZS5jb20wHhcNMjAwNDA2MTY0NDU2WhcNMjEwNDA2MTY0NDU2WjAWMRQw\nEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBALuCGWz/aFOr5TPBehISu3LkcGvnNFg9eY8rVXbNFfpBzyzdWrx5IiMtBcDx\nAZXMOU7GSZyFhSB6cjNfCaESXC/gBTa0sZ/b4b4etNUlNHUFAatb9WckQ6AtWbVA\npxu8aw/5AjAKgMbkaNrUY3vzLzin11CyGOFkbAKwVqT13Z3Yyz/xuz7x2+yMwPBh\n9mEP0tXjvCz7NzETFSTysn9Sf+VjUle0upnpl8Q7GK52CDpvwdqE/O6MrTx/XrXm\nYUfeSkZd+nqFm4oxmrf01hOL2IlEit1RupILwVm2/8CK2sAdazTqh4LapA962b9V\nSKm31YbsGT3kQg5EERbjIgiN6M8CAwEAAaOCAU8wggFLMB0GA1UdDgQWBBRhFUQb\nh7YE6tgcpiHke60td96d4zAJBgNVHRMEAjAAMEIGA1UdIwQ7MDmAFGEVRBuHtgTq\n2BymIeR7rS133p3joRqkGDAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbYIFANEXIaYw\nHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMIG7BgNVHREEgbMwgbCCC2V4\nYW1wbGUuY29tghBtYWlsLmV4YW1wbGUuY29tgg93d3cuZXhhbXBsZS5jb22CEmNw\nYW5lbC5leGFtcGxlLmNvbYITd2VibWFpbC5leGFtcGxlLmNvbYITd2ViZGlzay5l\neGFtcGxlLmNvbYIWY3Bjb250YWN0cy5leGFtcGxlLmNvbYIXY3BjYWxlbmRhcnMu\nZXhhbXBsZS5jb22CD3dobS5leGFtcGxlLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEA\nT0TaI0ypM3eqtRSddgyoy5+nXi8a9a8xFKrwEAljBua3rNR6fOfedMOg9NFwCmQD\nw96/eZJjq+xMh57yLEGu05OBbyFVsdu2AXVhwHeBaURrGn5p7IjNM+dB+ld+oCnP\nex6iisbsfxwUqa7y2vqTU5XaUiXfccqEz8ofvuTcqNs8bgGn0Tm90XbgGnPVd7zl\nGm4t7Gf2pvMNd2R1prJ07z42bp/z8E2DcFhb/QZnblFOhJ8jPspxYK4G5XmwwYZD\n79NDK47OyG3hTiinxroKMjqIgnLT7ZabDMGHJkcg5xOL/VdYi7ZGHAnBEwA8eadO\ndh3jFPxGGIBJTTmKIScSrm==\n-----END CERTIFICATE-----",
"crt": "-----BEGIN CERTIFICATE-----\nMIID/DCCAuSgZwBBAvIFANEXIaYwDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UEAwwL\nZXhhbXBsZS5jb20wHhcNMjAwNDA2MTY0NDU2WhcNMjEwNDA2MTY0NDU2WjAWMRQw\nEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBALuCGWz/aFOr5TPBehISu3LkcGvnNFg9eY8rVXbNFfpBzyzdWrx5IiMtBcDx\nAZXMOU7GSZyFhSB6cjNfCaESXC/gBTa0sZ/b4b4etNUlNHUFAatb9WckQ6AtWbVA\npxu8aw/5AjAKgMbkaNrUY3vzLzin11CyGOFkbAKwVqT13Z3Yyz/xuz7x2+yMwPBh\n9mEP0tXjvCz7NzETFSTysn9Sf+VjUle0upnpl8Q7GK52CDpvwdqE/O6MrTx/XrXm\nYUfeSkZd+nqFm4oxmrf01hOL2IlEit1RupILwVm2/8CK2sAdazTqh4LapA962b9V\nSKm31YbsGT3kQg5EERbjIgiN6M8CAwEAAaOCAU8wggFLMB0GA1UdDgQWBBRhFUQb\nh7YE6tgcpiHke60td96d4zAJBgNVHRMEAjAAMEIGA1UdIwQ7MDmAFGEVRBuHtgTq\n2BymIeR7rS133p3joRqkGDAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbYIFANEXIaYw\nHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMIG7BgNVHREEgbMwgbCCC2V4\nYW1wbGUuY29tghBtYWlsLmV4YW1wbGUuY29tgg93d3cuZXhhbXBsZS5jb22CEmNw\nYW5lbC5leGFtcGxlLmNvbYITd2VibWFpbC5leGFtcGxlLmNvbYITd2ViZGlzay5l\neGFtcGxlLmNvbYIWY3Bjb250YWN0cy5leGFtcGxlLmNvbYIXY3BjYWxlbmRhcnMu\nZXhhbXBsZS5jb22CD3dobS5leGFtcGxlLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEA\nT0TaI0ypM3eqtRSddgyoy5+nXi8a7a6xFKrwEAljBua3rNR6fOfedMOg9NFwCmQD\nw96/eZJjq+xMh57yLEGu05OBbyFVsdu2AXVhwHeBaURrGn5p7IjNMjdB+ld+oCmU\nex6iisbsfxwUqa7y2vqTU5XaUiXfccqEz8ofvuTcqNs8bgGn0Tm90XbgGnPVd7zl\nGm4t7Gf2pvMNd2R1prJ07z42bp/z8E2DcFhb/RPnblFOhJ8jPspxYK4G5XmwwYZD\n79NDK47OyG3hTiinxroKMjqIgnLT4ZabDMGHJkcg5xOL/VdYi7ZGHAnBEwA8eadO\ndh3jFPxGGIBJTTmKIScSbg==\n-----END CERTIFICATE-----",
"crt_origin": "username",
"domain": "example.com",
"ip": "192.168.0.1",
"key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBBCKAAQNAu4IZbP0oU6vlM8F6EhK9cuRrs+c1WD24jytPds0V+kH+LN1a\nvHkiIy0FwPABlcw5TrZJnIWFIHpyM18JoRJcM+AFNrSxn9vhvh601SU0dQUBq1v1\nZyRDoC1ZtUCnG7xrD/kCMAqAxuRo2tRje/MvOKfXULIY4WRsArBWpPXdndjLP/G7\nPvHb7IzA8GH2YQ/S1eO8LPs3MRMVJPKyf1J/5WNSV7S6memXxDsYrnYIOm/B2oT8\n7oytPH9eteZhR95KRl36eoWbijGat/TWE4vYiUSK3VG6kgvBWbb/wIrawB1rNOqH\ngtqkD3rZv1VIqbfVhuwZPeRCDkQRFuMiCI3ozwIDAQABAoIBAFADflIS0zQRQCdL\nwol/0NmAPbDt4lpdMUg0161wapZ2CrA8bQHMNxMHnVLuBR0lHrdMyhCusVZgqebe\nAT/ok8oiMFdd2AY9UCFO/R+PVskwr7ut7BRtVyY88/Dye9zMFGumeJaDhNxaj5wB\n0coMxfPJO4pF1XQo5CZplS+jc0RtiNnRmWP/zwwtH+QwT43GXKS3U3QgX1a/7Yzw\nliUFuggsjysNPovM5NzcgzYfVlMg3F9fDnMeve2s/MO6/wCIp1+SHN89DwluDmw0\nII0sJDtBRB1nPqseLV1XwYImdSosKuaUIK225vQy/cXK9S/zcq6+d6P5efCw8nRg\nbCfwd7ECgYEA8Agkx+P7zBAWItnkrNzah6QaWd3VP5bSw6WeHwcWIS1h3ASKSr3u\nT8rp5qDTk92eV/g5Uqr5lr8txnp448wnipeK0LDF4r+uhOsHOY4B4eFiTsRecXKD\nzlcC/ees4UOzbdptqosyAG5ub8UMwEH0zPOCszpnIhZkm004EHxc8zUCgYEAx/t0\nF1DYHm834CYyHfq3XiuB3yNECKMQZ1lgcq8IXaO3EJKnaSF3INogS1lZ6hQR2AW+\ntr+U6LdBRzsxH0ZeHu/lYCZ6ssgV3H6HTLlFVRysufVdlLaeaKAMuEADrUhVgvVA\n8rNM+8WSxrfya+2a/PwyJD9YdHCITcXVdwHHCHMCgYBLhYRtECJNVlJgrMXyTZrE\nSrGvzMgntcCiph1WDdi8n5bGrvcEBTZSDLoDQl7Pi08ixorio8Db2VMBu88FfVqD\nlKKsfrIEYeL7FyeyyCd3dn6D4e0FLM6jwWTDln0iczalPbB7lEgrMpO0vv8ADsCD\nK6rX1ZxZoWoOQwF8zmRAcQKBgQC85weoJpOfXAt5zlq1+ulPKOXKs3NGfVG3bjOp\n4SuT2FvKad19b0EqZSDzR/ylIkQgvHyD/8BXexNMh9tE4aFys8UF6BMq4dnUqCiC\nDtgxJ575IY8+NKq5xcV+HenbO2KbC7RIDZqAkQauc3+o947ZvhhXKQcTJmF6pY+Y\nlLM/hQKBgQCplo1rGsimNitBb2iw2B+jDJoMBLYjWeZWcr8VMwVlN9DXPG19uXKq\nCsbrteMX3VedbeRYk/NITsasRefZq7JDSe9JbsPxj3I+/nzV0EbMXX9cxJL3hkCc\n5QAmE/BMR7yh0odK57o+mcQZtecIEO1BK/qW6Au0otQHPraygGCwkQ==\n-----END RSA PRIVATE KEY-----",
"key_origin": "username",
"searched_users": ["username"
],
"status": 1,
"statusmsg": "ok",
"user": "username"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return SSL certificate information for all FQDN

This function retrieves the certificate information for all fully qualified domain names (FQDNs) that the account owns.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Examples:

domains=domains=example1.com,example2.com - Multiple domains.
domains=example.com - A single domain.

A domain or comma-delimited list of domains for which to retrieve information.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  fetch_certificates_for_fqdns \
  domains='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_certificates_for_fqdns",
"module": "SSL",
"result": {"data": [{"cab": "-----BEGIN CERTIFICATE-----\nMIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD\nVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv\nb3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV\nUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU\ncnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv\nRLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M\nypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5\n1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz\ndcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl\nIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy\nbW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY\n-----END CERTIFICATE-----",
"created": 1496950287,
"crt": "-----BEGIN CERTIFICATE-----\nMIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJ\nc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQI\nDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYy\nMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNV\nBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0G\nCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3P\nXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fW\nvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/da\nM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC\n+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6\nPLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGj\nUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw\n+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA\nA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3Wh\ncDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVw\nFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh\n/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2ag\nqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPa\nKm6r7YmwfLN/YMZBHXSR58oOGP9W\n-----END CERTIFICATE-----",
"domain_is_configured": 1,
"domains": ["example.servername.com",
"example.com",
"mail.example.com",
"www.example.com",
"www.example.servername.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "Cert for example.servername.com",
"id": "example_servername_com_ce52d_6e643_2813308004_119580f9b01960cjones72bc519206bc",
"is_self_signed": 1,
"issuer.commonName": "example.servername.com",
"issuer.organizationName": "Organization",
"issuer_text": "stateOrProvinceName\\nTX\\nlocalityName\\nHouston\\ncountryName\\nUS\\ncommonName\\nexample.com\\norganizationName\\ncPanel",
"key": "-----BEGIN RSA PRIVATE KEY-----\nMIIJJwIBAAKCAgEA4yilqsoCdEpiNOyLcPJ4FLT7vgwaLdOBeJLTMUeV2uZM4v65/tiZe7H0soDp1C55SCr3uEIEa7Lq7RUZ+F5p67BgRR19rmerKGxfN7N5Vu97pfTwW1f+lVsxUF/56lVeoAmm4okU98xJHiGGlI8ZHGJbUMYfLPy0OrA+gNwMHqMVOv1BSgpbEWCILMvnvtp0rwPutjnPVX2Dj40ia40L4Wqvp+0Yg7mZyhIOl+q6VZVIdXZslR4ZywfRBYt3ieFBDYMyNw9wN3Xy44fCpHc77+ho84W3BqrGaWSSDyf6UkZGD5mfohGf2JSp+c8J6H7hsxo7pta3K1diVXFOSfnaA+k56zW445XruwYs/SN/zvGetGi6uqhMAcVRQcYCmLCixcC6RkcUx3exxgR4q3gthDnFvWC4+NuTh8/K0BcxcuCEhRug/MfVfO3+f7RJFSJPFb9m9Lf4HHBSVkDP5WtG4XiBKCe++9Wuvxbd4QxS7YrnSopNKxkuHKswH8ONpADMYDqfLODMhNrslHNHu95Nv7AlQr8weLqMGWMp7GFqzXcl39RnVkF4Bxd3bAAsMN8/JvanMKCPjTTDrfzVFZcmHXPYOljYDdY1xfIstYVtbyFkUHZP2RPPBaPUAt90lzrKGVF8a2vdIKRiey5SZ5qu9c/mGri3oz7Lkk7qkNPAqDMCAwEAAQKCAgA3f9raG3j2CKZt381Bzzvfc0h+al6LC736Q4Ut6RuH2/S1ER9IUItPWW87nZuDp8ciBr13W0nRNmmHezxZHlgqqXEb8dSfI90Bh1jMNyFSSDihl3KSHrGotBscVBavViREXZdUicGBuXuxtkYno96yvKUq2v0K9MLkA+OBgEHFynqJaw7klBsj573dlAQO8TjI+eD8zKsHbB8Ul5rtRAy/Cl3YXWk75cDZSggevc7A0jRd3o0w8aXDoSlEfYq7OTm3n3JJWZBFPKAXTzgTDr6qItJhjS4IxXsq7RNyeIYES/8aGKKT6lJvjALrcdYt47IpHCOu447lG/h+f6xtDophLGZoAirO7lJFRVfLJh76sLF12bpXJKbbmMN+aut0nM+MLEw8A5K9OV24jJ/3+afj//5789asIyvNaQFPOX23SdLX0QbA5QWvJt2tWvvpS3ubcIJaBEMTK8asEBC68eUW0BBKJaSiYNzecUFYCBjQlxKsIrYuWZoW6fMyRel+cnqMdiH7r2p6RmgF5c9myDwq3E47jE+VrOy8uhw7EMQvT8+YSKaIbgtFZcUSU02BDRB7gWNa842m6nGs5tj5xFNQ6Wt410vilTwL+6zCQqJaKmcdE3woiIgSdrw5MssAHHjqo7QJthZfbpUAUTc6jGPNO13U1ediIRAGdQW5ALqTwQKCAQEA884bmFFZLTewHIv1PJFfNxVZfk3C7LhWE2JcI/5P/YrN4ZA8G08OYhgxqa5XnsHHQPwMM85i1HeOoPwqgTMIyLDX/Sf88+eW3ef4V2M1Y4op0ahWFEwbwXKGxOhncElObN7dfZUwVlxCReaiw2XQAGRqtQC0f+9dZysqPJr+Rz6poTiOtm7DcpW/WiGfBPvVhzBENyqouL9V3vCWYPJSLtCexECoGoPSpHKgUkwbh3+ra8SfG6FOIBj4PpMB82R7oPDjIyXF1VDfb0EwYQlKxyZoP9+NPT2MhZv/hF/Mbm/5LolVHx92hO9q6yxS6nvaFmEPr9fY1EOTWzzPOA+VyQKCAQEA7oVioaTqxENt+wHITZq100iYUpm4X1N1eENTp97QyQbQOVR/t8iGLUdvOZdIxBSTS3JFQ8TNcGDPPc+o319QGdZABNnKwFGY3Ss+5QgVeX6n0WKdxCRelUOUB174aBeXcJCKplh6xBUrLfSZxvZQQb7fv0Mb+2eKUBKTymvES1kpYdn1T0vCCHA3bVpaHuqliCoDSX3RmQICZlfSgCGBbAkmU8RuxDd9yR9l7O9MXUmLsqlsw6hvbUt+7Y13YlDtyX8gbCwEEYsoALOotY1xNfXnyZKTAXhrg+xsQLrURYZUoZiCJyK/mHCWRTPVkt89wq4IexbJ9hqlRjzpmlr8GwKCAQBxRSCs855q06SOnrehHCkQfmrFs3sMX9gdyWTllBG1yfc9BLXoOiKEkJkCLG2o5H6eQnuo1go0jBdH0+ArhnpeQ0sV4q4y4zXEgzFt6Dm1tUsYjQzxASskBQF4GkF0eZpmGmTtI5MBjHt93llgTr0EcaLh1SIHDj5m4DcPUTMyBnro3E3xlCRZ6Biu10/6EMZzuIj42Gjq7HoIyd4TzIFCHsqkgyWWrAgBPwAdPB7OJRKPTxpcy+RwJSmwaLxPSC/n5gKhIbt4D8q+9Zp0esyzGbT1d/c2rJHMwV1FMvzXkk5CwKs7enKl8FXMTRt4tXHtU8rl93JVq8+aY/YiJZuBAoIBAERG2lz7IFjeFHVtpTDRwIqilTfP2P8wnMe4PhInrgxdbu16SrUJKZ98e1I5BBNc8G0AYONtSoGItMo0z1phpkQ/GERLM8aplOB6qJ5XGg6VOuStHgwvfQOtPIp/nQvu9OK7/XRwj3Phu2KESiCyEXdAdDwDsdbdZLJXHwcqoh4Pf9EK2zW/seNIfBVJb9K5yHiZzicTZRQvhxBUw2T6MloCpH4GFM8GM3OHEV4pgeqSSvLxnLjFVmAq5EKL5Ei4cdjkExvj3aZH90N8KicOPgH8SkVhN8OL/Prein5c/LaKJV+8kEUzpTS1xc45cEGCteMsfjD97QINzpG0jgopUVECggEADIaKsx8NUQT3hm0wHRanEFJnQH5HzxaQjWbsjm2uz0KROPNIK1X5L8kypsb+EzlJtvWUqxPaOaTv4DZVpFaVzk8/2PPGsYR3mUjqMqNFYMrNwYZAXvJ/huzDPqq6+w2Pn9jcAifHNw3S8UR650v8gl7BU4fVBvhamG8JelvwLqeGWoikST9NBXVqG5IKBpUkUiFOMUNmRih9ooKvhy7GosoK8MWbmhWo1v8TTSXSagACUhAoIzb6mMN/VFC5WDbFx5AEB/G9tq/zmTqQkuo39dvgl30wyZGRNwc1aFf1Kxeven10/JN9ipp0mTa7NYSdn0RAe9ZRp5cCkgmktqmB0g==\n-----END RSA PRIVATE KEY-----",
"key_algorithm": "rsaEncryption",
"modulus": "ce52db786fd2776f69057ed8ee0d8ab267a2f328a66a3afd8\n76017a99d061ec5d24d646f80ec258c696cb742e2bcd2fef920177144d9126a4\n779c1a21ca5589ff06e673556116903493100dfba385a62d11aeec57f47e5b20\nad8d1142fbe93f003fb62403cdcc0012ccd407009ac21639623bc52a5d6d3814\nff9c45a7c246799f0229b4854af2aeddfa755ab13814132424f5b1680f2c357e\n1476af7422bd5863102cfc5982b3ddad7fecdeae5c1cb73789008be9ce2f24fe\n27c9202b3bca6524ba29a30972f14cbf06f0a1b7998c2361ed90221f40829faf\n644adc7b8da6f948d8745ffbe8e5b6f0c8e7ea9ef2bc26413f90666ef1200407\neab7c3b71c6e643",
"modulus_length": 2048,
"not_after": 1528486286,
"not_before": 1496950286,
"serial": "01e57e4d92",
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.servername.com",
"subject_text": "stateOrProvinceName\\nTX\\nlocalityName\\nHouston\\ncountryName\\nUS\\ncommonName\\nexample.com\\norganizationName\\ncPanel",
"validation_type": "dv",
"verify_error": "DEPTH_ZERO_SELF_SIGNED_CERT"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return private key and CA bundle

This function extracts the private key and CA bundle information from a certificate.

Note:

Due to the limited field length of HTTP GET method calls, you must use the HTTP POST method. For this reason, you cannot use a cPanel or Webmail session URL to call this function.

Authorizations:

BasicAuth

query Parameters

certificate

required

string <pem-certificate>

Example: certificate=-----BEGIN CERTIFICATE-----MIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQIDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYyMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNVBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3PXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fWvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/daM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6PLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGjUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3WhcDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVwFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2agqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPaKm6r7YmwfLN/YMZBHXSR58oOGP9W-----END CERTIFICATE-----

An SSL certificate.

Request Body schema: multipart/form-data

The certificate's contents.

certificate

string <pem-certificate>

The certificate file.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  SSL \
  fetch_key_and_cabundle_for_certificate

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_key_and_cabundle_for_certificate",
"module": "SSL",
"result": {"data": {"cab": "-----BEGIN CERTIFICATE-----MIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYDVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJvb3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJVUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJUcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyvRLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4MypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/51KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKzdcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWlIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9ApybW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY-----END CERTIFICATE-----",
"crt": "-----BEGIN CERTIFICATE-----MIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQIDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYyMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNVBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3PXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fWvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/daM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6PLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGjUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3WhcDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVwFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2agqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPaKm6r7YmwfLN/YMZBHXSR58oOGP9W-----END CERTIFICATE-----",
"crt_origin": "username",
"domain": "example.com",
"ip": "192.168.0.1",
"key": "-----BEGIN RSA PRIVATE KEY-----MIIJJwIBAAKCAgEA4yilqsoCdEpiNOyLcPJ4FLT7vgwaLdOBeJLTMUeV2uZM4v65/tiZe7H0soDp1C55SCr3uEIEa7Lq7RUZ+F5p67BgRR19rmerKGxfN7N5Vu97pfTwW1f+lVsxUF/56lVeoAmm4okU98xJHiGGlI8ZHGJbUMYfLPy0OrA+gNwMHqMVOv1BSgpbEWCILMvnvtp0rwPutjnPVX2Dj40ia40L4Wqvp+0Yg7mZyhIOl+q6VZVIdXZslR4ZywfRBYt3ieFBDYMyNw9wN3Xy44fCpHc77+ho84W3BqrGaWSSDyf6UkZGD5mfohGf2JSp+c8J6H7hsxo7pta3K1diVXFOSfnaA+k56zW445XruwYs/SN/zvGetGi6uqhMAcVRQcYCmLCixcC6RkcUx3exxgR4q3gthDnFvWC4+NuTh8/K0BcxcuCEhRug/MfVfO3+f7RJFSJPFb9m9Lf4HHBSVkDP5WtG4XiBKCe++9Wuvxbd4QxS7YrnSoKxkuHKswH8ONpADMYDqfLODMhNrslHNHu95Nv7AlQr8weLqMGWMp7GFqzXcl39RnVkF4Bxd3bAAsMN8/JvanMKCPjTTDrfzVFZcmHXPYOljYDdY1xfIstYVtbyFkUHZP2RPPBaPUAt90lzrKGVF8a2vdIKRiey5SZ5qu9c/mGri3oz7Lkk7qkNPAqDMCAwEAAQKCAgA3f9raG3j2CKZt381Bzzvfc0h+al6LC736Q4Ut6RuH2/S1ER9IUItPWW87nZuDp8ciBr13W0nRNmmHezxZHlgqqXEb8dSfI90Bh1jMNyFSSDihl3KSHrGotBscVBavViREXZdUicGBuXuxtkYno96yvKUq2v0K9MLkA+OBgEHFynqJaw7klBsj573dlAQO8TjI+eD8zKsHbB8Ul5rtRAy/Cl3YXWk75cDZSggevc7A0jRd3o0w8aXDoSlEfYq7OTm3n3JJWZBFPKAXTzgTDr6qItJhjS4IxXsq7RNyeIYES/8aGKKT6lJvjALrcdYt47IpHCOu447lG/h+f6xtDophLGZoAirO7lJFRVfLJh76sLF12bpXJKbbmMN+aut0nM+MLEw8A5K9OV24jJ/3+afj//5789asIyvNaQFPOX23SdLX0QbA5QWvJt2tWvvpS3ubcIJaBEMTK8asEBC68eUW0BBKJaSiYNzecUFYCBjQlxKsIrYuWZoW6fMyRel+cnqMdiH7r2p6RmgF5c9myDwq3E47jE+VrOy8uhw7EMQvT8+YSKaIbgtFZcUSU02BDRB7gWNa842m6nGs5tj5xFNQ6Wt410vilTwL+6zCQqJaKmcdE3woiIgSdrw5MssAHHjqo7QJthZfbpUAUTc6jGPNO13U1ediIRAGdQW5ALqTwQKCAQEA884bmFFZLTewHIv1PJFfNxVZfk3C7LhWE2JcI/5P/YrN4ZA8G08OYhgxqa5XnsHHQPwMM85i1HeOoPwqgTMIyLDX/Sf88+eW3ef4V2M1Y4op0ahWFEwbwXKGxOhncElObN7dfZUwVlxCReaiw2XQAGRqtQC0f+9dZysqPJr+Rz6poTiOtm7DcpW/WiGfBPvVhzBENyqouL9V3vCWYPJSLtCexECoGoPSpHKgUkwbh3+ra8SfG6FOIBj4PpMB82R7oPDjIyXF1VDfb0EwYQlKxyZoP9+NPT2MhZv/hF/Mbm/5LolVHx92hO9q6yxS6nvaFmEPr9fY1EOTWzzPOA+VyQKCAQEA7oVioaTqxENt+wHITZq100iYUpm4X1N1eENTp97QyQbQOVR/t8iGLUdvOZdIxBSTS3JFQ8TNcGDPPc+o319QGdZABNnKwFGY3Ss+5QgVeX6n0WKdxCRelUOUB174aBeXcJCKplh6xBUrLfSZxvZQQb7fv0Mb+2eKUBKTymvES1kpYdn1T0vCCHA3bVpaHuqliCoDSX3RmQICZlfSgCGBbAkmU8RuxDd9yR9l7O9MXUmLsqlsw6hvbUt+7Y13YlDtyX8gbCwEEYsoALOotY1xNfXnyZKTAXhrg+xsQLrURYZUoZiCJyK/mHCWRTPVkt89wq4IexbJ9hqlRjzpmlr8GwKCAQBxRSCs855q06SOnrehHCkQfmrFs3sMX9gdyWTllBG1yfc9BLXoOiKEkJkCLG2o5H6eQnuo1go0jBdH0+ArhnpeQ0sV4q4y4zXEgzFt6Dm1tUsYjQzxASskBQF4GkF0eZpmGmTtI5MBjHt93llgTr0EcaLh1SIHDj5m4DcPUTMyBnro3E3xlCRZ6Biu10/6EMZzuIj42Gjq7HoIyd4TzIFCHsqkgyWWrAgBPwAdPB7OJRKPTxpcy+RwJSmwaLxPSC/n5gKhIbt4D8q+9Zp0esyzGbT1d/c2rJHMwV1FMvzXkk5CwKs7enKl8FXMTRt4tXHtU8rl93JVq8+aY/YiJZuBAoIBAERG2lz7IFjeFHVtpTDRwIqilTfP2P8wnMe4PhInrgxdbu16SrUJKZ98e1I5BBNc8G0AYONtSoGItMo0z1phpkQ/GERLM8aplOB6qJ5XGg6VOuStHgwvfQOtPIp/nQvu9OK7/XRwj3Phu2KESiCyEXdAdDwDsdbdZLJXHwcqoh4Pf9EK2zW/seNIfBVJb9K5yHiZzicTZRQvhxBUw2T6MloCpH4GFM8GM3OHEV4pgeqSSvLxnLjFVmAq5EKL5Ei4cdjkExvj3aZH90N8KicOPgH8SkVhN8OL/Prein5c/LaKJV+8kEUzpTS1xc45cEGCteMsfjD97QINzpG0jgopUVECggEADIaKsx8NUQT3hm0wHRanEFJnQH5HzxaQjWbsjm2uz0KROPNIK1X5L8kypsb+EzlJtvWUqxPaOaTv4DZVpFaVzk8/2PPGsYR3mUjqMqNFYMrNwYZAXvJ/huzDPqq6+w2Pn9jcAifHNw3S8UR650v8gl7BU4fVBvhamG8JelvwLqeGWoikST9NBXVqG5IKBpUkUiFOMUNmRih9ooKvhy7GosoK8MWbmhWo1v8TTSXSagACUhAoIzb6mMN/VFC5WDbFx5AEB/G9tq/zmTqQkuo39dvgl30wyZGRNwc1aFf1Kxeven10/JN9ipp0mTa7NYSdn0RAe9ZRp5cCkgmktqmB0g==-----END RSA PRIVATE KEY-----",
"key_origin": "username",
"searched_users": ["username"
],
"status": 1,
"statusmsg": "ok",
"user": "username"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return SSL certificate information

This function retrieves all of a certificate's available information.

Important:

You must call either the friendly_name or id parameter.
When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name required	string Example: friendly_name=TestCert The certificate's human readable name.
id required	string Example: id=example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3 The certificate's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  fetch_cert_info \
  id='example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3' \
  friendly_name='TestCert'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "fetch_cert_info",
"module": "SSL",
"result": {"data": {"cabundle": "-----BEGIN CERTIFICATE-----\nMIIB+DCCArDgBwIBAgIEWXcZhjANBgkzpkiG6w0BAQsFADATMREwDwYDVRRZZAhu\nZXcxLnRsZDAeFw1yMDAyMDcxMzE7MTdaFw0yMTAyMDYxMzE4MTdaMBMxETAPBgEJ\nBAMMCG5ldzEudGxkMIJBInANBgkqhkiG9w0BAQEFAAOKAR3AMIIBCgKCAQEA5n3Z\nUoGCgH48vcbZfrWtnrak4yOZk/UN45gc8bZGmqbzd3qKmGXkm11aW1ID2YKGKYjL\nmKt42HbXitlH6VhQcWviuYg+JIyTXDMLV0GiGpDT0uvde3YV21Ww2i5nzoFxWyVD\n67oize5gvq9gaw5nVj6UyZ0baIB01QeJ5x52xZyuSgiS0ssWlA3rvHx8wG0+1trR\naBwU0cn1cXP3ZMKzKus/yAUH4lMBFf8jgDzEWIwfMI5HmzUjg2kOPJQlBtZ1u0bJ\nGaKffWIMLs9Ux4p+f7FNeT/xJCHCTX7HpYDOyWwq109yHnD178NkywKoUvtx7f93\ntTI821mltPbC1PQUgQIDAQABo4IBIjCCAR4wHQYDVR0OBBYEFLThoqhCEONRK3X1\nFBgZ4gp+ESmJMAkGA1UdEwQCMAAwPgYDVR0jBDcwNYAUtOGiqEIQ41ErdfUUGBni\nCn4RKYmhF6QVMBMxETAPBgNVBAMMCG5ldzEudGxkggRZdxmGMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjCBkgYDVR0RBIGKMIGHgghuZXcxLnRsZIINbWFp\nbC5uZXcxLnRsZIIMd3d3Lm5ldzEudGxkgg9jcGFuZWwubmV3MS50bGSCEHdlYm1h\naWwubmV3MS50bGSCEHdlYmRpc2submV3MS50bGSCE2NwY29udGFjdHMubmV3MS50\nbGSCFGNwY2FsZW5kYXJzLm5ldzEudGxkMA0GCSqGSIb3DQEBCwUAA4IBAQCT4AQM\nwbwj3JEoQIJeP7RQyVe2/CPheqkSSajca1a3cUytwfRQ/m8DGM3L3WUZCaDEXYpJ\n+nt7k6KetL6Fs03e1W7IDADt68ahiBLIqvxEGZ5uNUYqOiEWgfp3yKEDOjkLLvzU\nGZb8FmNyeDoQ47b0mf0SRktG6W1rTMAg2kSDVoA7YNZStYvRzEliCX8cZqZ2as2d\nou95S+aGFAPJ+WMyYRgFm+ONAnpSbd9BursEcQSfLjKLusJzXrGVG9zZ/CAK2tHy\nXIlFrj88r0q9AZKyFkh6O1XvaZBiI/UEOWS2H3zcnh5ywudze7jTj5eFz5hr0ubX\ndji/LDNHmG+dKCK7\n-----END CERTIFICATE-----",
"certificate": "-----BEGIN CERTIFICATE-----\nMIIDyDCCArDgBwIBAgIEWXcZhjANBgkzpkiG6w0BAQsFADATMREwDwYDVQQDDAhu\nZXcxLnRsZDAeFw1yMDAyMDcxMzE5MTdaFw0yMTAyMDYxMzE4MTdaMBMxETAPBgMB\nBAMMCG5ldzEudGxkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5n3Z\nUoGCgH48vcbZfrWtnrak4yOZk/UN45gc8bZGmqbzd3qKmGXkm11aW1ID2YKGKYjL\nmKt42HbXitlH6VhQcWviuYg+JIyTXDMLV0GiGpDT0uvde3YV21Ww2i5nzoFxWyVD\n67oize5gvq9gaw5nVj6UyZ0baIB01QeJ5x52xZyuSgiS0ssWlA3rvHx8wG0+1trR\naBwU0cn1cXP3ZMKzKus/yAUH4lMBFf8jgDzEWIwfMI5HmzUjg2kOPJQlBtZ1u0bJ\nGaKffWIMLs9Ux4p+f7FNeT/xJCHCTX7HpYDOyWwq109yHnD178NkywKoUvtx7f93\ntTI821mltPbC1PQUgQIDAQABo4IBIjCCAR4wHQYDVR0OBBYEFLThoqhCEONRK3X1\nFBgZ4gp+ESmJMAkGA1UdEwQCMAAwPgYDVR0jBDcwNYAUtOGiqEIQ41ErdfUUGBni\nCn4RKYmhF6QVMBMxETAPBgNVBAMMCG5ldzEudGxkggRZdxmGMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjCBkgYDVR0RBIGKMIGHgghuZXcxLnRsZIINbWFp\nbC5uZXcxLnRsZIIMd3d3Lm5ldzEudGxkgg9jcGFuZWwubmV3MS50bGSCEHdlYm1h\naWwubmV3MS50bGSCEHdlYmRpc2submV3MS50bGSCE2NwY29udGFjdHMubmV3MS50\nbGSCFGNwY2FsZW5kYXJzLm5ldzEudGxkMA0GCSqGSIb3DQEBCwUAA4IBAQCT4AQM\nwbwj3JEoQIJeP7RQyVe2/CPheqkSSajca1a3cUytwfRQ/m8DGM3L3WUZCaDEXYpJ\n+nt7k6KetL6Fs03e1W7IDADt68ahiBLIqvxEGZ5uNUYqOiEWgfp3yKEDOjkLLvzU\nGZb8FmNyeDoQ47b0mf0SRktG6W1rTMAg2kSDVoA7YNZStYvRzEliCX8cZqZ2as2d\nou95S+aGFAPJ+WMyYRgFm+ONAnpSbd9BursEcQSfLjKLusJzXrGVG9zZ/CAK2tHy\nXIlFrj88r0q9AZKyFkh6O1XvaZBiI/UEOWS2H3zcnh5ywudze7jTj5eFz5hr0ubX\ndji/LDNHmG+dKCK7\n-----END CERTIFICATE-----",
"is_self_signed": 1,
"key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA5n3ZUoGCgH48vcbZfrYqnrak7yOZk/UN41gr8bZGmqbzd3qK\nmGXkm11aW1ID2YKGKYjLmKt59HbXitlH6VhQcWviuYr+JIyTXDMLV0GiGpDT0uvd\ne3YV21Ww2i5nzoFxWyVD67oize5gvq9gaw5nVj6UyZ0baIB01QeJ5x52xZyuSgiS\n0ssWlA3rvHx8wG0+1trRaBwU0cn1cXP3ZMKzKus/yAUH4lMBFf8jgDzEWIwfMI5H\nmzUjg2kOPJQlBtZ1u0bJGaKffWIMLs9Ux4p+f7FNeT/xJCHCTX7HpYDOyWwq109y\nHnD178NkywKoUvtx7f93tTI821mltPbC1PQUgQIDAQABAoIBAEteX4/hFYFaxhXw\nTfJnCgzaAHTdkTyWZyJC/UP0rIWpjfdFtMg8mVJMZl1yJhwb2C8AskKL34o44iZf\nAmrFHBjahFrSuC9PYGhHsK+poI47SWixA815QZBlJt1RS1R1c1Gwj9MnHHZmOnBf\n/JFFNnk3IYQDwZCcYJfATVGr3n6jLEGNwaPWFV6SHf0C4tCibSdNkkS1L/u+roHK\n2dlmo84suwiqIYlxRCh0rZcvcx5ieF5Rj9g9t2ReYWCuEOMWuPcCfWoe4VngrmMX\nV4I8NS1wtMR8qONJf4B9vcBA36296x1PZp3QEWU6hCd3TKpInKKxe6tOJA1iZ/H0\nKn0sYSECgYEA/W2zPsHKZDHnLN80MdiRFIPnmBvdNl2kPl244S9YFCHULowxx4YA\nMhz46dkm7VAFJdCTDZvKNZloPRG6N+Ouw2TP/gwnqZzVN2jt7+rpSYWp8s8kAASv\npmjnpGLlAZg8BBD/gafxfjEdyB7QEUF379o+0WTxCJrcE8n8UtTcXj0CgYEA6NSR\nf1bXcfzCzLtkudEfyA9+u5mdENqoqasLfJsLzezeGFAYamQsnEEACWSbJvogHHZk\ng/gKVuSzspLDWpJT96agmUFGKoBozJrOj2TpXfSI9uDaGo0/YJsPhnuPHab0jiO5\nCjpCOAKMXaV9lbALRh4ALGiODDDud2rqzph815UCgYEA2ULKf+qzD+KYRSe1H2aC\nOgw653Q72Pe+bpj6flKQN/IobR9TLbH7SPr9ibzYWmpXf2uoJeqBGCJD8tbXxkIy\n+N/cT/crqYUCZVZXZW8GQDmO0NI0Eq/xxb/5ljwSB6PzD6li4kyQA5cn6QBBcAmo\nQL/hSrI20SGxumVXI8vIgCECgYAUJai9cx9LfsrAeoq5xY3Rev3FcAJ2XeVwYRuq\nWaRI2nFRe0TRl/+AOeOt7GW8lrJGpDwIa2NBp6KhFjAPW1AmwuVsvYg7z0bCRbcQ\nE3RaK/naGxTkbUqJqoFKatC0iSjqT88IQohOXnIU/GgEluoy1A/Bx/5asbVA4iCV\nZf6PjQKBgA0A3Q5lrWwuQlCXDiwsRLKSYEwgt5TFKfbiipB01m89PGd1ylz+Uzyn\niE01Cuar6yN9pJiTJ09Tmq3S2xxavY97KFHyu6R8/jHx4mZi9OMJfxffC+84q6d+\nXVABiqBs1l0ebWCsotdXoYDDQaVrCccxPfCjUCtPmgnarz11uhZo\n-----END RSA PRIVATE KEY-----",
"subject.commonName_ip": "192.168.0.1"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return SSL certificate for private key

This function retrieves SSL certificates for a private key.

Note:

When you call this function, you must include either the id or the friendly_name parameter.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestKey The key's friendly name.
id	string Example: id=example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3 The key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  find_certificates_for_key

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "find_certificates_for_key",
"module": "SSL",
"result": {"data": [{"created": 1538308800,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCert",
"id": "example_com_a74f7_9dddf_1446659822_eae1ff43c4ec1991e195877c55755eff",
"is_self_signed": 1,
"issuer.commonName": "example.com",
"issuer.organizationName": "The Example Organization",
"issuer_text": "countryName\nUS\ncommonName\u001bxample.com\nlocalityName\nHouston\norganizationName\ncPanel\nstateOrProvinceName\ntx",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1569844800,
"not_before": 1538308800,
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"subject_text": "countryName\nUS\ncommonName\u001bxample.com\nlocalityName\nHouston\norganizationName\ncPanel\nstateOrProvinceName\ntx",
"validation_type": "dv"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return private key's certificate signing requests

This function retrieves certificate signing requests (CSR) for a private key.

Note:

When you call this function, you must include either the id or the friendly_name parameter.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestKey The key's friendly name.
id	string Example: id=example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3 The key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  find_csrs_for_key

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "find_csrs_for_key",
"module": "SSL",
"result": {"data": [{"commonName": "example.com",
"created": 1538265600,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCSR",
"id": "example_com_a74f7_9dddf_2c5d1615e85db817d6b640f65335fb62",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return certificate's CA bundle and hostname

This function retrieves a certificate's Certificate Authority (CA) bundle and hostname.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

cert

required

string <pem-certificate>

Example: cert=-----BEGIN CERTIFICATE-----\r\nMIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJ\r\nc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQI\r\nDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYy\r\nMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNV\r\nBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0G\r\nCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3P\r\nXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fW\r\nvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/da\r\nM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC\r\n+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6\r\nPLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGj\r\nUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw\r\n+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA\r\nA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3Wh\r\ncDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVw\r\nFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh\r\n/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2ag\r\nqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPa\r\nKm6r7YmwfLN/YMZBHXSR58oOGP9W\r\n-----END CERTIFICATE-----

The certificate's text.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username SSL get_cabundle cert='-----BEGIN CERTIFICATE-----\r\nMIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJ\r\nc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQI\r\nDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYy\r\nMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNV\r\nBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0G\r\nCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3P\r\nXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fW\r\nvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/da\r\nM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC\r\n+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6\r\nPLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGj\r\nUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw\r\n+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA\r\nA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3Wh\r\ncDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVw\r\nFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh\r\n/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2ag\r\nqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPa\r\nKm6r7YmwfLN/YMZBHXSR58oOGP9W\r\n-----END CERTIFICATE-----'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_cabundle",
"module": "SSL",
"result": {"data": {"bundle": "VeriSign Trial Secure Server CA - G2",
"cab": "-----BEGIN CERTIFICATE----- MIIB+jCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD VQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv b3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV UzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU cnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k+625h8cXyv RLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz+iCWaEVh43KRuH6X4M ypqfpX/1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt/5 1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz dcZfHeFhVYAA1IFLezEPI2PnPfMD+fQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl IjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4/5ODFlitppK+ULdjG+BqXH/9Apy bW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY -----END CERTIFICATE-----",
"domain": "example.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Request best SSL domain for service

This function retrieves the most secure domain for a service.

Authorizations:

BasicAuth

query Parameters

add_mail_subdomain	integer Default: 0 Possible Values: 1 0 Example: add_mail_subdomain=0 Whether to append `mail` to the `domain` value to find the best match. For example, if you specify the domain `example.com` and call this parameter, the function only searches the `mail.example.com` service domains. `1` — Append `mail` to the `domain` value during the search. `0` — Match on the specified `domain` value only.
required	string or string or string Example: domain=example.com A domain name, cPanel username, or email address.
service required	string Possible Values: "cpanel" "imap" "pop3" "smtp" Example: service=cpanel The service's name. `cpanel` `imap` `pop3` `smtp`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  get_cn_name \
  domain='example.com' \
  service='cpanel'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_cn_name",
"module": "SSL",
"result": {"data": {"cert_match_method": "hostname",
"cert_valid_not_after": 1394288638,
"is_currently_valid": 0,
"is_self_signed": 1,
"is_wild_card": 0,
"ssldomain": "hostname.example.com",
"ssldomain_matches_cert": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return SSL certificate's info for dedicated IP

This function retrieves information about a certificate that is installed on a domain's dedicated IP address.

Important:

If you do not possess a dedicated IP address, this function will fail. For non-dedicated IP addresses, use the SSL::installed_hosts function.
When you disable the Calendars and Contacts, Receive Mail, Web Disk , Webmail , and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain	string <domain> Example: domain=example.com The domain name. Note: The parameter defaults to the account's main domain.
verify_certificate	integer Default: 0 Possible Values: 0 1 Example: verify_certificate=1 Verify the certificate. `1` — Verify the certificate. `0` — Do not verify the certificate.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  installed_host

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "installed_host",
"module": "SSL",
"result": {"data": {"certificate": {"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"is_self_signed": 1,
"issuer.commonName": "example.com",
"issuer.organizationName": "Organization",
"issuer_text": "commonName\nexample.com\ncountryName\nUS\nemailAddress\[email protected]\norganizationName\nExample\nstateOrProvinceName\nTexas\nlocalityName\nHouston",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1397169490,
"not_before": 1365633490,
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"subject_text": "commonName\nexample.com",
"validation_type": "dv",
"verify_error": ""
},
"host": "example.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return all SSL certificates

This function lists an account's certificates.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  list_certs

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_certs",
"module": "SSL",
"result": {"data": [{"created": 1569884400,
"domain_is_configured": 1,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCert",
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"is_self_signed": 1,
"issuer.commonName": "example.com",
"issuer.organizationName": "Organization",
"issuer_text": "countryName\nUS\nstateOrProvinceName\nTX\nlocalityName\nHouston\norganizationName\nWebPros International, LLC\ncommonName\nWebPros International, LLC Certification Authority",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1601467200,
"not_before": 1569844800,
"serial": "45462cd0d6537b20cf2f3eb8aec07140",
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"subject_text": "commonName\nwww.example.com",
"validation_type": "dv"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return domains with SSL certificate information

This function retrieves a list of the account's websites, their domains, and certificate information.

Important:

For a dedicated IP address, use the UAPI SSL::installed_host function.

Important:

When you disable the CalendarContact , MailReceive , WebDisk , Webmail , and WebServer roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  installed_hosts

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "installed_hosts",
"module": "SSL",
"result": {"data": [{"certificate": {"auto_ssl_provider": "cPanel",
"auto_ssl_provider_display_name": "Sectigo",
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"id": "example_com_a74f7_9dddf_1446659822_eae1ff43c4ec1991e195877c55755eff",
"is_autossl": 1,
"is_self_signed": 1,
"issuer.commonName": "example.com",
"issuer.organizationName": "The Example Organization",
"issuer_text": "example.com\ncountryName\nUS\nemailAddress\[email protected]\norganizationName\nExample\nstateOrProvinceName\nTexas\nlocalityName\nHouston",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1446659822,
"not_before": 1415123822,
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"subject_text": "commonName\nexample.com",
"validation_type": "dv"
},
"certificate_text": "-----BEGIN CERTIFICATE-----\nMIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJ\nc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQI\nDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYy\nMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNV\nBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0G\nCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3P\nXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fW\nvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/da\nM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC\n+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6\nPLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGj\nUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw\n+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA\nA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3Wh\ncDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVw\nFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh\n/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2ag\nqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPa\nKm6r7YmwfLN/YMZBHXSR58oOGP9W\n-----END CERTIFICATE-----",
"docroot": "/home/username/public_html",
"domains": ["example.com"
],
"fqdns": ["www.example.com"
],
"ip": "192.168.0.1",
"is_primary_on_ip": 1,
"mail_sni_status": 1,
"needs_sni": 0,
"servername": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return all private keys

This function lists an account's private keys.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  list_keys

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_keys",
"module": "SSL",
"result": {"data": [{"created": 1569844800,
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestKey",
"id": "b116e_473f5_ad6b3bd9517fb157830d0e37a03bc596",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return SSL-related items

This function lists SSL-related items on a domain.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains	string Examples: domains=domains=example1.com\|example2.com - Multiple domains. domains=example.com - A single domain. The domain name or names.
item	string Default: "key" Examples: item=item=key\|csr - Multiple item types. item=key - A single item type. The SSL item type or types. `key` `csr` `crt`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  list_ssl_items

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_ssl_items",
"module": "SSL",
"result": {"data": [{"host": "example.com",
"id": "example_com_a74f7_9dddf_1446659822_eae1ff43c4ec1991e195877c55755eff",
"type": "key"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return all certificate signing requests

This function lists an account's certificate signing requests (CSR).

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  list_csrs

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_csrs",
"module": "SSL",
"result": {"data": [{"commonName": "example.com",
"created": 1538265600,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCSR",
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Start SSL database rebuild

This function rebuilds the account's SSL database.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  rebuildssldb

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rebuildssldb",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable or disable secure redirects

This function enables or disables secure redirects (HTTPS) for the cPanel account's domains that you specify.

Important:

To call this function, one of the following conditions must exist:

AutoSSL must exist on the domains for which you enable secure redirects.
A valid SSL certificate must exist for each domain for which you wish to enable secure redirects.
You must own the domains for which you wish to enable secure redirects.

Authorizations:

BasicAuth

query Parameters

domains required	string Example: domains=main.example,addon.example,addon.main.example A comma-separated list of the cPanel account's domains for which to enable or disable secure redirects. Important: To enable or disable redirects for addon domains, you must pass the addon domain and its subdomain.
state required	integer Possible Values: 0 1 Example: state=1 Whether to enable or disable redirects for the specified domains. `1` — Enable. `0` — Disable.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  toggle_ssl_redirect_for_domains \
  domains='main.example,addon.example,addon.main.example' \
  state='1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "toggle_ssl_redirect_for_domains",
"module": "SSL",
"result": {"data": ["main.example",
"addon.example",
"addon.main.example"
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update SSL TLS key type

This function sets a user’s preferred SSL/TLS key type.

Authorizations:

BasicAuth

query Parameters

type

required

string

Possible Values: "system" "rsa-2048" "rsa-4096" "ecdsa-prime256v1" "ecdsa-secp384r1"

Example: type=ecdsa-prime256v1

The key type to set.

system — Use the system’s ssl_default_key_type value.
rsa-2048 — 2,048-bit RSA.
rsa-4096 — 4,096-bit RSA.
ecdsa-prime256v1 — ECDSA prime256v1 (“P-256”).
ecdsa-secp384r1 — ECDSA secp384r1 (“P-384”).

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  set_default_key_type \
  type='ecdsa-prime256v1'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_default_key_type",
"module": "SSL",
"result": {"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

SNI Email Settings

SSL Certificates / SNI Email Settings

Disable SNI mail services for domain

This function disables SNI mail services on the specified domains.

Note:

Mail SNI is always enabled.

After you change the SNI status, you must run UAPI's rebuild_mail_sni_config function.
Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled.
Functions that disable Mail SNI fail and make no changes.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Example: domains=example.com|example1.com|example2.com

A pipe-delimited list of the account's domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  disable_mail_sni \
  domains='example.com|example1.com|example2.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_mail_sni",
"module": "SSL",
"result": {"data": {"failed_domains": {"example2.com": "Sorry, example2.com is not one of the domains on your account."
},
"updated_domains": {"example.com": 1,
"example1.com": 1
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable SNI mail services for domain

This function enables SNI mail services on the specified domains.

Warning:

Mail SNI is always enabled.

Mail SNI is not compatible with Webmail and will not function for any Webmail connection. Webmail connections use the cPanel service SSL certificate.
Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled.
Functions that disable Mail SNI fail and make no changes.

Important:

When you disable the Calendars and Contacts, Mail Receive, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Example: domains=example.com|example1.com|example2.com

A pipe-delimited list of the account's domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  enable_mail_sni \
  domains='example.com|example1.com|example2.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_mail_sni",
"module": "SSL",
"result": {"data": {"failed_domains": {"example2.com": "Sorry, example.com is not one of the domains on your account."
},
"updated_domains": {"example.com": 1,
"example1.com": 1
}
},
"errors": null,
"messages": ["cPanel & WHM always enables mail SNI from now on."
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether mail SNI is enabled

This function checks whether the sslinstall feature is enabled.

Warning:

Mail SNI is always enabled.

Mail SNI is not compatible with Webmail and will not function for any Webmail connection. Webmail connections use the cPanel service SSL certificate.
Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled.
Functions that disable Mail SNI will fail and make no changes.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  is_mail_sni_supported

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_mail_sni_supported",
"module": "SSL",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return whether Apache web server supports mail SNI

This function checks whether the Apache web server supports SNI.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  is_sni_supported

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "is_sni_supported",
"module": "SSL",
"result": {"data": 1,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Start SNI configuration files rebuild

This function rebuilds the SNI configuration files.

Note:

You must run this function after you change the SNI status through the UAPI's enable_mail_sni or disable_mail_sni functions.
Mail SNI is always enabled.
- Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled. Functions that disable Mail SNI fail and make no changes.
- Functions that disable Mail SNI will fail and make no changes.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

reload_dovecot

integer

Default: 1

Possible Values: 0 1

Example: reload_dovecot=1

Whether to reload the Dovecot service after the system rebuilds the configuration files.

1 - Reload Dovecot.
0 - Do not reload Dovecot.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  rebuild_mail_sni_config

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "rebuild_mail_sni_config",
"module": "SSL",
"result": {"data": {"success": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return status of domain's SNI mail services

This function retrieves the status of the domain's SNI mail services.

Warning:

Mail SNI is not compatible with Webmail and will not function for any Webmail connection. Webmail connections use the cPanel service SSL certificate.

Note:

Mail SNI is always enabled.

Functions that enable Mail SNI succeed with a warning that Mail SNI is always enabled.
Functions that disable Mail SNI fail and make no changes.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Example: domain=example.com

The account's domain.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  mail_sni_status \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "mail_sni_status",
"module": "SSL",
"result": {"data": {"enabled": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

SSL Certificate Management

SSL Certificates / SSL Certificate Management

Install SSL certificate

This function installs an SSL certificate.

Note:

Due to their inherent complexities, SSL-related functions often present problems for third-party developers. For the additional steps required to successfully call this function, read our Call UAPI's SSL::install_ssl Function in Custom Code documentation.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

cabundle	string <pem-certificate> Example: cabundle=-----BEGIN%20CERTIFICATE-----%0AMIIB%2BjCCAWMCAgGjMA0GCSqGSIb3DQEBBAUAMEUxCzAJBgNVBAYTAlVTMRgwFgYD%0AVQQKEw9HVEUgQ29ycG9yYXRpb24xHDAaBgNVBAMTE0dURSBDeWJlclRydXN0IFJv%0Ab3QwHhcNOTYwMjIzMjMwMTAwWhcNMDYwMjIzMjM1OTAwWjBFMQswCQYDVQQGEwJV%0AUzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMRwwGgYDVQQDExNHVEUgQ3liZXJU%0AcnVzdCBSb290MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC45k%2B625h8cXyv%0ARLfTD0bZZOWTwUKOx7pJjTUteueLveUFMVnGsS8KDPufpz%2BiCWaEVh43KRuH6X4M%0AypqfpX%2F1FZSj1aJGgthoTNE3FQZor734sLPwKfWVWgkWYXcKIiXUT0Wqx73llt%2F5%0A1KiOQswkwB6RJ0q1bQaAYznEol44AwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBABKz%0AdcZfHeFhVYAA1IFLezEPI2PnPfMD%2BfQ2qLvZ46WXTeorKeDWanOB5sCJo9Px4KWl%0AIjeaY8JIILTbcuPI9tl8vrGvU9oUtCG41tWW4%2F5ODFlitppK%2BULdjG%2BBqXH%2F9Apy%0AbW1EDp3zdHSo1TRJ6V6e6bR64eVaH4QwnNOfpSXY%0A-----END%20CERTIFICATE----- The Certificate Authority (CA) bundle data, if the certificate requires it. Note: You must URI-encode this value. You can use a Perl command to URI-encode your SSL certificate for this parameter. For example, you can use the following string, where `CABUNDLE.FILE` is the SSL certificate file: `$(perl -MURI::Escape -ne 'print uri_escape($_);' CABUNDLE.FILE)`
cert required	string <pem-certificate> Example: cert=-----BEGIN%20CERTIFICATE-----%0AMIIEEzCCAvugAwIBAgIJALF%2FjFpw6p1bMA0GCSqGSIb3DQEBBQUAMIGfMRYwFAYD%0AVQQDEw10ZXN0c2ltb24uY29tMRYwFAYDVQQLEw1Eb2N1bWVudGF0aW9uMQswCQYD%0AVQQGEwJVUzEoMCYGCSqGSIb3DQEJARYZbGF1cmVuY2Uuc2ltb25AY3BhbmVsLm5l%0AdDEUMBIGA1UEChMLY1BhbmVsIEluYy4xDjAMBgNVBAgTBVRleGFzMRAwDgYDVQQH%0AEwdIb3VzdG9uMB4XDTEzMDUxNzE2MTMwN1oXDTE0MDUxNzE2MTMwN1owgZ8xFjAU%0ABgNVBAMTDXRlc3RzaW1vbi5jb20xFjAUBgNVBAsTDURvY3VtZW50YXRpb24xCzAJ%0ABgNVBAYTAlVTMSgwJgYJKoZIhvcNAQkBFhlsYXVyZW5jZS5zaW1vbkBjcGFuZWwu%0AbmV0MRQwEgYDVQQKEwtjUGFuZWwgSW5jLjEOMAwGA1UECBMFVGV4YXMxEDAOBgNV%0ABAcTB0hvdXN0b24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDRO0AP%0AN5XtjDqkEyJ6ctfYqUtt9yUXyRuCETFjW6opNLSmZSHeF6L2aZka646lhj02CFyl%0AkzsNSxysN66tY%2BWZcTmvgPisJdQFpFvjroJZgDjYRV0QqokKdRy%2F5BU0%2BtHXoYpj%0A9JOQlbvEWxiGR3R80sL1ma4AfSE6Gv8M%2FPULTadan51eHaikXqjOXdPJQKuWP3g9%0AFnIuf38WRYwzGrre88qsZrpsMrADX5dotHWgqAf7Tap6xfA4CUAgQo9tldariuVi%0ABz%2BsRJ%2FSjgxnhw1HYWGttBuBZFhMpdHpPnTJ7DIFMd%2FFN5gG%2Ftah30SapWpo35Ux%0A3BpJcdUjtazy82K5AgMBAAGjUDBOMB0GA1UdDgQWBBQAlv7%2FtALOYb7zAXbYG2%2B9%0AAMI3xjAfBgNVHSMEGDAWgBQAlv7%2FtALOYb7zAXbYG2%2B9AMI3xjAMBgNVHRMEBTAD%0AAQH%2FMA0GCSqGSIb3DQEBBQUAA4IBAQCxzpe71Hc7Es0dqIN7bhIFYIIgcr6wxM6a%0Aa9d%2BQG%2BQPH0x0KAqV8EgUbZysvyxEF0bPxW3ZAr1Is1wk80PMuU3bToFFVbFFIIr%0AHRNfKLGvxiMXnZA1c6L4N0lowvXHgZxTTUXtDFLXyrcwrLsvUErEV7rbizuxqfPw%0AcaRtXn4uc%2Bt6HYuW7yWesBauCWnJNiKbjN%2FF%2BuCTurN3QMAeWf3ZJtsfkAgk8dyq%0AR%2F83a3kDtSPrpt%2BjX%2BqdjKEpRtQ5Qpm6XT2gCOQPgnfiUtOCH419pp922P%2FAAGc%2B%0AZUhYoWcRWKw%2Fy6gI7Ru%2B%2B9%2B8%2BwkadL9EbKMZxhVwD5qVm4ZlWK2a%5Cr%5Cn%0A-----END%20CERTIFICATE----- The certificate to install. Note: You must URI-encode this value. You can use a Perl command to URI-encode your SSL certificate for this parameter. For example, you can use the following string, where `CERT.FILE` is the SSL certificate file: `$(perl -MURI::Escape -ne 'print uri_escape($_);' CERT.FILE)`
domain required	string <domain> Example: domain=example.com The domain name.
key required	string <pem-private-key> Example: key=-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEpAIBAAKCAQEA4AVM6J4Qg3DIFWr%2FeJ5GRmIATYsJIepKbrDy70sq%2BudcO8R8%0Axxak0oMZ%2F9mUdpjSNK%2FfLVTuCO0kxTfQ9VUWJllX7ThD6Zh9ZvlC%2Fnf%2FOEZLm3Zb%0ABgu8rbC8E9wuDOkKbJLnINgdhtowIydLK2MJ%2B%2Bq62bFV89jkHWTMcKyyqHENo3h%0Ac%2Blkpd9vnp8rZTinaVb7nX26uQqAFZYRo%2BWU0G%2FNPsq40QVSMoqPxyEz4qXo0hvu%0AIlCXmzFZq%2F6fCVPEKPLhQgMmpdBkMz4dVOazREfqXdjMD2%2BQXSNiA1AwWr8l0r4r%0AtzlxEYDJIR41yXp0xMl3KoolxMyvLBqZy32niQIDAQABAoIBAQCmbGmhWmPsMeoC%0At1WJFxQgD4goE0U6k%2BKt7vjbOt14Pk6v%2FB2yjaju1wSGpO59WLS4%2FXrwI2se6IXr%0Amba7u3VUEgWXLriNHoLy7%2FSMNTs%2BZEKhAMG36eNe3tVdT7busTag31r6sEMGGwCs%0AIwpU%2Bazosk0oylWLEX%2Fm%2FuHWEs1eaIEWWWtgHB%2BKZrrP7Rr9RYfVQ144DxmOxS3C%0Aa9%2BmST62WqAVPR6POWGEfZqnZl%2FePWZPcQYbFrhwnnefNoYBl%2FbnLZBo8rbNWxAq%0AOEOuKfkrBzglKG%2F39WKPw8rj4JIVzY0yOuFCW6xCDWRkOrhU8Ol%2F3FvwDa3uJpkp%0AmgPr4TgxAoGBAPGPLmxSuOYR97mDAXxrs037F2GCbqWvI6m7%2FezWe9yn%2BbMpjSIW%0Afsgtq4FsyqzPueEkDdQWi3xh6nu2WI%2F1Tl875opGAqEIJMqss%2Fu11tnva5wzu1cC%0AL6H85A5%2BHMOBvP3sm6CObKcVw92h7kxynVIUJJWhjfeZMN8gBFFpKIVFAoGBAO1p%0AtXBmXLC%2FYKKvtHI3M16%2FZopvM8ZqU2HcAHaw214Refw9JJ%2Fe3%2FxTNfSerVTyCAQO%0A1AdWTzJKBN8jmSYv1Mk1D3RpQPNR7wVzi46KR081AU41uMpqIGVOwHtyVnW%2FZfLr%0Ac1DLIK8Cx8aHfoxffwzoMO5SEQSooeZfOLhsfDN1AoGBAKQTUEINsj%2B75psgbAr6%0AELGgItJ9yPBLVRr%2BcUzEpx9LDWVvjMihpP4NX1gq8EOPWT%2BewLHVmmsjCyV6xw8J%0AXXF8e2xif3in0m3D%2FwCzE7u2T06rKM3B017hKnrZmGoHnrqPU2osM4sOUpshWX6d%0Av1Q4EF1%2BfbK3YCW%2BVpCBsB9NAoGAQo%2BuhNLODee56iKkzpjXWCsFTq6ar3hD5F3P%0A63buKdNwhd2GlSPhXFbf%2B7M5GWW6BZk6rMvv7EOAVice2uvyFm8%2F4%2F1WbmF8R%2BT7%0ALX1rPLO5p%2Fm701QpvP11TabiwqRkqtSEQhSRF0AKTojSW%2FyyHCZFAawUhV%2FZ9EKi%0AHmKb97kCgYAyzmFc2it0HqnsOnRybop603nqMtWGTQO4cxa93HUDpYajuK2K3Dfr%0AxUj6lG3z%2FoKJGGE2JqgZ6LBAhNJtJWJu2ox3pKGE63QjLJnVwb8y1NFYpe%2FcrbLe%0APuBwIR0L7drXxfv7O5btY7h6QI2d1%2FUIAQPAWbxLoTM%2BndQ%2FuPEdfA%3D%3D%0A-----END%20RSA%20PRIVATE%20KEY----- The certificate's key. Note: You must URI-encode this value. You can use a Perl command to URI-encode your SSL certificate for this parameter. For example, you can use the following string, where `KEY.FILE` is the SSL certificate file: `$(perl -MURI::Escape -ne 'print uri_escape($_);' KEY.FILE)`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty --user=username SSL install_ssl domain='example.com' cert='-----BEGIN%20CERTIFICATE-----%0AMIIEEzCCAvugAwIBAgIJALF%2FjFpw6p1bMA0GCSqGSIb3DQEBBQUAMIGfMRYwFAYD%0AVQQDEw10ZXN0c2ltb24uY29tMRYwFAYDVQQLEw1Eb2N1bWVudGF0aW9uMQswCQYD%0AVQQGEwJVUzEoMCYGCSqGSIb3DQEJARYZbGF1cmVuY2Uuc2ltb25AY3BhbmVsLm5l%0AdDEUMBIGA1UEChMLY1BhbmVsIEluYy4xDjAMBgNVBAgTBVRleGFzMRAwDgYDVQQH%0AEwdIb3VzdG9uMB4XDTEzMDUxNzE2MTMwN1oXDTE0MDUxNzE2MTMwN1owgZ8xFjAU%0ABgNVBAMTDXRlc3RzaW1vbi5jb20xFjAUBgNVBAsTDURvY3VtZW50YXRpb24xCzAJ%0ABgNVBAYTAlVTMSgwJgYJKoZIhvcNAQkBFhlsYXVyZW5jZS5zaW1vbkBjcGFuZWwu%0AbmV0MRQwEgYDVQQKEwtjUGFuZWwgSW5jLjEOMAwGA1UECBMFVGV4YXMxEDAOBgNV%0ABAcTB0hvdXN0b24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDRO0AP%0AN5XtjDqkEyJ6ctfYqUtt9yUXyRuCETFjW6opNLSmZSHeF6L2aZka646lhj02CFyl%0AkzsNSxysN66tY%2BWZcTmvgPisJdQFpFvjroJZgDjYRV0QqokKdRy%2F5BU0%2BtHXoYpj%0A9JOQlbvEWxiGR3R80sL1ma4AfSE6Gv8M%2FPULTadan51eHaikXqjOXdPJQKuWP3g9%0AFnIuf38WRYwzGrre88qsZrpsMrADX5dotHWgqAf7Tap6xfA4CUAgQo9tldariuVi%0ABz%2BsRJ%2FSjgxnhw1HYWGttBuBZFhMpdHpPnTJ7DIFMd%2FFN5gG%2Ftah30SapWpo35Ux%0A3BpJcdUjtazy82K5AgMBAAGjUDBOMB0GA1UdDgQWBBQAlv7%2FtALOYb7zAXbYG2%2B9%0AAMI3xjAfBgNVHSMEGDAWgBQAlv7%2FtALOYb7zAXbYG2%2B9AMI3xjAMBgNVHRMEBTAD%0AAQH%2FMA0GCSqGSIb3DQEBBQUAA4IBAQCxzpe71Hc7Es0dqIN7bhIFYIIgcr6wxM6a%0Aa9d%2BQG%2BQPH0x0KAqV8EgUbZysvyxEF0bPxW3ZAr1Is1wk80PMuU3bToFFVbFFIIr%0AHRNfKLGvxiMXnZA1c6L4N0lowvXHgZxTTUXtDFLXyrcwrLsvUErEV7rbizuxqfPw%0AcaRtXn4uc%2Bt6HYuW7yWesBauCWnJNiKbjN%2FF%2BuCTurN3QMAeWf3ZJtsfkAgk8dyq%0AR%2F83a3kDtSPrpt%2BjX%2BqdjKEpRtQ5Qpm6XT2gCOQPgnfiUtOCH419pp922P%2FAAGc%2B%0AZUhYoWcRWKw%2Fy6gI7Ru%2B%2B9%2B8%2BwkadL9EbKMZxhVwD5qVm4ZlWK2a%5Cr%5Cn%0A-----END%20CERTIFICATE-----' key='-----BEGIN%20RSA%20PRIVATE%20KEY-----%0AMIIEpAIBAAKCAQEA4AVM6J4Qg3DIFWr%2FeJ5GRmIATYsJIepKbrDy70sq%2BudcO8R8%0Axxak0oMZ%2F9mUdpjSNK%2FfLVTuCO0kxTfQ9VUWJllX7ThD6Zh9ZvlC%2Fnf%2FOEZLm3Zb%0ABgu8rbC8E9wuDOkKbJLnINgdhtowIydLK2MJ%2B%2Bq62bFV89jkHWTMcKyyqHENo3h%0Ac%2Blkpd9vnp8rZTinaVb7nX26uQqAFZYRo%2BWU0G%2FNPsq40QVSMoqPxyEz4qXo0hvu%0AIlCXmzFZq%2F6fCVPEKPLhQgMmpdBkMz4dVOazREfqXdjMD2%2BQXSNiA1AwWr8l0r4r%0AtzlxEYDJIR41yXp0xMl3KoolxMyvLBqZy32niQIDAQABAoIBAQCmbGmhWmPsMeoC%0At1WJFxQgD4goE0U6k%2BKt7vjbOt14Pk6v%2FB2yjaju1wSGpO59WLS4%2FXrwI2se6IXr%0Amba7u3VUEgWXLriNHoLy7%2FSMNTs%2BZEKhAMG36eNe3tVdT7busTag31r6sEMGGwCs%0AIwpU%2Bazosk0oylWLEX%2Fm%2FuHWEs1eaIEWWWtgHB%2BKZrrP7Rr9RYfVQ144DxmOxS3C%0Aa9%2BmST62WqAVPR6POWGEfZqnZl%2FePWZPcQYbFrhwnnefNoYBl%2FbnLZBo8rbNWxAq%0AOEOuKfkrBzglKG%2F39WKPw8rj4JIVzY0yOuFCW6xCDWRkOrhU8Ol%2F3FvwDa3uJpkp%0AmgPr4TgxAoGBAPGPLmxSuOYR97mDAXxrs037F2GCbqWvI6m7%2FezWe9yn%2BbMpjSIW%0Afsgtq4FsyqzPueEkDdQWi3xh6nu2WI%2F1Tl875opGAqEIJMqss%2Fu11tnva5wzu1cC%0AL6H85A5%2BHMOBvP3sm6CObKcVw92h7kxynVIUJJWhjfeZMN8gBFFpKIVFAoGBAO1p%0AtXBmXLC%2FYKKvtHI3M16%2FZopvM8ZqU2HcAHaw214Refw9JJ%2Fe3%2FxTNfSerVTyCAQO%0A1AdWTzJKBN8jmSYv1Mk1D3RpQPNR7wVzi46KR081AU41uMpqIGVOwHtyVnW%2FZfLr%0Ac1DLIK8Cx8aHfoxffwzoMO5SEQSooeZfOLhsfDN1AoGBAKQTUEINsj%2B75psgbAr6%0AELGgItJ9yPBLVRr%2BcUzEpx9LDWVvjMihpP4NX1gq8EOPWT%2BewLHVmmsjCyV6xw8J%0AXXF8e2xif3in0m3D%2FwCzE7u2T06rKM3B017hKnrZmGoHnrqPU2osM4sOUpshWX6d%0Av1Q4EF1%2BfbK3YCW%2BVpCBsB9NAoGAQo%2BuhNLODee56iKkzpjXWCsFTq6ar3hD5F3P%0A63buKdNwhd2GlSPhXFbf%2B7M5GWW6BZk6rMvv7EOAVice2uvyFm8%2F4%2F1WbmF8R%2BT7%0ALX1rPLO5p%2Fm701QpvP11TabiwqRkqtSEQhSRF0AKTojSW%2FyyHCZFAawUhV%2FZ9EKi%0AHmKb97kCgYAyzmFc2it0HqnsOnRybop603nqMtWGTQO4cxa93HUDpYajuK2K3Dfr%0AxUj6lG3z%2FoKJGGE2JqgZ6LBAhNJtJWJu2ox3pKGE63QjLJnVwb8y1NFYpe%2FcrbLe%0APuBwIR0L7drXxfv7O5btY7h6QI2d1%2FUIAQPAWbxLoTM%2BndQ%2FuPEdfA%3D%3D%0A-----END%20RSA%20PRIVATE%20KEY-----'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "install_ssl",
"module": "SSL",
"result": {"data": {"action": "update",
"cert_id": "example_com_bbe7e_16e2d_1369007999_1d87a0cdb540f5aae607b10e9a1a82fb",
"domain": "example.com",
"extra_certificate_domains": ["ssl.example.com"
],
"html": "The SSL certificate is now installed onto the domain \"example.com\" using the IP address \"192.168.0.1\".\nThe existing virtual host was updated with the new certificate. Apache is restarting in the background.",
"ip": "192.168.0.1",
"key_id": "bbe7e_16e2d_df7539f280eb1ecf6c1096190e41ada7",
"message": "The SSL certificate is now installed onto the domain \"example.com\" using the IP address \"192.168.0.1\".\nThe existing virtual host was updated with the new certificate.\nApache is restarting in the background.",
"statusmsg": "The SSL certificate is now installed onto the domain \"example.com\" using the IP address \"192.168.0.1\".\nThe existing virtual host was updated with the new certificate.\nApache is restarting in the background.\nThe SSL certificate is now installed onto the domain \"example.com\" using the IP address \"192.168.0.1\".\nThe existing virtual host was updated with the new certificate.\nApache is restarting in the background",
"user": "example",
"warning_domains": ["warning.com"
],
"working_domains": ["example.com"
]
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete SSL certificate

This function deletes an SSL certificate.

Note:

When you call this function, you must include the id or the friendly_name parameter.
This function only deletes certificates from SSL storage. To end SSL coverage for a domain, use the UAPI SSL::delete_ssl function instead.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestCert The certificate's friendly name.
id	string Example: id=example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3 The certificate's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  delete_cert

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_cert",
"module": "SSL",
"result": {"data": [{"created": 1538308800,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCert",
"id": "example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3",
"is_self_signed": 1,
"issuer.commonName": "example.com",
"issuer.organizationName": "Organization",
"issuer_text": "countryName\nUS\nstateOrProvinceName\nTX\nlocalityName\nHouston\norganizationName\nOrganization\ncommonName\nexample.com",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1569844800,
"not_before": 1538308800,
"serial": "45462cd0d6537b20cf2f3eb8aec07140",
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"subject_text": "commonName\nwww.example.com",
"validation_type": "dv"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete certificate signing request

This function deletes a certificate signing request (CSR).

Note:

When you call this function, you must include the id or the friendly_name parameter.
To delete a private key, use the UAPI SSL::delete_key function instead.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestCSR The CSR's friendly name.
id	string Example: id=example_com_e095f_0ab2f_ebcbe4a571276f48562241411556647f The CSR's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  delete_csr

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_csr",
"module": "SSL",
"result": {"data": [{"commonName": "example.com",
"created": 1538308800,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCSR",
"id": "example_com_e095f_0ab2f_ebcbe4a571276f48562241411556647f",
"key_algorithm": "rsaEncryption",
"modulus": "a74f7636fa6ac93ee6836a83a995b55deb5019ea36d7ba3dafb00e38d693acd\nb0c81b2ff777d6b433a420fae523f127f352a68bcc8b8f2d6ee7b70395bafab\nd8237ada8164fdddf8376b30375c35d4d4cbcce7d33d08069c17b409176a368\n9f1ebc97c0b08fe6ae44c19a92ac6d68448e7f1d13f3b360affd4222a51b4f3\n5342de99b5a1fb5548e438f2d824664562a448002eed7fce24dedc7dc3e1ed1\n79973d1dae959b33716eeb410d172708954e00632cbf60a0e26419860c8c0bc\n285d6bfe4b479de0dd189772a5dae676bd2a92acccc1369821be8cffddd8a7e\n6ecc061f8a32a9ae0661e4e946ed8e3827b277138d3a76116567cbd129cbd86\n9ef9dddf"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Delete private key

This function deletes a private key.

Note:

When you call this function, you must include the id or the friendly_name parameter.
To delete a certificate signing request (CSR), use the UAPI SSL::delete_csr function instead.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestKey The private key's friendly name.
id	string Example: id=example_com_e095f_0ab2f_ebcbe4a571276f48562241411556647f The private key's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  delete_key

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_key",
"module": "SSL",
"result": {"data": [{"created": 1538308800,
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestKey",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Create self-signed SSL certificate

This function generates a self-signed SSL certificate.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

countryName required	string <ISO-3166-1 (alpha-2)> Example: countryName=US The two-letter country code.
domains required	string <domain> Examples: domains=domains=example1.com,example2.com,example3.com - Generate certificates for multiple domains. domains=example.com - Generate a certificate for a domain. A comma-separated list of domains for which to generate the certificate.
emailAddress	string <email> Default: "" Example: [email protected] An email address to associate with the certificate.
friendly_name	string Example: friendly_name=TestCert A friendly name for the new certificate. This parameter defaults to the domain's name for which you generated the certificate.
key_id required	string Example: key_id=example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3 The key's ID.
localityName required	string Example: localityName=Houston The certificate's city or locality name.
organizationalUnitName	string Default: "" Example: organizationalUnitName=Department The certificate's organizational unit or department name.
organizationName required	string Example: organizationName=Organization The certificate's Organization Name.
stateOrProvinceName required	string Example: stateOrProvinceName=TX The two-letter state or locality abbreviation.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  generate_cert \
  domains='example.com' \
  countryName='US' \
  stateOrProvinceName='TX' \
  localityName='Houston' \
  organizationName='Organization' \
  key_id='example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "generate_cert",
"module": "SSL",
"result": {"data": {"created": 1538308800,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCert",
"id": "example_com_a74f7_9dddf_1446659822_eae1ff43c4ec1991e195877c55755eff",
"is_self_signed": 1,
"issuer.commonName": "example.com",
"issuer.organizationName": "Organization",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1569844800,
"not_before": 1538308800,
"serial": "01e57e4d92",
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"text": "-----BEGIN CERTIFICATE-----\nMIIGBzCCA++gAwIBAgIFAeV+TZIwDQYJKoZIhvcNAQELBQAwUjELMAkGA1UECAwC\nVFgxEDAOBgNVBAcMB0hvdXN0b24xCzAJBgNVBAYTAlVTMRMwEQYDVQQDDAptcmZy\nb2cuY29tMQ8wDQYDVQQKDAZjUGFuZWwwHhcNMjAwNjA4MTUyNjA0WhcNMjEwNjA4\nMTUyNjA0WjBSMQswCQYDVQQIDAJUWDEQMA4GA1UEBwwHSG91c3RvbjELMAkGA1UE\nBhMCVVMxEzARBgNVBAMMCm1yZnJvZy5jb20xDzANBgNVBAoMBmNQYW5lbDCCAiIw\nDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK/PpzRsms2ZZmA1EG2rNYZaAq2z\nbhUGN6YMpugDwPL9xuqDwf0WUdoBjSBbty7rb5zMCZ+Ty3xHFAo15TLQXqtM0zIo\nh/FRET9rtl6EuXFFFN+eAiV4GgZJVmVMmcgXNGgSjKZHhie5THkGJbwXXRxZryHN\nQIeLlT7DttSwoAh9rEbk6hHKyyoQQ4rSkNXREUZTN3Gk7u7et8iYWl1FBkmJkFDJ\nH4Ys678md7AiXndb4YkOQd2CEgoWXMaMLWJcFkdAmrIYhRmJvyp3BzF9hEkg+qPp\nVEyIL/xVxScdxiFKGWbiHr10UiFt/0+g0gToyUXCmsfo01p0oqrk4qRSZMnUtfdX\nW06vvD64x4Z4M4Jh5WqzVEXEdppzJx09Z7MBK6GLN82pV46x8jp87cBL1LZrpWDinerx+6Vr7YC62itfp6aJ2q6vkxCh4u8T6EjPEcpZAEh5SiQZaOLhAlqgt/lwPpuCW\nQ7LEi/Vg4aG3yb/z8e2BvRK5nnCHd7OOZqg7HJ9UnrzFxeQ8KyvcxP+oYD3h0EvZ\n1zVTbJDLbYuohqbLts3Skuk1hT9HoeWqrmzn2XkoU8LkvzCcRT0oG40BfFr4z7Zz\nsKfG9Z4e06kb1YAPrSqd9w/iI1Ej8cRhBBlowYFq9RjNlkjJCwKlxzynNAJjoQ5W\nU5NJzKjUz6ChHAAtAgMBAAGjgeMwgeAwHQYDVR0OBBYEFFczMNVfcxDsyk27GfjD\nC0Z1Yv+mMAkGA1UdEwQCMAAwfgYDVR0jBHcwdYAUVzMw1V9zEOzKTbsZ+MMLRnVi\n/6ahVqRUMFIxCzAJBgNVBAgMAlRYMRAwDgYDVQQHDAdIb3VzdG9uMQswCQYDVQQG\nEwJVUzETMBEGA1UEAwwKbXJmcm9nLmNvbTEPMA0GA1UECgwGY1BhbmVsggUB5X5N\nkjAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwFQYDVR0RBA4wDIIKbXJm\ncm9nLmNvbTANBgkqhkiG9w0BAQsFAAOCAgEArbNqSdABFWy8NbpDGDAoi2rpw/aM\nWu18iEAHmPg9YekIngNpxZg4b8SB4jrNSSqB0pK8asckxmAcho/pnAx4rOFibftd\nDmGzYxGN9h60JkVToWSn3UQ/0dbqfhfTbGiQvJHTNqB3pQVvWenMFRz9XEcpMDUj\n7UKR8v2xe5Y25yvNPVezYF2/x85awlOoSa00UlKgqh0OU+iuzQZ9T3wtk5uvlc7Z\nIEzBseIn3Kp/WG3P64Rxn95YT6QssKJ+pZ412yKM7vKdcuglNLTv5cx4ffKFN1jm\nanCmPXgYsUdAazmZVSjVuVN7d2+NL+SDVczZCdJ2Vhk5DPqv8ZnHUF7MT+K6vtQd\nJ16+pszCF55t9w5uPqur67/R00dCWLpxvHRRF8J+2Xverhmex5kR6a1nUlbP1oOP\nVq+EmcAL0PP6qdDr8fkjgvNyX7hT+cuiPBbxpY6XfDSlat5+5T2lJ1Ny6GWhBnaR\n35g3EF8ysu3AYQnDwtZrOrEa08lDN3mbrkT3ImSa5oZKgOrlpCZ0dzi8p4wSrboq\n9eZyqikEvuudz+VeQf1WR/6/FsyRq2PEtjgX1atWZiPfatN5f1YVxcElTvuMzyOP\nZXjpUs8MO+CHF1FwtKm52NNItIlnUY7KPpFU8L+oa8O2BMr91wi8NpTR2gd0F+jH\n21NkfEM7YlXzgMw=\n-----END CERTIFICATE-----\n",
"validation_type": null
},
"errors": null,
"messages": ["Certificate generated"
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Create private key

This function generates a private key.

Important:

You cannot call both the keytype and keysize parameters in a single call.
When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestKey A friendly name for the new key. This parameter defaults to the key's type, creation date, and creation time.
keysize	integer Deprecated Default: 2048 Example: keysize=2048 The key's modulus size. Note: Use the `keytype` parameter.
keytype	string Possible Values: "system" "rsa-2048" "rsa-4096" "ecdsa-prime256v1" "ecdsa-secp384r1" Example: keytype=rsa-2048 The key's type. `system` — The system's default value. `rsa-2048` — 2,408-bit RSA. `rsa-4096` — 4,096-bit RSA. `ecdsa-prime256v1` — ECDSA prime256v1 ("P-256"). `ecdsa-secp384r1` — ECDSA secp384r1 ("P-384"). This parameter defaults to the user's default SSL/TLS key type. Note: If you do not use this parameter, the system defaults to the `keysize` parameter's default value.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  generate_key

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "generate_key",
"module": "SSL",
"result": {"data": {"created": 1601467200,
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestKey",
"id": "example_com_a74f7_9dddf_1446659822_eae1ff43c4ec1991e195877c55755eff",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"text": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAyeiHvMuJuVk8ZEY6wMzUS1g0eWaHaIWmIRe+Qrn6SwiRrm1p\npsJCiGPPPQGOSg4FzrMXqE0zsi/Tk3hUO/EEsi7CcZe8cUanjlUeXhiwrb86FCMF\nOb9siRHQvlss7VCg8ZGXXTWZgf5yD3A1xPwdayYwF2Tc7GkNcZGUAI58geuYaq+U\nGiLczRGZep1IQ0b1cZnqDvGMx6AS6hiDqLISjnmXYY2OhG6Uyp+SuinjYzLPJ6eO\nN/7i9qqbcGmt0ssddmhR897+bTEom5SlSuyi03KZ9Rn4ZmNJgOsup9MclSBGxBys\nb6MuuM3N0/tF5QuwmDc8H6h2rNBP9vGV7RTTXQIDAQABAoIBAFS/WVoRRLmbjxG3\nuKl8UA9f8oaSVnu0vUpeoOl5Dmm4Kw2/tvzbxPlii3Xb1VGYGS/tVBy8atp74J6h\nfxm5zHLN1afAPMR/F41ShPCSBHapMUOKf4MBqhjOdYOw2Way1RsQNSxWdxxtJIr+\nWlNYTzDOUpk/KMvCPHZS2IBzTidpcFpDQ3pyDXjOoKJJH0EQWPtvxJNGrFqmU29D\n9WBqQemHnDrzg3s7JzQ5cGpbbCE+QX8IckNkslAkyhm771CtqWdeo+c45e6YfGcx\nKuAy1zGSVzQBuitzYoMUOL5olXLEj8fHzXd/cZP4yCyyabcGz2vi6luxF+28l1OL\nG1axyLECgYEA+bD5B+Y/Dp5hZ/uVR1bbvyraQpwbDesS1zgnJ53KOIl926dnWzIt\nUvM46+c9IF+UJrtzwIB6IvjAQioNFrK36bHgNGzNf9WQ54NN172qveaFLdW34z/i\nGR2ix/efm9OC41QREQ/5IKV07TibCwVazVBWascMPkH7FnguTvTCiosCgYEAzwJ+\nGPlIWjK+sqkK5JMUyuH43qAvgVfkZV906JpNRQH0Mob3bC0nXN95EoTwWXk68ULT\no1GHv9XLbj8e+Ok7kpJQZT5vEZnDN+cy3jdTLCvcjU5Q3ToImOTp9isSAFWRTbtk\nyabLNoIIsTR/ZwwPFTZcRiK2d8k7ZhcRKdfGnrcCgYAPZ06FoTukoDqsGoYkB4S4\n72DVmSHGIwlfg5ROylouULUV9ubWZmsLYfvR+cr4k0zlcsz6RDLEs4nQyx1RmCbm\nYNXPBiNLTpaI4b3MoGPHIVB3+mZEu60sFXr0UR9kkpDRi18eKVkaHXrwI3zVGjh2\n0Az0u2DS+mkOAs4AivLxbwKBgQC0XPqbLc+Bb0dCCREJmLD8GCkrZ6wcaQUB4krN\nQ2vhnVM0Fu5K3Yi3XapynUuA2aSmgtA9MxMw7MkjlHGa9DPIgBz2KZDCaBN0iMeE\nX/XivZCbucmxBxhohsLmjh5QFj3U2Vp2bBIQuvlx1EjQ8uvNUqDRJvuOoNFVIPH+\nYBeZPwKBgA//kXfNtNMHOpch699i3rgTzbRFDmGwsr1otzvJsXw7Pr2bM4WIzUJy\nG2SUSUlQRSZK4+BBKT9S0d7TynJD6X/6R7IBotZbfXs1myYxEsKj89/BQmr47x2h\nHjYVCClNoJlsbd5C2yu1R3PikweWGoVaxE3c+AN5knqjwJ0g21Cf\n-----END RSA PRIVATE KEY-----"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Create certificate signing request

This function generates a certificate signing request (CSR).

Note:

This function requires a valid key in the account's ssl directory. You can generate a key with UAPI's SSL::generate_key function.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and WebServer roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

countryName required	string <ISO-3166-1 (alpha-2)> Example: countryName=US The two-letter country code.
domains required	string Examples: domains=domains=example-1.com,example-1.com,example-2.com - Generate a certificate for multiple domains. domains=example.com - Generate a certificate for a single domain. A comma-separated list of the domains for which to generate the certificate.
emailAddress	string <email> Default: "" Example: [email protected] An email address to associate with the certificate.
friendly_name	string Example: friendly_name=TestCert A friendly name for the new certificate. This parameter defaults to the domain name for which you generated the certificate.
key_id required	string Example: key_id=example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3 The key's ID.
localityName required	string Example: localityName=Houston The certificate's city or locality name.
organizationalUnitName	string Default: "" Example: organizationalUnitName=Department The certificate's organizational unit or department name.
organizationName required	string Example: organizationName=Organization The certificate's organization.
stateOrProvinceName required	string Example: stateOrProvinceName=Texas The certificate's state or locality name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  generate_csr \
  domains='example.com' \
  countryName='US' \
  stateOrProvinceName='Texas' \
  localityName='Houston' \
  organizationName='Organization' \
  key_id='example_com_cb497_a394d_1397249671_d1272da8f13a1fd837493a5ad1f0a0f3'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "generate_csr",
"module": "SSL",
"result": {"data": {"commonName": "example.com",
"created": 1569884400,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCSR",
"id": "example_com_a74f7_9dddf_1446659822_eae1ff43c4ec1991e195877c55755eff",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"text": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC3TCCAcUCAQAwgZcxFDASBgNVBAMMC2V4YW1wbGUuY29tMRYwFAYDVQQLDA1E\nb2N1bWVudGF0aW9uMQswCQYDVQQGEwJVUzEiMCAGCSqGSIb3DQEJARYTbGF1cmVu\nY2VAY3BhbmVsLm5ldDEUMBIGA1UECgwLY1BhbmVsIEluYy4xDjAMBgNVBAgMBVRl\neGFzMRAwDgYDVQQHDAdIb3VzdG9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAp092NvpqyT7mg2qDqZW1XetQGeo217o9r7AOONaTrNsMgbL/d31rQzpC\nD65SPxJ/NSpovMi48tbue3A5W6+r2CN62oFk/d34N2swN1w11NTLzOfTPQgGnBe0\nCRdqNonx68l8Cwj+auRMGakqxtaESOfx0T87Ngr/1CIqUbTzU0LembWh+1VI5Djy\n2CRmRWKkSAAu7X/OJN7cfcPh7ReZc9Ha6VmzNxbutBDRcnCJVOAGMsv2Cg4mQZhg\nyMC8KF1r/ktHneDdGJdypdrmdr0qkqzMwTaYIb6M/93Yp+bswGH4oyqa4GYeTpRu\n2OOCeydxONOnYRZWfL0SnL2Gnvnd3wIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEB\nAFlolzJbcviWcdZUv+PJ7G8cAqFAxa8a3W2a0Y1U0BaMrpDfuOHpQgOtO62rr+i+\nhkrIReuk7Isyl6GoZkX17KhQ1Vo9aW8a8Ur7+0RGDbxRlK9jJWnvSFn6cMMqRSfA\nDXpptxhqBFZJIZMc3pPX9Jqycuu8bxeIvUKeSMe3Jxcl1ZXEXX47FeRZxvd+WXF9\n4Xu4KZXHdzb5tB6jPhzIaN0/3d92N/KhvCcnw3YC2fEGDkpOlZaoa7O72+aq5K3b\nM1htFv9deAHqIHefV41iOrxUCIKIhdPIjvAm774lDHLzPpJVrshO/NpA74LEkny5\nFMwKKx+6Jgx1HSWucn5kWek=\n-----END CERTIFICATE REQUEST-----"
},
"errors": null,
"messages": ["Certificate Signing Request generated!"
],
"metadata": { },
"status": 1,
"warnings": null
}
}

Update SSL certificate's friendly name

This function changes a certificate's friendly name.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name required	string Example: friendly_name=TestCert The certificate's friendly name.
new_friendly_name required	string Example: new_friendly_name=TestCert2 The certificate's new friendly name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  set_cert_friendly_name \
  friendly_name='TestCert' \
  new_friendly_name='TestCert2'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_cert_friendly_name",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update private key's friendly name

This function changes a key's friendly name.

Important:

You must call either the friendly_name or id parameter.
When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name required	string Example: friendly_name=TestKey The key's friendly name.
id required	string Example: id=a9b72_63971_2cb6d8897b362cfb1548e047d8428b8d The key's ID.
new_friendly_name required	string Example: new_friendly_name=TestKey2 The key's new friendly name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  set_key_friendly_name \
  friendly_name='TestKey' \
  id='a9b72_63971_2cb6d8897b362cfb1548e047d8428b8d' \
  new_friendly_name='TestKey2'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_key_friendly_name",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update SSL website for dedicated IP address

This function sets a new primary SSL website for a dedicated IP address.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

servername

required

string <domain>

Example: servername=hostname.example.com

The primary SSL website's servername.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  set_primary_ssl \
  servername='hostname.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_primary_ssl",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update certificate signing request's friendly name

This function changes a certificate signing request's (CSR) friendly name.

Important:

You must call either the friendly_name or id parameter.
When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name required	string Example: friendly_name=TestCSR The CSR's friendly name.
id required	string Example: id=example_com_eda9d_543fb_a3009b4b01a592390866ab3a47c0df18 The CSR's ID. Note: To retrieve a CSR's ID, use the UAPI `list_csrs` function.
new_friendly_name required	string Example: new_friendly_name=TestCSR2 The CSR's new friendly name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  set_csr_friendly_name \
  friendly_name='TestCSR' \
  id='example_com_eda9d_543fb_a3009b4b01a592390866ab3a47c0df18' \
  new_friendly_name='TestCSR2'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_csr_friendly_name",
"module": "SSL",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Export SSL certificate

This function retrieves a certificate.

Note:

When you call this parameter, you must include either the id or the friendly_name parameter.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestCert The certificate's friendly name.
id	string Example: id=example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041 The certificate's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  show_cert

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "show_cert",
"module": "SSL",
"result": {"data": {"cert": "-----BEGIN CERTIFICATE-----MIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQIDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYyMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNVBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3PXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fWvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/daM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6PLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGj\\UDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3WhcDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVwFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2agqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPaKm6r7YmwfLN/YMZBHXSR58oOGP9W-----END CERTIFICATE-----",
"details": {"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCert",
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"is_self_signed": 1,
"issuer": {"commonName": "example.com",
"countryName": "US",
"emailAddress": "[email protected]",
"localityName": "Houston",
"organizationName": "Organization",
"stateOrProvinceName": "Texas"
},
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"not_after": 1601467200,
"not_before": 1569844800,
"signature_algorithm": "sha256WithRSAEncryption",
"subject": {"commonName": "example.com",
"countryName": "US",
"emailAddress": "[email protected]",
"localityName": "Houston",
"organizationName": "Organization",
"stateOrProvinceName": "Texas"
},
"validation_type": "dv"
},
"text": "Certificate:\n Data:\n Version: 3 (0x2)\n Serial Number:\n d1:e8:74:8c:d0:69:d2:55\n Signature Algorithm: sha1WithRSAEncryption\n Issuer: CN = example.com, C = US, emailAddress = [email protected], O = Example, ST = Texas, L = Houston\n Validity\n Not Before: Apr 10 22:38:10 2013 GMT\n Not After : Apr 10 22:38:10 2014 GMT\n Subject: CN = example.com, C = US, emailAddress = [email protected], O = Example, ST = Texas, L = Houston\n Subject Public Key Info:\n Public Key Algorithm: rsaEncryption\n Public-Key: (2048 bit)\n Modulus:\n 00:c6:9c:e3:37:1a:fc:e6:1b:e4:29:4d:8e:ee:ec:\n bd:7a:52:12:ef: 34:71:64:77:e0:79:76:6d:ba:f0:\n 77:fd:f0:92:18:b0:84:c3:f7:12:3a:a9:b9:1d:16:\n 6c:a0:10:6d:f0:55:17:35:27:ff:81:a7:46:e6:d4:\n 36:97:34:01:3a:2f:6d:61:9a: 04:20:e3:fd:06:11:\n 8b:a4:5e:4f:6d:0d:93:8e:3b:cc:cb:19:b3:cb:74:\n 7a:54:82:ae:52:9e:46:31:7a:02:44:0b:7b:26:e8:\n 84:aa:91:2b:25:c1:42:0c:cc:5d:c4:d5: c4:cf:df:\n de:4c:7c:22:99:ab:06:79:99:16:1e:a7:49:5b:9b:\n 89:97:18:3c:1e:4b:c6:c5:b5:b2:9d:7d:be:b9:91:\n c6:08:38:7d:dc:81:18:2b:0c:2c:da:29:f4:aa:a2:\n 72:46:d9:c2:68:31:89:51:ab:32:af:7a:8d:9b:a7:\n d8:b8:b5:37:21:03:91:1d:4e:d8:fc:f1:0e:1f:96:\n 17:d6:90:25:c1:3a:1a:76:4c:9e:2b:7e:b9:9c:f5:\n 86:0a:cf:ea: 2f:eb:bc:33:ee:69:49:b9:c2:e6:a0:\n ef:ee:90:19:4a:2a:64:7e:ef:96:46:7e:7d:e2:35:\n ec:d9:cf:34:42:7a:3d:c1:22:b9:68:a2:b3:02:a3:\n 7f:f5\n Exponent: 65537 (0x10001)\n X509v3 extensions:\n X509v3 Subject Key Identifier:\n 6A:A1:EA:62:FB:B2:C4:AC:04:B0:43:DD:56:BE:8A:8D:FA:16:D3:F4\n X509v3 Authority Key Identifier:\n keyid:6A:A1:EA:62:FB:B2:C4:AC:04:B0:43:DD:56:BE:8A:8D:FA:16:D3:F4\n\n X509v3 Basic Constraints:\n CA:TRUE\n Signature Algorithm: sha1WithRSAEncryption\n 3c:1e:f7:3d:20:1b:a2:bd:5c:d6:0f:2a:9e:f3:b0:83:bf:a9:\n a0:90:9b:96:b1:a6:1e:8b:be:7c:f5:72:58:a0:48:3e:68: 43:\n 06:37:63:0a:cb:9c:23:98:c6:9e:f1:73:e8:4b:71:ac:07:fc:\n d0:5c:e1:55:4f:be:a7:75:5a:57:da:a1:c2:46:63:8f:3a:70:\n 4c:42:3c:03:4c:a0:47:a3:fc: ae:15:03:25:a5:78:63:a2:73:\n cd:47:d5:64:7c:d4:f5:85:f7:03:b8:b4:d8:95:75:6a:78:5c:\n e6:c7:69:02:7b:a4:fc:4d:8c:80:7b:c7:1c:71:04:ba:53:71:\n 7a: ce:00:cb:0e:5e:21:89:02:ba:90:02:8e:b5:79:8e:84:50:\n b0:21:63:b0:ac:19:80:c5:1d:a2:95:68:b7:ee:35:10:fa:db:\n f5:bf:b0:16:b1:34:76:f2:d6:ee:07:3b:6d:b6:0c:1d:b4:e5:\n 53:50:23:b8:c4:bf:fe:d6:77:ec:89:68:a0:d8:dd:f4:f5:fa:\n 7d:f6:c4:72:02:b1:e8:87:f7:e1:16:71:80:2e:e7:94:7b:eb:\n c6:a7:07:36:05:6d:34:b4:25:74:e9:c2:2c:9e:3d:bc:97:8e:\n 84:ce:cc:4f:1f:11:67:ad:30:f6:83:3e:be:bb:88:48:10:65:\n f7:4b:2f:80\n"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Export certificate signing request

This function retrieves a certificate signing request (CSR).

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Note:

When you call this function, you must include either the id or the friendly_name parameter.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestCSR The CSR's friendly name.
id	string Example: id=example_com_e095f_0ab2f_ebcbe4a571276f48562241411556647f The CSR's ID.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  show_csr

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "show_csr",
"module": "SSL",
"result": {"data": {"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC3TCCAcUCAQAwgZcxFDASBgNVBAMMC2V4YW1wbGUuY29tMRYwFAYDVQQLDA1E\nb2N1bWVudGF0aW9uMQswCQYDVQQGEwJVUzEiMCAGCSqGSIb3DQEJARYTbGF1cmVu\nY2VAY3BhbmVsLm5ldDEUMBIGA1UECgwLY1BhbmVsIEluYy4xDjAMBgNVBAgMBVRl\neGFzMRAwDgYDVQQHDAdIb3VzdG9uMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAp092NvpqyT7mg2qDqZW1XetQGeo217o9r7AOONaTrNsMgbL/d31rQzpC\nD65SPxJ/NSpovMi48tbue3A5W6+r2CN62oFk/d34N2swN1w11NTLzOfTPQgGnBe0\nCRdqNonx68l8Cwj+auRMGakqxtaESOfx0T87Ngr/1CIqUbTzU0LembWh+1VI5Djy\n2CRmRWKkSAAu7X/OJN7cfcPh7ReZc9Ha6VmzNxbutBDRcnCJVOAGMsv2Cg4mQZhg\nyMC8KF1r/ktHneDdGJdypdrmdr0qkqzMwTaYIb6M/93Yp+bswGH4oyqa4GYeTpRu\n2OOCeydxONOnYRZWfL0SnL2Gnvnd3wIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEB\nAFlolzJbcviWcdZUv+PJ7G8cAqFAxa8a3W2a0Y1U0BaMrpDfuOHpQgOtO62rr+i+\nhkrIReuk7Isyl6GoZkX17KhQ1Vo9aW8a8Ur7+0RGDbxRlK9jJWnvSFn6cMMqRSfA\nDXpptxhqBFZJIZMc3pPX9Jqycuu8bxeIvUKeSMe3Jxcl1ZXEXX47FeRZxvd+WXF9\n4Xu4KZXHdzb5tB6jPhzIaN0/3d92N/KhvCcnw3YC2fEGDkpOlZaoa7O72+aq5K3b\nM1htFv9deAHqIHefV41iOrxUCIKIhdPIjvAm774lDHLzPpJVrshO/NpA74LEkny5\nFMwKKx+6Jgx1HSWucn5kWek=\n-----END CERTIFICATE REQUEST-----",
"details": {"commonName": "example.com",
"countryName": "US",
"created": 1538265600,
"domains": ["example.com"
],
"emailAddress": "[email protected]",
"friendly_name": "TestCSR",
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"key_algorithm": "rsaEncryption",
"localityName": "Houston",
"modulus": "a74f7636fa6ac93ee6836a83a995b55deb5019ea36d7ba3dafb00e38d693acdb0c81b2ff777d6b433a420fae523f127f352a68bcc8b8f2d6ee7b70395bafabd8237ada8164fdddf8376b30375c35d4d4cbcce7d33d08069c17b409176a3689f1ebc97c0b08fe6ae44c19a92ac6d68448e7f1d13f3b360affd4222a51b4f35342de99b5a1fb5548e438f2d824664562a448002eed7fce24dedc7dc3e1ed179973d1dae959b33716eeb410d172708954e00632cbf60a0e26419860c8c0bc285d6bfe4b479de0dd189772a5dae676bd2a92acccc1369821be8cffddd8a7e6ecc061f8a32a9ae0661e4e946ed8e3827b277138d3a76116567cbd129cbd869ef9dddf",
"organizationName": "Organization",
"organizationalUnitName": "Department",
"stateOrProvinceName": "Texas"
},
"text": "Certificate Request:\n Data:\n Version: 0 (0x0)\n Subject: CN = example.com, C = US, emailAddress = [email protected], O = Example, ST = Texas, L = Houston\n Subject Public Key Info:\n Public Key Algorithm: rsaEncryption\n Public-Key: (2048 bit)\n Modulus:\n 00:bf:44:22:cb:13:2b:7f:41:9f:48:85:d6:2c:77:\n 03:cf:84:db:90:5c:5a:ed:e5:9c:cb:d6:9d:4b:fc:\n 67:58:b7:db:71:dd:eb:8e:5a:77:6f:03:5d:96:85:\n 60:dc:91:45:59:85:ff:9e:57:76:a5:b5:cd:dc:48:\n 25:89:3f:8f:17:c1:c2:1e:4d:ec:f0:08:1a:a9:cc:\n 2d:45:34:be:82:77:a5:e4:bb:0b:82:bc:82:51:c3:\n ac:1b:ed:c3:a4:b3:e6:14:4f:ba:9e:39:af:08:ae:\n 3c:2c:15:bd:dc:03:17:93:01:95:4f:c0:2a:0f:3b:\n 46:5f:5e:6f:96:d5:b2:dd:53:22:a9:91:e4:36:8e:\n f2:60:5b:ca:b3:72:e6:be:53:8b:9e:b6:72:26:04:\n 85:37:f4:89:c1:78:91:7d:46:96:71:c4:be:39:f3:\n cc:1d:79:bc:33:61:5c:5f:76:52:4a:7d:d0:60:31:\n 79:96:44:6e:6a:77:72:70:1f:3f:08:24:e6:d1:50:\n c0:6a:86:98:df:56:8b:ae:2f:c1:97:bc:ed:4c:70:\n a1:a6:b2:7e:25:97:8f:95:73:a1:84:71:43:da:33:\n 48:d5:44:17:e1:28:1e:37:93:63:fa:ec:45:17:39:\n e5:ff:62:90:6b:b2:eb:11:5b:32:b2:ce:51:0b:8a:\n 3e:95\n Exponent: 65537 (0x10001)\n Attributes:\n a0:00\n Signature Algorithm: sha1WithRSAEncryption\n 41:bd:99:89:7a:1b:c2:71:90:f7:5a:17:05:c9:77:c8:f0:0e:\n 62:0f:85:0d:fb:16:02:74:34:5f:7a:93:3e:50:8e:cf:f4:6f:\n ee:ab:7b:c9:ef:7c:76:59:dd:85:fd:7d:4e:ac:95:9d:b7:ae:\n 8a:89:fc:1f:5b:ee:ee:6b:cd:9b:4e:2d:2a:fb:1b:32:8f:8f:\n 56:70:d1:42:c1:72:ed:04:4b:27:5a:ee:5a:e1:2b:6e:53:59:\n aa:14:25:87:7f:2b:c3:7a:f5:b2:6c:71:2a:93:62:40:ca:87:\n b4:fe:34:a1:95:77:1e:98:f1:71:5e:14:97:61:73:07:8d:bc:\n 3e:e1:f8:47:f7:00:8b:06:a5:1c:84:a3:88:9a:7b:37:74:5d:\n 34:a6:ae:22:ab:a3:b8:9f:d7:ab:60:9a:70:81:15:13:0f:d9:\n ff:ab:7a:2b:fd:cb:96:04:ad:00:6b:e4:74:4e:59:57:a5:9e:\n 84:c7:74:d8:62:08:37:b3:ee:cc:74:b2:b6:26:e8:c0:37:32:\n 19:dc:1c:ff:97:4a:cc:1c:36:c3:a7:2d:ca:77:53:c4:1d:1c:\n 3c:36:5b:f8:90:46:01:48:49:61:9b:ef:bb:b3:a8:94:0b:3f:\n 50:51:93:29:9f:aa:9a:ab:ae:3d:3c:72:8a:0b:bc:2f:3f:19:\n d7:5d:70:14\n"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Export private key

This function retrieves a private key.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name	string Example: friendly_name=TestKey The key's friendly name. Note: You must use either the `id` or the `friendly_name` parameter.
id	string Example: id=example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041 The key's ID. Note: You must use either the `id` or the `friendly_name` parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SSL \
  show_key

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "show_key",
"module": "SSL",
"result": {"data": {"details": {"created": 1365633415,
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestKey",
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"key": "-----BEGIN RSA PRIVATE KEY-----\nMIIJJwIBAAKCAgEA4yilqsoCdEpiNOyLcPJ4FLT7vgwaLdOBeJLTMUeV2uZM4v65\n/tiZe7H0soDp1C55SCr3uEIEa7Lq7RUZ+F5p67BgRR19rmerKGxfN7N5Vu97pfTw\nW1f+lVsxUF/56lVeoAmm4okU98xJHiGGlI8ZHGJbUMYfLPy0OrA+gNwMHqMVOv1B\nSgpbEWCILMvnvtp0rwPutjnPVX2Dj40ia40L4Wqvp+0Yg7mZyhIOl+q6VZVIdXZs\nlR4ZywfRBYt3ieFBDYMyNw9wN3Xy44fCpHc77+ho84W3BqrGaWSSDyf6UkZGD5mf\nohGf2JSp+c8J6H7hsxo7pta3K1diVXFOSfnaA+k56zW445XruwYs/SN/zvGetGi6\nuqhMAcVRQcYCmLCixcC6RkcUx3exxgR4q3gthDnFvWC4+NuTh8/K0BcxcuCEhRug\n/MfVfO3+f7RJFSJPFb9m9Lf4HHBSVkDP5WtG4XiBKCe++9Wuvxbd4QxS7YrnSopN\nKxkuHKswH8ONpADMYDqfLODMhNrslHNHu95Nv7AlQr8weLqMGWMp7GFqzXcl39Rn\nVkF4Bxd3bAAsMN8/JvanMKCPjTTDrfzVFZcmHXPYOljYDdY1xfIstYVtbyFkUHZP\n2RPPBaPUAt90lzrKGVF8a2vdIKRiey5SZ5qu9c/mGri3oz7Lkk7qkNPAqDMCAwEA\nAQKCAgA3f9raG3j2CKZt381Bzzvfc0h+al6LC736Q4Ut6RuH2/S1ER9IUItPWW87\nnZuDp8ciBr13W0nRNmmHezxZHlgqqXEb8dSfI90Bh1jMNyFSSDihl3KSHrGotBsc\nVBavViREXZdUicGBuXuxtkYno96yvKUq2v0K9MLkA+OBgEHFynqJaw7klBsj573d\nlAQO8TjI+eD8zKsHbB8Ul5rtRAy/Cl3YXWk75cDZSggevc7A0jRd3o0w8aXDoSlE\nfYq7OTm3n3JJWZBFPKAXTzgTDr6qItJhjS4IxXsq7RNyeIYES/8aGKKT6lJvjALr\ncdYt47IpHCOu447lG/h+f6xtDophLGZoAirO7lJFRVfLJh76sLF12bpXJKbbmMN+\naut0nM+MLEw8A5K9OV24jJ/3+afj//5789asIyvNaQFPOX23SdLX0QbA5QWvJt2t\nWvvpS3ubcIJaBEMTK8asEBC68eUW0BBKJaSiYNzecUFYCBjQlxKsIrYuWZoW6fMy\nRel+cnqMdiH7r2p6RmgF5c9myDwq3E47jE+VrOy8uhw7EMQvT8+YSKaIbgtFZcUS\nU02BDRB7gWNa842m6nGs5tj5xFNQ6Wt410vilTwL+6zCQqJaKmcdE3woiIgSdrw5\nMssAHHjqo7QJthZfbpUAUTc6jGPNO13U1ediIRAGdQW5ALqTwQKCAQEA884bmFFZ\nLTewHIv1PJFfNxVZfk3C7LhWE2JcI/5P/YrN4ZA8G08OYhgxqa5XnsHHQPwMM85i\n1HeOoPwqgTMIyLDX/Sf88+eW3ef4V2M1Y4op0ahWFEwbwXKGxOhncElObN7dfZUw\nVlxCReaiw2XQAGRqtQC0f+9dZysqPJr+Rz6poTiOtm7DcpW/WiGfBPvVhzBENyqo\nuL9V3vCWYPJSLtCexECoGoPSpHKgUkwbh3+ra8SfG6FOIBj4PpMB82R7oPDjIyXF\n1VDfb0EwYQlKxyZoP9+NPT2MhZv/hF/Mbm/5LolVHx92hO9q6yxS6nvaFmEPr9fY\n1EOTWzzPOA+VyQKCAQEA7oVioaTqxENt+wHITZq100iYUpm4X1N1eENTp97QyQbQ\nOVR/t8iGLUdvOZdIxBSTS3JFQ8TNcGDPPc+o319QGdZABNnKwFGY3Ss+5QgVeX6n\n0WKdxCRelUOUB174aBeXcJCKplh6xBUrLfSZxvZQQb7fv0Mb+2eKUBKTymvES1kp\nYdn1T0vCCHA3bVpaHuqliCoDSX3RmQICZlfSgCGBbAkmU8RuxDd9yR9l7O9MXUmL\nsqlsw6hvbUt+7Y13YlDtyX8gbCwEEYsoALOotY1xNfXnyZKTAXhrg+xsQLrURYZU\noZiCJyK/mHCWRTPVkt89wq4IexbJ9hqlRjzpmlr8GwKCAQBxRSCs855q06SOnreh\nHCkQfmrFs3sMX9gdyWTllBG1yfc9BLXoOiKEkJkCLG2o5H6eQnuo1go0jBdH0+Ar\nhnpeQ0sV4q4y4zXEgzFt6Dm1tUsYjQzxASskBQF4GkF0eZpmGmTtI5MBjHt93llg\nTr0EcaLh1SIHDj5m4DcPUTMyBnro3E3xlCRZ6Biu10/6EMZzuIj42Gjq7HoIyd4T\nzIFCHsqkgyWWrAgBPwAdPB7OJRKPTxpcy+RwJSmwaLxPSC/n5gKhIbt4D8q+9Zp0\nesyzGbT1d/c2rJHMwV1FMvzXkk5CwKs7enKl8FXMTRt4tXHtU8rl93JVq8+aY/Yi\nJZuBAoIBAERG2lz7IFjeFHVtpTDRwIqilTfP2P8wnMe4PhInrgxdbu16SrUJKZ98\ne1I5BBNc8G0AYONtSoGItMo0z1phpkQ/GERLM8aplOB6qJ5XGg6VOuStHgwvfQOt\nPIp/nQvu9OK7/XRwj3Phu2KESiCyEXdAdDwDsdbdZLJXHwcqoh4Pf9EK2zW/seNI\nfBVJb9K5yHiZzicTZRQvhxBUw2T6MloCpH4GFM8GM3OHEV4pgeqSSvLxnLjFVmAq\n5EKL5Ei4cdjkExvj3aZH90N8KicOPgH8SkVhN8OL/Prein5c/LaKJV+8kEUzpTS1\nxc45cEGCteMsfjD97QINzpG0jgopUVECggEADIaKsx8NUQT3hm0wHRanEFJnQH5H\nzxaQjWbsjm2uz0KROPNIK1X5L8kypsb+EzlJtvWUqxPaOaTv4DZVpFaVzk8/2PPG\nsYR3mUjqMqNFYMrNwYZAXvJ/huzDPqq6+w2Pn9jcAifHNw3S8UR650v8gl7BU4fV\nBvhamG8JelvwLqeGWoikST9NBXVqG5IKBpUkUiFOMUNmRih9ooKvhy7GosoK8MWb\nmhWo1v8TTSXSagACUhAoIzb6mMN/VFC5WDbFx5AEB/G9tq/zmTqQkuo39dvgl30w\nyZGRNwc1aFf1Kxeven10/JN9ipp0mTa7NYSdn0RAe9ZRp5cCkgmktqmB0g==\n-----END RSA PRIVATE KEY-----",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048
},
"text": "Private-Key: (2048 bit)\nmodulus:\n 00:b1:16:ee:3e:de:ff:41:3c:f2:cb:b5:c5:0a:3d:\n    c8:0d:64:bc:02:9f:e1:90:c9:7f:da:e8:03:e6:2c:\n 47:9f:e4:ff:5e:0d:95:64:5d:32:c2:b7:c9:01:ae:\n    30:e5:17:da:82:78:f4:15:b9:46:40:eb:8b:99:5c:\n cc:4b:e4:2a:e4:ee:0e:28:29:01:79:ee:d4:90:bc:\n    5d:9e:ab:b0:46:7c:de:4f:df:b2:d7:d1:76:89:88:\n ad:f3:6c:36:f3:a0:07:8c:90:88:19:52:0a:68:a1:\n    4d:c0:26:9e:8d:53:70:91:83:87:f4:8a:d9:b5:0f:\n a7:ed:31:f3:8f:34:d2:ca:e7:d1:31:ea:42:17:5d:\n    4d:48:7d:b3:73:07:72:40:9a:58:55:c8:b3:b6:ff:\n c2:b5:f6:ba:64:bd:3e:06:62:42:cd:44:0b:d2:f1:\n    76:5e:bb:20:55:47:d4:10:86:2d:ec:6b:e7:d2:0e:\n 5d:99:48:ca:4d:66:35:e1:1a:db:1b:96:0a:41:64:\n    aa:c4:1b:1f:9d:90:e3:2e:aa:70:61:f7:77:b6:7b:\n f7:44:22:d8:73:0b:53:84:63:c3:f4:a4:19:e2:07:\n    f6:0b:42:8a:3d:70:cb:92:24:80:44:e7:36:5d:01:\n a2:e0:e5:cd:50:e1:f7:7c:5a:9a:b5:da:c4:0f:c4:\n    73:f5\npublicExponent: 65537 (0x10001)\nprivateExponent:\n 5b:c3:ae:21:16:1c:df:09:5e:27:01:41:e1:54:b2:\n    5d:7e:5d:8e:5e:9a:dc:14:0e:14:b9:35:8c:08:55:\n f5:1d:0c:d7:07:e2:e9:e7:01:6e:b5:1d:8b:a9:5f:\n    dc:d6:c7:7b:e4:81:56:e0:72:ef:21:1f:6d:91:10:\n ac:22:c7:b7:69:44:1c:bb:62:f0:74:39:e1:e6:39:\n    fd:06:aa:89:5c:1b:36:f8:8c:0c:19:96:7b:1e:40:\n 45:6b:45:ee:68:76:80:f8:44:0e:1a:dd:19:ea:bc:\n    07:5d:fb:ba:f0:09:dc:dd:73:8d:dc:85:83:b5:61:\n 27:20:43:3d:69:f9:f0:f9:e1:73:76:29:5a:b0:05:\n    23:65:47:e8:39:f0:21:be:17:84:73:0a:08:15:4e:\n 7b:e2:14:6a:72:c7:d3:13:ff:98:ee:96:c9:40:a3:\n    d3:0d:6c:90:48:25:7c:79:74:bf:be:fa:18:62:4d:\n c9:95:d4:d9:1a:47:59:4b:98:9a:2f:95:94:f4:4e:\n    78:cc:39:ef:9f:f7:6e:eb:db:cb:e5:95:ef:8f:ee:\n 5b:bf:c7:2a:29:e5:76:16:28:53:04:8e:ef:3f:66:\n    6f:34:a1:21:09:d6:da:ac:dd:ad:8c:2e:72:78:87:\n 01:45:f2:fa:3b:b9:23:2d:cf:5f:66:dc:c7:1c:0b:\n    e1\nprime1:\n 00:e9:14:c4:18:92:16:8e:ad:fd:cf:17:f0:8c:f7:\n 55:e0:58:3d:e3:cd:bd:4d:4e:00:64:ee:f0:cf:a5:\n    b0:14:19:85:ea:03:a8:be:18:78:34:3b:04:8c:b8:\n be:9a:ee:fc:0a:3e:6f:d2:8f:8f:fd:31:2d:02:97:\n    6e:bb:18:5b:9c:6a:85:6e:25:95:a4:40:4e:0b:91:\n a1:c3:85:bd:84:0c:d5:72:34:13:12:d9:20:56:52:\n    06:53:aa:06:2d:d0:61:2b:0b:d9:94:c6:d7:62:0f:\n c9:7d:17:cc:81:39:b3:59:e5:ce:77:d5:8a:82:ab:\n    2d:37:8a:51:49:3a:aa:c7:37\nprime2:\n 00:c2:80:b7:b4:85:25:37:30:b4:45:f3:3a:69:cf:\n    c3:86:43:89:db:d4:09:6b:72:54:a6:89:b4:a7:43:\n 3c:dd:da:c6:46:89:93:0a:05:9a:8c:d6:05:5c:6a:\n    4d:34:1e:84:5b:14:28:b7:ef:d2:be:a5:10:9c:5f:\n e7:35:fb:15:e2:9e:4a:60:0a:73:01:f0:55:6c:75:\n    25:8a:9b:b0:32:d3:28:41:11:e2:85:2d:f6:35:76:\n 6c:68:14:ba:02:98:44:82:e1:c6:ca:f7:07:78:ca:\n    ff:1a:60:3a:e1:88:91:55:a1:ae:11:46:29:4b:f0:\n 0f:e0:de:8a:0d:26:91:5c:33\nexponent1:\n    1d:2a:ad:13:4a:0c:aa:94:19:43:b6:02:33:11:ac:\n 5c:63:8e:73:18:46:cd:0a:aa:bf:f6:aa:89:c1:79:\n    14:3a:d1:68:24:47:14:6a:a9:78:17:be:8d:01:7d:\n 50:94:01:54:22:d6:09:6a:4f:a1:66:6a:f4:7d:10:\n    ad:36:f2:17:d3:b8:98:bc:f9:49:d1:86:32:aa:69:\n ac:b6:ea:ad:40:91:e1:35:a5:01:61:cc:4b:20:fe:\n    8b:af:a6:10:4b:98:2d:33:d1:69:6d:ac:7c:27:ef:\n 95:c8:c9:9d:8e:23:e4:66:fe:7c:3e:6b:93:c8:69:\n    e3:1e:5a:e7:a8:00:c0:e7\nexponent2:\n 6d:2e:3b:f0:c5:5c:a2:a2:60:4f:73:bd:32:70:41:\n    dd:38:44:46:75:bb:e3:e8:85:c4:06:40:b6:33:74:\n 13:45:1f:4f:b1:22:2c:da:00:6b:56:28:24:3c:37:\n    a2:2e:0f:35:e1:17:0a:49:41:0f:6b:30:eb:d6:99:\n bf:1f:76:a5:83:1d:54:d4:08:c2:e9:d9:c9:cb:e8:\n    8a:e9:e1:fa:65:b5:8e:f1:2f:2a:7b:26:5d:d4:5f:\n fd:fc:c4:7d:78:63:dc:e4:47:e6:de:cb:fe:ee:54:\n    4c:c5:ff:c7:62:15:d2:ef:b2:fa:57:5c:0f:18:6e:\n 91:57:da:3e:8f:8b:c1:29\ncoefficient:\n    00:bd:71:a9:3c:18:7b:0c:93:ab:d5:bf:f3:be:ea:\n 35:45:86:ce:60:0f:67:b3:2d:ba:5f:cf:9f:b6:1a:\n    13:27:cb:da:e7:ad:f3:c7:c2:06:7c:9e:00:d5:6c:\n 07:74:71:2c:35:39:c9:4b:24:cc:11:fd:60:c2:a2:\n    0b:28:b9:8b:4d:48:c6:0d:f0:39:34:dc:e2:c9:3a:\n b8:c6:64:0a:17:df:c4:f1:3d:fb:18:0b:af:ed:27:\n    3f:98:3b:e1:24:72:fc:5d:af:2c:e3:b6:07:3e:e1:\n 2f:fe:db:44:b0:8b:c3:e5:72:82:e5:a4:4a:3a:37:\n    8f:c4:9f:db:e9:1c:33:6a:f3\n"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Import SSL certificate

This function uploads a certificate.

Important:

Due to the limited field length of HTTP GET method calls, you must use the HTTP POST method. For this reason, you cannot use a cPanel or Webmail session URL to call this function.
When you disable the Calendar and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

crt

required

string <pem-certificate>

Example: crt="-----BEGIN CERTIFICATE-----/nMIIDcTCCAlmgAwIBAgIFAU+BNVgwDQYJKoZIhvcNAQEFBQAwUTESMBAGA1UEAwwJc2lza28udGxkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGY1BhbmVsMQswCQYDVQQIDAJUWDEQMA4GA1UEBwwHSG91c3RvbjAeFw0xNDEwMDYyMjI2MTlaFw0xNTEwMDYyMjI2MTlaMFExEjAQBgNVBAMMCXNpc2tvLnRsZDELMAkGA1UEBhMCVVMxDzANBgNVBAoMBmNQYW5lbDELMAkGA1UECAwCVFgxEDAOBgNVBAcMB0hvdXN0b24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9zx6zGiHdmWA0dKtoXmJiWXpZ9E3PXx3YHsjFEWW7e5pH0vZ+jVMzDmm5nsJ7RXrAkZO1IvpIpVLvoQfiJOWVvkD+o9fWvoK1tWJS72FSgPju+58mA2ieBuc87A790Pzuv1P3NR3zFLAjUR99zkHR1fpri/daM3PBWO8ET48FWkyU1kOeZaUlF67/+wrEiNgg+t1qhKOCAB61PdNVkLaSGHimksuC+Czk8Kq9nuS0E0TCnDtjjEyJ455FUcaCfczlTb8xkB/F9ORe74yTzD+vlk0tFMG6PLj/ajIwWqwO0qmQ8wX3NRxkWgGz5kVO1wrVJarKQ5EYQ3/mgvit0v6dAgMBAAGjUDBOMB0GA1UdDgQWBBRw+wKBo34+bgexjAa3EMDsgSCd7zAfBgNVHSMEGDAWgBRw+wKBo34+bgexjAa3EMDsgSCd7zAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQCHRXIs53opzKM2rM8Qe8lcw524WK6hqy2EWrZHp78N7rU7/6DQ/I3hv3WhcDDIO04I2/Xhe88MLBaLoM367Ya+vy7CaLr14aLi/SfQszMA0ALBvMao+Fis0iVwFYq/NLgSXw+fgnpFskt8v8iQZ+4Kaal8U8e9sVgu8m0RgO7rzym1eRiIKpsKd1rh/SD7LbSN7M7TRL3QqF7ltw9sQhAAsQcRaBBF21pdWrqhiGZ+Eioo3hhgwNavH2agqz78ddHwrFpHFwrEeUk1OfpPb76MYIce7xIy/4oQNdg6fOq4l/FrajBv+WkzDVPaKm6r7YmwfLN/YMZBHXSR58oOGP9W/n-----END CERTIFICATE-----"

The certificate's contents.

friendly_name

string

Example: friendly_name=TestCert

The certificate's friendly name.

Request Body schema: multipart/form-data

The certificate's contents.

crt	string <pem-certificate> The certificate file.
friendly_name	string The certificate's friendly name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  SSL \
  upload_cert

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "upload_cert",
"module": "SSL",
"result": {"data": [{"created": 1569844800,
"domains": ["example.com"
],
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestCert",
"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
"is_self_signed": 1,
"issuer.commonName": "VeriSign Trial Secure Server CA - G2",
"issuer.organizationName": "VeriSign, Inc.",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048,
"not_after": 1601467200,
"not_before": 1569844800,
"signature_algorithm": "sha256WithRSAEncryption",
"subject.commonName": "example.com",
"validation_type": "dv"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Import private key

This function uploads a private key.

Note:

Due to the limited field length of HTTP GET method calls, you must use the HTTP POST method. For this reason, you cannot use a cPanel or Webmail session URL to call this function.

Important:

When you disable the Calendars and Contacts, Receive Mail, Web Disk, Webmail, and Web Server roles, the system disables this function.

Authorizations:

BasicAuth

query Parameters

friendly_name

string

Example: friendly_name=TestKey

The key's friendly name.

key

required

string <pem-private-key>

Example: key="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAyeiHvMuJuVk8ZEY6wMzUS1g0eWaHaIWmIRe+Qrn6SwiRrm1p\npsJCiGPPPQGOSg4FzrMXqE0zsi/Tk3hUO/EEsi7CcZe8cUanjlUeXhiwrb86FCMF\nOb9siRHQvlss7VCg8ZGXXTWZgf5yD3A1xPwdayYwF2Tc7GkNcZGUAI58geuYaq+U\nGiLczRGZep1IQ0b1cZnqDvGMx6AS6hiDqLISjnmXYY2OhG6Uyp+SuinjYzLPJ6eO\nN/7i9qqbcGmt0ssddmhR897+bTEom5SlSuyi03KZ9Rn4ZmNJgOsup9MclSBGxBys\nb6MuuM3N0/tF5QuwmDc8H6h2rNBP9vGV7RTTXQIDAQABAoIBAFS/WVoRRLmbjxG3\nuKl8UA9f8oaSVnu0vUpeoOl5Dmm4Kw2/tvzbxPlii3Xb1VGYGS/tVBy8atp74J6h\nfxm5zHLN1afAPMR/F41ShPCSBHapMUOKf4MBqhjOdYOw2Way1RsQNSxWdxxtJIr+\nWlNYTzDOUpk/KMvCPHZS2IBzTidpcFpDQ3pyDXjOoKJJH0EQWPtvxJNGrFqmU29D\n9WBqQemHnDrzg3s7JzQ5cGpbbCE+QX8IckNkslAkyhm771CtqWdeo+c45e6YfGcx\nKuAy1zGSVzQBuitzYoMUOL5olXLEj8fHzXd/cZP4yCyyabcGz2vi6luxF+28l1OL\nG1axyLECgYEA+bD5B+Y/Dp5hZ/uVR1bbvyraQpwbDesS1zgnJ53KOIl926dnWzIt\nUvM46+c9IF+UJrtzwIB6IvjAQioNFrK36bHgNGzNf9WQ54NN172qveaFLdW34z/i\nGR2ix/efm9OC41QREQ/5IKV07TibCwVazVBWascMPkH7FnguTvTCiosCgYEAzwJ+\nGPlIWjK+sqkK5JMUyuH43qAvgVfkZV906JpNRQH0Mob3bC0nXN95EoTwWXk68ULT\no1GHv9XLbj8e+Ok7kpJQZT5vEZnDN+cy3jdTLCvcjU5Q3ToImOTp9isSAFWRTbtk\nyabLNoIIsTR/ZwwPFTZcRiK2d8k7ZhcRKdfGnrcCgYAPZ06FoTukoDqsGoYkB4S4\n72DVmSHGIwlfg5ROylouULUV9ubWZmsLYfvR+cr4k0zlcsz6RDLEs4nQyx1RmCbm\nYNXPBiNLTpaI4b3MoGPHIVB3+mZEu60sFXr0UR9kkpDRi18eKVkaHXrwI3zVGjh2\n0Az0u2DS+mkOAs4AivLxbwKBgQC0XPqbLc+Bb0dCCREJmLD8GCkrZ6wcaQUB4krN\nQ2vhnVM0Fu5K3Yi3XapynUuA2aSmgtA9MxMw7MkjlHGa9DPIgBz2KZDCaBN0iMeE\nX/XivZCbucmxBxhohsLmjh5QFj3U2Vp2bBIQuvlx1EjQ8uvNUqDRJvuOoNFVIPH+\nYBeZPwKBgA//kXfNtNMHOpch699i3rgTzbRFDmGwsr1otzvJsXw7Pr2bM4WIzUJy\nG2SUSUlQRSZK4+BBKT9S0d7TynJD6X/6R7IBotZbfXs1myYxEsKj89/BQmr47x2h\nHjYVCClNoJlsbd5C2yu1R3PikweWGoVaxE3c+AN5knqjwJ0g21Cf\n-----END RSA PRIVATE KEY-----"

The key's contents.

Request Body schema: multipart/form-data

The certificate's contents.

crt	string <pem-private-key> The key's contents.
friendly_name	string The key's friendly name.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
HTTP Request (Wire Format)

uapi --input=json --output=jsonpretty \
  --user=username \
  SSL \
  upload_key

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "upload_key",
"module": "SSL",
"result": {"data": [{"created": 1569844800,
"ecdsa_curve_name": null,
"ecdsa_public": null,
"friendly_name": "TestKey",
"id": "bbe7e_16e2d_df7539f280eb1ecf6c1096190e41ada7",
"key_algorithm": "rsaEncryption",
"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
"modulus_length": 2048
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Verify Domain Ownership

SSL Certificates / Verify Domain Ownership

Verify domain ownership via DNS

This function checks whether the account's domains can pass Domain Control Validation (DCV) via a DNS request.

Authorizations:

BasicAuth

query Parameters

domain

required

string <domain>

Examples:

domain=domain-0=example.com&domain-1=example2.com - Check multiple domains.
domain=example.com - Check a single domain.

The domain or domains to check.

Note:

To check multiple domains, increment the parameter name. For example, domain-0, domain-1, and domain-2.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DCV \
  check_domains_via_dns \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_domains_via_dns",
"module": "DCV",
"result": {"data": [{"dcv_string": "_dcv-test-record=wsWRlG9IsG7KNnLdIsx9Oz2oTw8m5q0imRR9L6LnDBz14sZelvDHqrJyJc6LA0DY",
"domain": "example.com",
"failure_reason": "The DNS query to _dcv-test-record.example2.org for the DCV challenge returned no TXT record that matches the value _dcv-test-record=wRUFPTN1DskKDG8KHfYM_5cQF5QUGWq1_A2ovO8rKsrIYO_HilAjsQABFCrbJkLX.",
"query_results": ["_dcv-test-record=wsWRlG9IsG7KNnLdIsx9Oz2oTw8m5q0imRR9L6LnDBz14sZelvDHqrJyJc6LA0DY"
],
"succeeded": 1,
"zone": "example.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Verify domain ownership via HTTP

This function checks whether the account's domains can pass Domain Control Validation (DCV) via an HTTP request.

Authorizations:

BasicAuth

query Parameters

dcv_file_allowed_characters	Array of strings Default: "A&dcv_file_allowed_characters=B&dcv_file_allowed_characters=C&dcv_file_allowed_characters=D&dcv_file_allowed_characters=E&dcv_file_allowed_characters=F&dcv_file_allowed_characters=G&dcv_file_allowed_characters=H&dcv_file_allowed_characters=I&dcv_file_allowed_characters=J&dcv_file_allowed_characters=K&dcv_file_allowed_characters=L&dcv_file_allowed_characters=M&dcv_file_allowed_characters=N&dcv_file_allowed_characters=O&dcv_file_allowed_characters=P&dcv_file_allowed_characters=Q&dcv_file_allowed_characters=R&dcv_file_allowed_characters=S&dcv_file_allowed_characters=T&dcv_file_allowed_characters=U&dcv_file_allowed_characters=V&dcv_file_allowed_characters=W&dcv_file_allowed_characters=X&dcv_file_allowed_characters=Y&dcv_file_allowed_characters=Z&dcv_file_allowed_characters=0&dcv_file_allowed_characters=1&dcv_file_allowed_characters=2&dcv_file_allowed_characters=3&dcv_file_allowed_characters=4&dcv_file_allowed_characters=5&dcv_file_allowed_characters=6&dcv_file_allowed_characters=7&dcv_file_allowed_characters=8&dcv_file_allowed_characters=9" An array of characters that the certificate provider allows in the DCV check file's filename.
dcv_file_extension	string Default: "" Example: dcv_file_extension=txt The DCV check file extension that the certificate provider requires.
dcv_file_random_character_count	integer >= 1 Default: 100 Example: dcv_file_random_character_count=32 The number of characters that the certificate provider allows in the DCV check file's filename.
dcv_file_relative_path	string Default: ".well-known/pki-validation" Example: dcv_file_relative_path=.well-known/pki-validation The DCV check file's file path, relative to the domain's document `root` directory.
dcv_max_redirects	integer or null >= 0 Default: null Example: dcv_max_redirects=2 The number of domain redirects the system permits the DCV check to follow. The function checks the provider's supported number of redirects. It will then return the `redirect` array of objects for the passed value, plus one. This ensures the function will display any redirects causing DCV failures, if any exist. Note: If you pass a `0` value, this function does not limit the number of redirect returns. Use the `Market::get_provider_specific_dcv_constraints` UAPI function to list a provider's supported number of redirects.
dcv_user_agent_string	string Example: dcv_user_agent_string=SECTIGO+DCV The user agent string that the system uses for the imitated local DCV check. Important: The default value can change at any time.
domain required	string <domain> Examples: domain=domain-1=example.com&domain-2=example2.com&domain-3=example2.com - Check multiple domains. domain=example.com - Check a single domain. The domains to check. Note: To check more than one domain, repeat or increment the parameter name. For example, `domain-1`, `domain-2`, and `domain-3`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DCV \
  check_domains_via_http \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "check_domains_via_http",
"module": "DCV",
"result": {"data": [{"failure_reason": "The system queried for a temporary file at http://example.com/.well-known/pki-validationD01511F4E E535A5442FC378AA946CF41.txt, but the web server responded with the following error: 404 (Not Found). A DNS (Domain Name System) or web server misconfiguration may exist. The domain example.com resolved to an IP address 93.184.216.34 that does not exist on this server.",
"redirects": [{"content": "<!DOCTYPE HTML PUBLIC \\\"-//IETF//DTD HTML 2.0//EN\\\">\\n<html><head>\\n<title>301 Moved Permanently</title>\\n </head><body>\\n<h1>Moved Permanently</h1>\\n <p>The document has moved <a href=\\\"http://www.example.com/.well-known/pki-validation/770102 17B0CCF0CCF6211602F9A1B2B2.txt\\\">here</a>.</p>\\n</body></html>\\n",
"headers": { },
"protocol": "HTTP/1.1",
"reason": "Moved Permanently",
"redirects": null,
"status": 301,
"success": "",
"url": "http://example.com/.well-known/pki-validation/77010217B0CCF0CCF6211602F9A1B2B2.txt"
}
],
"redirects_count": 0
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Verify domain ownership Deprecated

This function indicates whether the account's domains can pass a Domain Control Validation (DCV) check.

Warning:

We deprecated this function. Use UAPI's DCV::check_domains_via_http function.

Authorizations:

BasicAuth

query Parameters

domain

required

string

Examples:

domain=domain-1=example1.com domain-2=example2.com domain-3=example3.com - Check multiple domains.
domain=domain=example1.com domain=example2.com domain=example3.com - Check multiple domains.
domain=example.com - Check a single domain.

The domains to check.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, domain-1, domain-2, and domain-3.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  DCV \
  ensure_domains_can_pass_dcv \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ensure_domains_can_pass_dcv",
"module": "DCV",
"result": {"data": [null,
null,
"The domain resolves to Mars. Beep beep beep."
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Domain Statistics

Statistics / Domain Statistics

Return bandwidth statistics for all domains

This function retrieves a list of bandwidth records for the domains on a cPanel account.

Note:

This function also returns the bandwidth use of a distributed cPanel account.

Warning:

This function requires the Bandwidth Stats feature. To enable this feature, use WHM's Feature Manager interface (WHM >> Home >> Packages >> Feature Manager).

Authorizations:

BasicAuth

query Parameters

timezone

string

Example: timezone=America/Chicago

The timezone in which to report the data, in Olson tz format.

Note:

This parameter defaults to the server's timezone.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Stats \
  get_bandwidth

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_bandwidth",
"module": "Stats",
"result": {"data": [{"bytes": 74845,
"domain": "example.com",
"month_start": 1561957200,
"protocol": "imap"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return specified domain access log

This function returns entries from a domain's error log.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain for which to return error log entries.
log	string Possible Values: "error" "suexec" Example: log=suexec The Apache log file to query. This parameter defaults to error. `error` - The `/var/log/apache2/error_log` file. `suexec` - The `/var/log/apache2/suexec_log` file.
maxlines	integer [ 1 .. 5000 ] Default: 300 Example: maxlines=250 The number of lines to retrieve from the error log.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Stats \
  get_site_errors \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_site_errors",
"module": "Stats",
"result": {"data": [{"date": 1234576704,
"entry": "[Fri Feb 13 19:58:24.420593 2009] [core:error] [pid 29228:tid 47876185720577] (13)Permission denied: [client 10.0.0.2:62908] AH00132: file permissions deny server access: /home/user/public_html/index.html"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return Analog statistics for all domains

This function displays the Analog statistics for the domains on a cPanel account.

Authorizations:

BasicAuth

query Parameters

engine required	string Possible Values: "webalizer" "analog" Example: engine=webalizer The statistics engine. `webalizer` `analog`
traffic	string Default: "http" Possible Values: "http" "ftp" Example: traffic=http The web traffic type. `http` `ftp`

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Stats \
  list_sites \
  engine='webalizer'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_sites",
"module": "Stats",
"result": {"data": [{"all_domains": 1,
"domain": "example.com",
"path": "/tmp/user/webalizer/index.html",
"ssl": 1
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return Analog statistics for specified domain

This function returns a domain's Analog statistics.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain from which to retrieve statistics.
engine required	string Value: "analog" Example: engine=analog The statistics engine. `analog` is the only possible value.
ssl	integer Default: 1 Possible Values: 0 1 Example: ssl=1 Whether to return statistics from SSL requests. `1` - Return statistics for SSL requests. `0` - Return statistics for non-SSL requests.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Stats \
  list_stats_by_domain \
  engine='analog' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_stats_by_domain",
"module": "Stats",
"result": {"data": [{"date": 1565795929,
"url": "tmp/cptest/analog/8.html.com"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Weblog Settings

Statistics / Weblog Settings

Save current user's weblog analyzers configuration

This function saves the users choice about which web log anayzers are enabled for each domain on their cPanel users account. If the log anayzers are controlled by the reseller or root account, the user cannot manage which log analyzers are enabled or disabled.

Important:

When you disable the WebServer role the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:

BasicAuth

Request Body schema: application/json

List of domains and what web log analyzers to change.

Array of objects

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

Payload
CLI
HTTP Request (Wire Format)

Content type

application/json

{"changes": [{"analyzers": [{"enabled": 1,
"name": "awstats"
},
{"enabled": 0,
"name": "analog"
},
{"enabled": 0,
"name": "webalizer"
}
],
"domain": "domain.com"
}
]
}

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "save_configuration",
"module": "StatsManager",
"result": {"data": [{"analyzers": [{"available": 1,
"enabled": 1,
"locked": 0,
"name": "awstats"
},
{"available": 1,
"enabled": 0,
"locked": 0,
"name": "analog"
},
{"available": 0,
"enabled": 0,
"locked": 0,
"name": "webalizer"
}
],
"domain": "user"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Returns weblog analyzers' configuration

This function lists the configuration of the web log anayzers for each domain on the cPanel account.

Important:

When you disable the WebServer role the system disables this function. For more information, read our How to Use Server Profiles documentation.

Note

Additional web log analyzer configuration such as if the user can edit their own configuration is provided in the metadata section of the return.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  StatsManager \
  get_configuration

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_configuration",
"module": "StatsManager",
"result": {"data": [{"analyzers": [{"enabled": 1,
"enabled_by_user": 1,
"name": "awstats"
},
{"enabled": 0,
"enabled_by_user": 0,
"name": "analog"
},
{"enabled": 0,
"enabled_by_user": 1,
"name": "webalizer"
}
],
"domain": "domain.com"
}
],
"errors": null,
"messages": null,
"metadata": {"analyzers": [{"available_for_user": 1,
"enabled_by_default": 0,
"name": "analog"
},
{"available_for_user": 1,
"enabled_by_default": 1,
"name": "awstats"
},
{"available_for_user": 1,
"enabled_by_default": 0,
"name": "webalizer"
}
],
"locked": 1,
"transformed": 1
},
"status": 1,
"warnings": null
}
}

UserData

The UserData module for cPanel UAPI.

Set scoped userdata key/value

This function sets (creates or updates) a userdata key/value pair within a specified scope and returns the full updated mapping for that scope.

Authorizations:

BasicAuth

query Parameters

json	string Example: json={"theme":"dark"} A json string to save to the specified scope. Note: The "json" argument cannot be used with the "key" or "value" arguments.
key	string Example: key=theme The userdata key to set. Note: The "json" argument cannot be used with the "key" or "value" arguments.
scope required	string Example: scope=example_scope The scope name to modify.
value	string Example: value=dark The value to assign to the key. Note: The "json" argument cannot be used with the "key" or "value" arguments.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
--user=username \
UserData \
set_scoped_userdata \
scope=ui_prefs \
key=theme \
value=dark

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_scoped_userdata",
"module": "UserData",
"result": {"data": {"theme": "dark",
"items_per_page": "50",
"show_help_tour": "0"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return scoped userdata mapping

This function returns all userdata key/value pairs for a given scope.

Authorizations:

BasicAuth

query Parameters

scope

required

string

Example: scope=example_scope

The scope name whose userdata you wish to retrieve.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
--user=username \
UserData \
get_scoped_userdata \
scope=ui_prefs

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_scoped_userdata",
"module": "UserData",
"result": {"data": {"theme": "dark",
"items_per_page": "50",
"show_help_tour": "0"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

EA4

The EA4 module for UAPI.

Get EA4 configuration recommendations

This function retrieves a list of EasyApache 4 (EA4) configuration recommendations.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EA4 \
  get_recommendations

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_recommendations",
"module": "EA4",
"result": {"data": {"ea-php55-php": [{"desc": "PHP DSO runs as the user [asis,nobody] by default. In a shared hosting environment, this is a security issue.",
"level": "danger",
"name": "PHP DSO",
"on": "add",
"options": [{"items": ["ea-apache24-mod_ruid2",
"ea-apache24-mod_mpm_itk"
],
"level": "success",
"recommended": true,
"text": "We strongly recommend that you install one of the following packages unless this is a single-user system:"
},
{"level": "warning",
"recommended": false,
"text": "If you use suPHP, you will add some security, but may experience performance issues on your server."
}
],
"url": "https://www.example.com"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

EasyApache Settings

Web Server Configuration / EasyApache Settings

PHP

PHP recommendations

Get custom PHP recommendations.

This function returns a list of recommended PHP versions.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  EA4 \
  get_php_recommendations

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_php_recommendations",
"module": "EA4",
"result": {"data": ["php80"
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Application Manager

Web Server Management / Application Manager

Disable Passenger application

This function disables a Passenger application on an account.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=slippers

The application to disable.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  disable_application \
  name='slippers'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_application",
"module": "PassengerApps",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update Passenger application settings

This function edits a Passenger application for an account.

Note:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

clear_envvars	integer Default: 0 Possible Values: 0 1 Example: clear_envvars=0 Whether to clear the application’s environment variables.
deployment_mode	string Possible Values: "production" "development" Example: deployment_mode=production The new server environment in which to run the application. If you do not use this parameter, the function does not change the application’s server environment. `development` — Sets the application to run in a development environment. `production` — Sets the application to run in a production environment.
domain	string <domain> Example: domain=toto.com The application’s new domain. If you do not use this parameter, the function does not change the application’s domain.
enabled	integer Default: 1 Possible Values: 0 1 Example: enabled=1 Whether to enable the application and generate the web server configuration for it. `1` — Enable the application and generate the web server configuration. `0` — Don’t enable the application and generate the web server configuration.
envvar_name	Array of strings Example: envvar_name=SCARECROW&envvar_name=TINMAN&envvar_name=LION New set of environment variables for the application. Important: The function replaces all current environment variables with the variables that you pass in this parameter. Note: For each `envvar_name` parameter you send you must include an `envvar_value` parameter.
envvar_value	Array of strings [ 1 .. 1024 ] characters Example: envvar_value=brain&envvar_value=heart&envvar_value=courage Each environment variable’s value. Note: For each `envvar_name` parameter you send you must include an `envvar_value` parameter.
name required	string Example: name=Ruby Slippers The application’s current name.
new_name	string Example: new_name=Little Dog The application’s new name. If you do not use this parameter, the function does not change the application's name.
path	string <path> Example: path=/home/dorothy/littledog The application’s new filepath. If you do not use this parameter, the function does not change the application’s filepath.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  edit_application \
  name='Ruby Slippers'

Response samples

200

Content type

application/json

{"data": {"Little Dog": {"base_uri": "/littledog",
"deployment_mode": "production",
"domain": "toto.com",
"enabled": 1,
"envvars": {"LION": "courage",
"SCARECROW": "brain",
"TINMAN": "heart"
},
"name": "Little Dog",
"path": "/home/dorothy/littledog"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1
}

Install Passenger application dependencies

This function installs the dependencies for a Passenger application.

Note:

This function starts the installation process. This may take a long time to complete.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

app_path required	string <path> Example: app_path=/home/example/my-app/ The application’s filepath.
type required	string Possible Values: "gem" "npm" "pip" Example: type=npm The application’s type. `gem` — Ensure ruby gems in the application’s `Gemfile` file. `npm` — Ensure node packages in the application’s `package.json` file. `pip` — Ensure python pips in the application’s `requirements.txt` file.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  ensure_deps \
  type='npm' \
  app_path='/home/example/my-app/'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "ensure_deps",
"module": "PassengerApps",
"result": {"data": {"sse_url": "/sse/UserTasks/00000000_5c6c8b18228a35/ensure_deps.log",
"task_id": "00000000/5c76ec5566332c"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Enable Passenger application

This function enables a Passenger application and generates the Apache configuration on an account.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=slippers

The Passenger application to enable on the account.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  enable_application \
  name='slippers'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_application",
"module": "PassengerApps",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Register Passenger application

This function registers a Passenger application for an account.

Important:

This function only registers an application. It does not create the application. You must create an application before you register the application. For an example of how to do this, read our How to Create Ruby Web Applications documentation.
When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

base_uri	string <url-path> Default: "/" Example: base_uri=/ruby The application’s base URI.
deployment_mode	string Default: "production" Possible Values: "production" "development" Example: deployment_mode=production The type of server environment in which to run the application. `development` — Sets the application to run in a development environment. `production` — Sets the application to run in a production environment.
domain required	string <domain> Example: domain=dorothy.com The domain for which to register the application.
enabled	integer Default: 1 Possible Values: 0 1 Example: enabled=1 Whether to enable the application and generate the web server configuration for it. `1` — Enable the application and generate the web server configuration. `0` — Don’t enable the application and generate the web server configuration.
envvar_name	Array of strings <= 256 characters Example: envvar_name=SHOES&envvar_name=TINMAN Environment variables that the application needs. Note: For each `envvar_name` parameter you send, you must include an `envvar_value` parameter. This parameter's value can only contain letters, numbers, underscores, and dashes, and cannot begin with a number. This parameter's value must also not exceed 256 characters.
envvar_value	Array of strings <= 1024 characters Example: envvar_value=ruby&envvar_value=heart Each environment variable’s value. Note: For each `envvar_name` parameter you send, you must include an `envvar_value` parameter. An environment variable value must contain 1024 or fewer ASCII-printable characters.
name required	string [ 1 .. 50 ] characters Example: name=Name of Application The application’s name.
path required	string <path> Example: path=/slippers The application’s filepath relative to the user’s home directory.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  register_application \
  name='Name of Application' \
  path='/slippers' \
  domain='dorothy.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "register_application",
"module": "PassengerApps",
"result": {"data": {"Name of Application": {"base_uri": "/ruby",
"deployment_mode": "production",
"domain": "dorothy.com",
"enabled": 1,
"envvars": {"SHOES": "ruby",
"TINMAN": "heart"
},
"name": "Name of Application",
"path": "/home/dorothy/slippers"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Unregister Passenger application

This function unregisters a Passenger application on an account.

Note:

This function only unregisters an application. It does not delete the application. You must manually delete the application from your system.
When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

name

required

string

Example: name=slippers

The application to unregister.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  unregister_application \
  name='slippers'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "unregister_application",
"module": "PassengerApps",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return Passenger applications

This function lists an account’s Passenger applications.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  PassengerApps \
  list_applications

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_applications",
"module": "PassengerApps",
"result": {"data": {"Name of Application 1": {"base_uri": "/app1-uri",
"deployment_mode": "production",
"deps": {"gem": "0",
"npm": "0",
"pip": "cd /home/user/app1-dir && pip install --user -r requirements.txt"
},
"domain": "example.com",
"enabled": 1,
"envvars": { },
"name": "Name of Application 1",
"path": "/home/user/app1-dir"
},
"Name of Application 2": {"base_uri": "/app2-uri",
"deployment_mode": "development",
"deps": {"gem": "cd /home/user/app2-dir && BUNDLE_PATH=~/.gem /path/to/ruby/version/package/bundler install",
"npm": "0",
"pip": "0"
},
"domain": "example.com",
"enabled": 1,
"envvars": { },
"name": "Name of Application 2",
"path": "/home/user/app2-dir"
}
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

ModSecurity

The ModSecurity module for UAPI.

Enable ModSecurity for selected domains

This function enables ModSecurity™ for specified domains.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Example: domains=example.com,dallas.example.com,galveston.example.com

A comma-separated list of domains for which to enable ModSecurity.

Important:

The authenticated cPanel account must own these domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ModSecurity \
  enable_domains \
  domains='example.com,dallas.example.com,galveston.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_domains",
"module": "ModSecurity",
"result": {"data": [{"dependencies": ["dallas.com"
],
"domain": "dallas.example.com",
"enabled": 1,
"searchhint": "dallas.com",
"type": "sub"
},
{"dependencies": ["arkansas.com",
"kansas.com",
"nevada.com",
"newmexico.com",
"texas.com"
],
"domain": "example.com",
"enabled": 1,
"searchhint": "arkansas.com,kansas.com,nevada.com,newmexico.com,texas.com",
"type": "main"
},
{"dependencies": ["galveston.com"
],
"domain": "galveston.example.com",
"enabled": 1,
"searchhint": "galveston.com",
"type": "sub"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Enable ModSecurity for all domains

This function enables ModSecurity™ on a cPanel account's domains.

Important:

When you disable the WebServer role, the system disables this function

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ModSecurity \
  enable_all_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_all_domains",
"module": "ModSecurity",
"result": {"data": [{"dependencies": ["dallas.com"
],
"domain": "dallas.example.com",
"enabled": 1,
"searchhint": "dallas.com",
"type": "sub"
},
{"dependencies": ["arkansas.com",
"kansas.com",
"nevada.com",
"newmexico.com",
"texas.com"
],
"domain": "example.com",
"enabled": 1,
"searchhint": "arkansas.com,kansas.com,nevada.com,newmexico.com,texas.com",
"type": "main"
},
{"dependencies": ["galveston.com"
],
"domain": "galveston.example.com",
"enabled": 1,
"searchhint": "galveston.com",
"type": "sub"
},
{"dependencies": ["houston.com"
],
"domain": "houston.example.com",
"enabled": 1,
"searchhint": "houston.com",
"type": "sub"
},
{"dependencies": ["neworleans.com"
],
"domain": "neworleans.example.com",
"enabled": 1,
"searchhint": "neworleans.com",
"type": "sub"
},
{"dependencies": ["sanantonio.com"
],
"domain": "sanantonio.example.com",
"enabled": 1,
"searchhint": "sanantonio.com",
"type": "sub"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Disable ModSecurity for selected domains

This function disables ModSecurity™ on specified domains.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domains

required

string

Example: domains=example.com,dallas.example.com,galveston.example.com

A comma-separated list of domains that the cPanel account owns.

Important:

The authenticated cPanel account must own these domains.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ModSecurity \
  disable_domains \
  domains='example.com,dallas.example.com,galveston.example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_domains",
"module": "ModSecurity",
"result": {"data": [{"dependencies": ["dallas.com"
],
"domain": "dallas.example.com",
"enabled": 0,
"searchhint": "dallas.com",
"type": "sub"
},
{"dependencies": ["arkansas.com",
"kansas.com",
"nevada.com",
"newmexico.com",
"texas.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "arkansas.com,kansas.com,nevada.com,newmexico.com,texas.com",
"type": "main"
},
{"dependencies": ["galveston.com"
],
"domain": "galveston.example.com",
"enabled": 0,
"searchhint": "galveston.com",
"type": "sub"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return ModSecurity installation status

This function checks whether ModSecurity™ is installed on a server.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ModSecurity \
  has_modsecurity_installed

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "has_modsecurity_installed",
"module": "ModSecurity",
"result": {"data": {"installed": 1
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return ModSecurity domains' status

This function returns ModSecurity's™ status for a cPanel account's domains.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ModSecurity \
  list_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_domains",
"module": "ModSecurity",
"result": {"data": [{"dependencies": ["dallas.com"
],
"domain": "dallas.example.com",
"enabled": 1,
"searchhint": "dallas.com",
"type": "sub"
},
{"dependencies": ["arkansas.com",
"kansas.com",
"nevada.com",
"newmexico.com",
"texas.com"
],
"domain": "example.com",
"enabled": 1,
"searchhint": "arkansas.com,kansas.com,nevada.com,newmexico.com,texas.com",
"type": "main"
},
{"dependencies": ["galveston.com"
],
"domain": "galveston.example.com",
"enabled": 1,
"searchhint": "galveston.com",
"type": "sub"
},
{"dependencies": ["houston.com"
],
"domain": "houston.example.com",
"enabled": 0,
"searchhint": "houston.com",
"type": "sub"
},
{"dependencies": ["neworleans.com"
],
"domain": "neworleans.example.com",
"enabled": 0,
"searchhint": "neworleans.com",
"type": "sub"
},
{"dependencies": ["sanantonio.com"
],
"domain": "sanantonio.example.com",
"enabled": 0,
"searchhint": "sanantonio.com",
"type": "sub"
}
],
"errors": null,
"messages": null,
"metadata": {"modsec": {"total_disabled": 3,
"total_enabled": 3
},
"transformed": 1
},
"status": 1,
"warnings": null
}
}

Disable ModSecurity for all domains

This function disables ModSecurity™ on a cPanel account's domains.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  ModSecurity \
  disable_all_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_all_domains",
"module": "ModSecurity",
"result": {"data": [{"dependencies": ["dallas.com"
],
"domain": "dallas.example.com",
"enabled": 0,
"searchhint": "dallas.com",
"type": "sub"
},
{"dependencies": ["arkansas.com",
"kansas.com",
"nevada.com",
"newmexico.com",
"texas.com"
],
"domain": "example.com",
"enabled": 0,
"searchhint": "arkansas.com,kansas.com,nevada.com,newmexico.com,texas.com",
"type": "main"
},
{"dependencies": ["galveston.com"
],
"domain": "galveston.example.com",
"enabled": 0,
"searchhint": "galveston.com",
"type": "sub"
},
{"dependencies": ["houston.com"
],
"domain": "houston.example.com",
"enabled": 0,
"searchhint": "houston.com",
"type": "sub"
},
{"dependencies": ["neworleans.com"
],
"domain": "neworleans.example.com",
"enabled": 0,
"searchhint": "neworleans.com",
"type": "sub"
},
{"dependencies": ["sanantonio.com"
],
"domain": "sanantonio.example.com",
"enabled": 0,
"searchhint": "sanantonio.com",
"type": "sub"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

NginxCaching

The NginxCaching module for UAPI.

Enable the user's NGINX cache

This function enables the user's NGINX cache.

Note:

You can only use this function if you installed the ea-nginx package.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  NginxCaching \
  enable_cache

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "enable_cache",
"module": "NginxCaching",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Delete NGINX cache contents.

This function clears the user's NGINX cache.

Note:

You can only use this function if you installed the ea-nginx package.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  NginxCaching \
  clear_cache

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "clear_cache",
"module": "NginxCaching",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Reset the user's NGINX cache configuration

This function resets the user's NGINX caching configuration.

Note:

You can only use this function if you installed the ea-nginx package.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  NginxCaching \
  reset_cache_config

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "reset_cache_config",
"module": "NginxCaching",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Disable the user's NGINX cache

This function disables the user's NGINX cache.

Note:

You can only use this function if you installed the ea-nginx package.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  NginxCaching \
  disable_cache

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "disable_cache",
"module": "NginxCaching",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

PHP Settings

Web Server Management / PHP Settings

Return PHP version's handler

This function returns a PHP version's assigned PHP handler.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the WebServer role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:

BasicAuth

query Parameters

type required	string Possible Values: "home" "vhost" Example: type=vhost The type of `php.ini` file. `home` `vhost` Important: If you set this parameter to `vhost`, you must also include the vhost parameter. If you set this parameter to `home`, the system returns the system default PHP handler.
vhost	string <domain> Example: vhost=clearly.com The name of a virtual host. Important: If the `type` value is `vhost`, you must use this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_get_domain_handler \
  type='vhost'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_get_domain_handler",
"module": "LangPHP",
"result": {"data": {"php_handler": "cgi"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return installed PHP versions

This function lists the system's PHP versions.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_get_installed_versions

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_get_installed_versions",
"module": "LangPHP",
"result": {"data": {"versions": ["ea-php72"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return domains that shared PHP configuration

This function lists domains that obtain their PHP version from a specified PHP configuration.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain

string <domain>

Example: domain=example.com

A domain on the system.

Note:

You must pass either the system_default or domain parameters, or both.
You can pass this parameter multiple times.
You cannot pass the name of a parked domain.

system_default

integer

Possible Values: 1 0

Example: system_default=1

Whether to return domains that inherit the system's default PHP version.

1 - Return domains that inherit the system's default PHP version.
0 - Do not return domains that inherit the system's default PHP version.

Note:

If you pass this parameter with a false value and do not also pass the domain parameter, the function returns an error.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_get_impacted_domains

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_get_impacted_domains",
"module": "LangPHP",
"result": {"data": {"domains": ["example.com"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return basic PHP directives

This function lists a virtual host's basic PHP directives. The Basic Mode section of cPanel's MultiPHP INI Editor interface (Home >> Software >> MultiPHP INI Editor) also lists these directives.

Note:

This document only applies to systems that run EasyApache 4 with MultiPHP enabled.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

type required	string Possible Values: "home" "vhost" Example: type=vhost The type of `php.ini` file. `home` `vhost` Important: If you set this parameter to `vhost`, you must also include the `vhost` parameter.
vhost	string <domain> Example: vhost=clearly.com The name of a virtual host. Important: If the type value is `vhost`, you must use this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_ini_get_user_basic_directives \
  type='vhost'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_ini_get_user_basic_directives",
"module": "LangPHP",
"result": {"data": {"directives": [{"default_value": 1,
"info": "This option enables the URL-aware fopen wrappers that enable accessing URL object like files. Default wrappers are provided for the access of remote files using the ftp or http protocol, some extensions like zlib may register additional wrappers.",
"key": "allow_url_fopen",
"php_ini_mode": "PHP_INI_SYSTEM",
"type": "integer",
"value": "On"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return default PHP version

This function lists the system’s default PHP version.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_get_system_default_version

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_get_system_default_version",
"module": "LangPHP",
"result": {"data": {"version": "ea-php73"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return virtual host's php.ini content

This function returns the contents of a virtual host's php.ini file.

Note:

This document only applies to systems that run EasyApache 4 with MultiPHP enabled.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

type required	string Example: type=vhost The type of `php.ini` file. `home` `vhost` Important: If you set this parameter to `vhost`, you must also include the `vhost` parameter.
vhost	string <domain> Example: vhost=clearly.com The name of a virtual host. Important: If the type value is `vhost`, you must use this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_ini_get_user_content \
  type='vhost'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_ini_get_user_content",
"module": "LangPHP",
"result": {"data": {"content": "allow_url_fopen = On\\nallow_url_include = On\\nasp_tags = Off\\ndisplay_errors = On\\nenable_dl = Off\\nfile_uploads = On\\ninclude_path = &quot;.;/path/to/php/pear&quot;\\nmax_execution_time = 30\\nmax_input_time = 60\\nmax_input_vars = 1050\\nmemory_limit = 32M\\nupload_max_filesize = 2M"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return php.ini file paths

This function lists the php.ini file paths for the user's home directory and virtual host document roots.

Note:

This document only applies to systems that run EasyApache 4 with MultiPHP enabled.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_ini_get_user_paths

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_ini_get_user_paths",
"module": "LangPHP",
"result": {"data": {"paths": [{"account": "allthethings",
"documentroot": "/home/allthethings/public_html",
"homedir": "/home/allthethings/",
"main_domain": 1,
"path": "php.ini",
"type": "vhost",
"version": "ea-php72",
"vhost": "clearly.com"
}
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update basic PHP directives

This function sets the values of any basic PHP directive. The Basic Mode section of cPanel's MultiPHP INI Editor interface (WHM >> Home >> Software >> MultiPHP INI Editor) lists these directives.

Note:

This document only applies to systems that run EasyApache 4 with MultiPHP enabled.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

directive required	string Examples: directive=directive-1=allow_url_fopen%3A0&directive-2=upload_max_filesize%3A4M&directive-3=post_max_size - Multiple PHP directives. directive=allow_url_fopen:0 - A single PHP directive. The name of a PHP directive and its value. Note: To change the directive's value for multiple PHP directives, increment the parameter name. For example, the `directive-1`, `directive-2`, and `directive-3` parameters. You must format values as `<directive>:<value>`
type required	string Possible Values: "home" "vhost" Example: type=vhost The type of `php.ini` file. `home` `vhost` Important: If you set this parameter to `vhost`, you must also include the `vhost` parameter.
vhost	string <domain> Example: vhost=clearly.com The name of a virtual host. Important: If the `type` value is `vhost`, you must use this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_ini_set_user_basic_directives \
  type='vhost' \
  directive='allow_url_fopen:0'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_ini_set_user_basic_directives",
"module": "LangPHP",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"LangPHP": {"path": "/home/allthethings/public_html/php.ini",
"phpversion": "ea-php55",
"type": "vhost",
"vhost": "clearly.com"
}
},
"status": 1,
"warnings": null
}
}

Update virtual host's PHP version

This function sets a virtual host's PHP version.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

version required	string Example: version=ea-php72 The PHP version of a virtual host.
vhost required	string <domain> Examples: vhost=vhost-1=example.com&vhost-2=example2.com&vhost-3=example3.com - Set a multiple vhosts. vhost=example.com - Set a single vhost. The virtual host's name. Note: To change the PHP version of multiple virtual hosts, duplicate or increment the parameter name. For example, `vhost-1`, `vhost-2`, and `vhost-3`.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_set_vhost_versions \
  version='ea-php72' \
  vhost='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_set_vhost_versions",
"module": "LangPHP",
"result": {"data": {"vhosts": ["example.com"
]
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Update virtual host's php.ini content

This function changes the contents of a virtual host's php.ini file.

Note:

This document only applies to systems that run EasyApache 4 with MultiPHP enabled.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

content required	string Example: content=%5BPHP%5D%0D%0A%3B+About+php.ini%0D%0A%3B+php.ini+is+responsible+for+configuring+many+of+the+aspects+of+PHP%27s+behavior.%0D%0Apcre.backtrack_limit%3D100000 The content of the `php.ini` file to change.
type required	string Possible Values: "host" "vhost" Example: type=vhost The type of `php.ini` file. `home` `vhost` Important: If you set this parameter to `vhost`, you must also include the `vhost` parameter.
vhost	string <domain> Example: vhost=clearly.com The name of a virtual host. Important: If the type value is `vhost` , you must use this parameter.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_ini_set_user_content \
  type='vhost' \
  content='%5BPHP%5D%0D%0A%3B+About+php.ini%0D%0A%3B+php.ini+is+responsible+for+configuring+many+of+the+aspects+of+PHP%27s+behavior.%0D%0Apcre.backtrack_limit%3D100000'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_ini_set_user_content",
"module": "LangPHP",
"result": {"data": { },
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return virtual host's PHP version

This function returns the PHP version of every virtual host that a reseller controls.

You can get the version of a single virtual host by providing an optional vhost name.

Note:

This document only applies to systems that run EasyApache 4.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

vhost

string

Example: vhost=your-domain.test

The PHP Virtual Hostname.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LangPHP \
  php_get_vhost_versions

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "php_get_vhost_versions",
"module": "LangPHP",
"result": {"data": [{"account": "blee",
"account_owner": "blee",
"documentroot": "/home/blee/public_html",
"homedir": "/home/blee",
"main_domain": 1,
"php_fpm": 1,
"php_fpm_pool_parms": {"pm_max_children": 5,
"pm_max_requests": 20,
"pm_process_idle_timeout": 10
},
"phpversion_source": [{"domain": "blee.com",
"system_default": 1
}
],
"version": "ea-php72",
"vhost": "blee.com"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Handler Management

Website Configuration / Handler Management

Add web server MIME type handler

This function creates an Apache MIME type handler for a file extension.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

extension required	string Example: extension=.foo The file extension.
handler required	string Example: handler=txt-foo The Apache MIME handler.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  add_handler \
  extension='.foo' \
  handler='txt-foo'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_handler",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove web server MIME type handler

This function deletes an Apache MIME type handler.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

extension

required

string

Example: extension=.foo

The file extension.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  delete_handler \
  extension='.foo'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_handler",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Return web server's MIME handlers

This function lists all of Apache's MIME handlers.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

type

required

string

Possible Values: "system" "user"

Example: type=user

Whether to retrieve system or user handlers.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  list_handlers \
  type='user'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_handlers",
"module": "Mime",
"result": {"data": [{"extension": ".foo",
"handler": "text-foo",
"origin": "user"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return redirect information

This function retrieves redirect information for a URL or ** All Public Domains **.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

domain required	string <domain> Example: domain=example.com The domain for which to retrieve redirector information.
url required	string <url> Example: url=http://redirect.example.com The URL for which to retrieve redirector information.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  redirect_info \
  url='http://redirect.example.com' \
  domain='example.com'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "redirect_info",
"module": "Mime",
"result": {"data": {"domain": "example.com",
"url": "http://redirect.example.com"
},
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Logs

Website Configuration / Logs

Retrieve cPanel account's log archival settings

This function retrieves the account's log archival settings.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LogManager \
  get_settings

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "get_settings",
"module": "LogManager",
"result": {"data": {"archive_logs": 1,
"prune_archive": 1
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return cPanel account's archive files list

This function returns a list of the user's archive files.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LogManager \
  list_archives

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_archives",
"module": "LogManager",
"result": {"data": [{"file": "domain.com-May-2019.gz",
"mtime": 1557835866,
"path": "/home/user/logs/domain.com-May-2019.gz"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Save cPanel account's log archive settings

This function saves the account's log archive settings.

Note:

You must pass either the archive_logs or the prune_archives parameter.

Authorizations:

BasicAuth

query Parameters

archive_logs

integer

Possible Values: 0 1

Example: archive_logs=1

Whether to archive log files to your home directory after the system processes statistics.

1 — Archive the logs.
0 — Do not archive the logs.

Note:

This parameter defaults to the archive-logs setting's value in the user's ~/.cpanel-logs file.
If this file does not exist, this parameter defaults to the default_archive-logs key's value in the cpanel.config file.

prune_archive

integer

Possible Values: 0 1

Example: prune_archive=1

Whether to remove the previous month's archived logs from the ~/logs directory at the end of each month.

1 — Remove the logs.
0 — Do not remove the logs.

Note:

This parameter defaults to the remove-old-archived-logs setting's value in the user's ~/.cpanel-logs file.
If this file doesn't exist, this parameter defaults to the default_remove-old-archive-logs key's value in the cpanel.config file.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  LogManager \
  set_settings

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "set_settings",
"module": "LogManager",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Mime Type Management

Website Configuration / Mime Type Management

Add MIME type to web server

This function adds a MIME type to Apache.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

extension required	string Example: extension=.foo The file extension.
type required	string <MIME> Example: type=text/foo The MIME type.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  add_mime \
  type='text/foo' \
  extension='.foo'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "add_mime",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Remove MIME type from web server

This function removes a MIME type from Apache.

Important:

When you disable the WebServer role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

type

required

string

Example: type=text/foo

The MIME type.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  delete_mime \
  type='text/foo'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "delete_mime",
"module": "Mime",
"result": {"data": null,
"errors": null,
"messages": null,
"status": 1,
"warnings": null
}
}

Return web server's MIME types

This function lists all of Apache's MIME types.

Note:

This function does not list PHP versions with MIME types when the user or domain enables PHP-FPM. The system displays only custom MIME types.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

type

required

string

Possible Values: "system" "user"

Example: type=user

The MIME types to list.

system — List the Apache system MIME types.
user — List the Apache user MIME types.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Mime \
  list_mime \
  type='user'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_mime",
"module": "Mime",
"result": {"data": [{"extension": ".foo",
"origin": "user",
"type": "application/foo"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Site Information

Website Configuration / Site Information

Return WordPress site information

This function retrieves the installation status and detailed information of the WordPress site for cPanel user's primary domain.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressSite \
  retrieve

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "retrieve",
"module": "WordPressSite",
"result": {"data": [{"details": null,
"install_status": "in progress"
}
],
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Site Installation

Website Configuration / Site Installation

Install WordPress site

This function installs a WordPress site for cPanel user's primary domain.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  WordPressSite \
  create

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "create",
"module": "WordPressSite",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": { },
"status": 1,
"warnings": null
}
}

Site Publisher Management

Website Configuration / Site Publisher Management

Return Site Publisher websites' information

This function lists information for the cPanel account's Site Publisher websites.

Note:

To retrieve the list of Site Publisher website information, the function queries the configurations.json file in each domain's document root. For more information, read our Guide to Site Publisher Templates documentation.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SiteTemplates \
  list_user_settings

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_user_settings",
"module": "SiteTemplates",
"result": {"data": [{"documentroot": "/home/example/public_html",
"domain": "example.com",
"homedir": "/home/example",
"serveralias": ["www.example.com"
],
"template_settings": {"is_empty": 0,
"path": "/usr/local/cpanel/3rdparty/share/site_templates/",
"template": "mytemplate"
},
"type": "main"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Return available Site Publisher templates

This function lists available templates for cPanel's Site Publisher feature.

If you call this function as the root or system user, the function lists the root user's templates.
If you call this function as a reseller, the function lists the root user's templates and the reseller's templates.
If you call this function as a cPanel user, the function's output depends on the account's owner:
- If the root user owns the account, the function only lists the root user's templates.
- If a reseller owns the account, the function lists the root user's templates and that reseller's templates.

Note:

The template directory's location depends on whether the root user or a reseller owns the template:

/var/cpanel/customizations/site_templates/ — The root user's templates.
/home/username/var/cpanel/reseller/site_templates/ — A reseller's templates, where username represents the reseller's username.
/usr/local/cpanel/3rdparty/share/site_templates/ — cPanel-provided templates.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SiteTemplates \
  list_site_templates

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "list_site_templates",
"module": "SiteTemplates",
"result": {"data": [{"meta": {"fields": [{"id": "fullName",
"label": "Full Name",
"placeholder": "Your Name",
"type": "text"
}
],
"information": {"date": "2020-06-30",
"description": "Single page 'About Me' site",
"id": "about_me",
"name": "About Me",
"preview_image_path": "/preview.png"
}
},
"path": "/usr/local/cpanel/3rdparty/share/site_templates",
"preview": 1,
"template": "about_me"
}
],
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}

Add Site Publisher website

This function publishes a Site Publisher website.

This function uses the /scripts/process_site_template script to publish the Site Publisher website.
This function creates the configurations.json file in the specified directory.
- This file contains the user-entered data for the Site Publisher website and uses 0700 permissions.
- For more information, read our Guide to Site Publisher Templates documentation.
When users publish a Site Publisher website, the system first creates a backup tarball of the target directory's contents in the /site_publisher/backups/ directory within the user's home directory.

Notes:

When users publish a Site Publisher website, the system logs template information and the target directory to the /usr/local/cpanel/logs/error_log file.
The template directory's location depends on whether the root user or a reseller owns the template:
- /var/cpanel/customizations/site_templates/ — The root user's templates.
- /home/username/var/cpanel/reseller/site_templates/ — A reseller's templates, where username represents the reseller's username.
- /usr/local/cpanel/3rdparty/share/site_templates/ — cPanel-provided templates.

Important:

When you disable the Web Server role, the system disables this function.

Authorizations:

BasicAuth

query Parameters

parameter_name	string Example: parameter_name=My Website The template's variables and values. Note: Use each variable's name as a parameter name for a parameter and value pair. The template that you specify determines the values to define. You must include the appropriate data for the selected template. If you use a cPanel-provided template, read our Guide to Site Publisher Templates documentation for more information. If you use a third-party template, consult that template's documentation or its `meta.json` file.
path	string <path> Example: path=/usr/local/cpanel/3rdparty/share/site_templates/ The directory that contains the template's source directory. `/var/cpanel/customizations/site_templates/` — The `root` user's templates. `/home/username/var/cpanel/reseller/site_templates/` — A reseller's templates, where `username` represents the reseller's username. `/usr/local/cpanel/3rdparty/share/site_templates/` — cPanel-provided templates. Note: You must include either the `source` parameter or the `path` and `template` parameters.
source	string <path> Example: source=/usr/local/cpanel/3rdparty/share/site_templates/under_construction The absolute path to a template directory that exists in one of the following directories: `/var/cpanel/customizations/site_templates/` — The `root` user's templates. `/home/username/var/cpanel/reseller/site_templates/` — A reseller's templates, where `username` represents the reseller's username. `/usr/local/cpanel/3rdparty/share/site_templates/` — cPanel-provided templates. If you do not specify a value, the system uses the path and template values to determine the template's source directory. Note: You must include either the `source` parameter or the `path` and `template` parameters.
target or docroot required	string <path> Example: target or docroot=/home/example/public_html The directory that will contain the Site Publisher website.
template	string Example: template=under_construction The template's directory's name. Note: You must include either the `source` parameter or the `path` and `template` parameters.

Responses

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  SiteTemplates \
  publish \
  target  or  docroot='/home/example/public_html'

Response samples

200

Content type

application/json

{"apiversion": 3,
"func": "publish",
"module": "SiteTemplates",
"result": {"data": null,
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}