96 functions, invoked through the cpanel_uapi tool.
scope cpanel:uapi
Call any function with cpanel_uapi(service_id, module="Email", function, params). Live availability depends on the cPanel features JetHost has enabled on your account — call list_cpanel_operations to see what is active.
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.
accountstringOptional
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.
displaystringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The account parameter's value. A valid string. All Mail On The Account * An empty value.
This function creates an autoresponder for an email account.
Important:
When you disable the Receive Mail role, the system disables this function.
bodystringRequired
The contents of the autoresponder message's Body section.
domainstringRequired
The email account's domain. For example, example.com if the email address is user@example.com.
emailstringRequired
The email account name. For example, user if the email address is user@example.com.
fromstringRequired
The contents of the autoresponder message's From: field.
intervalintegerRequired
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_htmlintegerRequired
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.
startintegerRequired
When to enable the autoresponder.
stopintegerRequired
When to disable the autoresponder. A time that is after the start time.
subjectstringRequired
The contents of the autoresponder message's Subject: field.
When you disable the MailReceive role, the system disables this function. For more information, read our How to Use Server Profiles documentation.
domainstringRequired
The domain.
emailstringRequired
The email address to forward.
fwdoptstringRequired
The method to use to handle the email address's mail.
failmsgsstringOptional
The failure message for the message's sender. Note: Use this parameter if you used the fail method for the fwdopt parameter.
fwdemailstringOptional
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.
fwdsystemstringOptional
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.
pipefwdstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
domainstring
The domain. A valid domain on the account.
emailstring
The email address. An email address on the account.
forwardstring
The method that the system will use to handle the address's mail. - An email address The system forwards mail to this address. - :fail: The system bounces mail back to the sender and sends a failure message. - :blackhole: The system deletes mail without a failure message. - The path to an application The system pipes mail to this application. - A username The system forwards mail to this system account.
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
domainstringRequired
The new mail exchanger's domain.
exchangerstringRequired
The new mail exchanger's name.
priorityintegerRequired
The new mail exchanger's priority value. Note: It is common practice to set a priority value that is divisible by five.
alwaysacceptintegerOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
checkmxobject
An object of the mail exchanger's data.
changedinteger
Whether a change occurred during the function. 1 - Change occurred. 0 - No change.
One of: 01
detectedstring
The mail exchanger type. autolocalsecondaryremote
One of: autolocalsecondaryremote
isprimaryinteger
Whether the mail exchanger is the primary mail exchanger. 1 - Primary. 0 - Not primary.
One of: 01
issecondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 - Secondary. 0 - Not secondary.
One of: 01
localinteger
Whether the mail exchanger is a local exchanger. 1 - Local. 0 - Not local.
One of: 01
mxcheckstring
The mail exchanger type. autolocalsecondaryremote
One of: autolocalsecondaryremote
remoteinteger
Whether the mail exchanger is a remote exchanger. 1 - Remote. 0 - Not remote.
One of: 01
secondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 - Secondary. 0 - Not secondary.
One of: 01
warningsarray<string>
Warning messages, if any exist.
resultsstring
A message of success, or an error message. A message of success that begins with Added entry:. An error message.
statusinteger
Whether the function succeeded. 1 - Success. 0 - Failure.
One of: 01
statusmsgstring
A message of success, or an error message. A message of success that begins with Added entry:. An error message.
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.
emailmixedRequired
The email account username or address. A valid email account username. For example, user to create user@example.com. A valid email address. Note: You cannot enter cpanel as an account name when you create an email account.
passwordstringRequired
The email account password.
domainstringOptional
The email account's domain. For example, example.com to create user@example.com.
password_hashstringOptional
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.
quotamixedOptional
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_emailintegerOptional
Whether to send client configuration instructions to the account. 1 — Send the instructions. 0 — Do not send the instructions.
skip_update_dbintegerOptional
Whether to skip the update of the email accounts database's cache. 1 — Skip the update. 0 — Perform the update.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The email address. The email account username, a plus character (+), and the email account domain.
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.
accountstringOptional
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_scorestringOptional
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).
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
accountstringOptional
An email address, to limit the function's results.
dirstringOptional
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.
showdotfilesintegerOptional
Whether to include hidden files and directories. 1 — Include hidden items. 0 — Do not include hidden items.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
depthinteger
The directory depth of the item's path.
filestring
The item's base name.
fullpathstring
The item's absolute path.
isleafinteger
Whether the item is a file or a directory. 1 - File. 0 - Directory.
One of: 01
ismailboxinteger
Whether the item is a mailbox. 1 - Mailbox. 0 - Not a mailbox.
One of: 01
mtimeinteger
The item's modification time. A time, in Unix time format.
pathstring
The item's directory's path.
relpathstring
The item's relative path.
typestring
The item type. dir - The item is a directory. file - The item is a file.
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.
domainstringRequired
The mail exchanger's domain.
exchangerstringRequired
The mail exchanger's name.
oldexchangerstringRequired
The mail exchanger's current name.
priorityintegerRequired
The mail exchanger's new priority value. Note: Common practice sets a priority value divisible by five.
alwaysacceptintegerOptional
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.
oldpriorityintegerOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
checkmxobject
An object of the mail exchanger's data.
changedinteger
Whether a change occurred during the function. 1 - Change occurred. 0 - No change.
One of: 01
detectedstring
The mail exchanger type. autolocalsecondaryremote
One of: autolocalsecondaryremote
isprimaryinteger
Whether the mail exchanger is the primary mail exchanger. 1 - Primary. 0 - Not primary.
One of: 01
issecondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 - Secondary. 0 - Not secondary.
One of: 01
localinteger
Whether the mail exchanger is a local exchanger. 1 - Local. 0 - Not local.
One of: 01
mxcheckstring
The mail exchanger type. autolocalsecondaryremote
One of: autolocalsecondaryremote
remoteinteger
Whether the mail exchanger is a remote exchanger. 1 - Remote. 0 - Not remote.
One of: 01
secondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 - Secondary. 0 - Not secondary.
One of: 01
warningsarray<string>
Warning messages, if any exist.
resultsstring
A message of success, or an error message. A message of success that begins with Added entry:. An error message.
statusinteger
Whether the function succeeded. 1 - Success. 0 - Failure.
One of: 01
statusmsgstring
A message of success, or an error message. A message of success that begins with Added entry:. An error message.
When you disable the Receive Mail role, the system disables this function.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The contents of the server's /var/cpanel/fastmail file. A positive value that represents a BlackBerry FastMail version number if it is enabled on the server. A null value if BlackBerry FastMail is not enabled on the server.
When you disable the Receive Mail role, the system disables this function.
emailmixedRequired
The email account username or address. A valid email account username. For example, user if the email address is user@example.com. A valid email address.
domainstringOptional
The email account's domain. For example, example.com if the email address is user@example.com.
flagsstringOptional
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_quotaintegerOptional
Whether to modify the mail account's quota file. 1 — Do not modify. 0 — Modify.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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 user+newmailbox@example.com address creates the newmailbox mailbox if the newmailbox mailbox does not exist.
emailstringRequired
The email account address for which to disable mailbox autocreation.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
Whether the function disabled mailbox autocreation for the cPanel account. 1 - Mailbox autocreation disabled. 0 - Mailbox autocreation is not disabled.
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.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The email account's domain. Defaults to the cPanel account's main domain.
emailstringRequired
The email account username.
quotastringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
emailstringRequired
The email account for which to enable mailbox autocreation.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
Whether the function enabled mailbox autocreation for the cPanel account. - 1 Mailbox autocreation enabled. - 0 Mailbox autocreation is not enabled.
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.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
accountstringRequired
The email user's account name. Note: If you do not enter an email address, the function rescans the default email account.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
Whether the system started the rescan. 1 - Success. 0 - Failure.
The contents of the autoresponder message's From field.
intervalinteger
The amount of time, in hours, that the server waits between autoresponder messages to the same address. Note: A value of 0 indicates that the system sends a message for each email received.
is_htmlinteger
Whether the body of the autoresponder message begins with an HTML content type declaration. - 1 - Includes an HTML content type declaration. - 0 - Does not include an HTML content type declaration.
One of: 01
startinteger
When the autoresponder becomes enabled in Unix time.
stopinteger
When the autoresponder becomes disabled in Unix time.
subjectstring
The contents of the autoresponder message's Subject field.
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.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The default email quota in bytes. The value will either be: The system's default quota value (32 gigabytes). The account's quota value, if it is less than the system's default value.
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.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The default email quota in mebibytes (MiB). The value will either be: The system's default quota value (32 gigabytes). The account's quota value, if it is less than the system's default value.
This function retrieves the disk space that an email account uses.
Important:
When you disable the Receive Mail role, the system disables this function.
domainstringRequired
The email account's domain.
userstringRequired
The email account username.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
diskusednumber
The disk space that the email account uses. A positive floating-point value that represents the disk space, used in megabytes (MB). 0 - The account posesses an unlimited disk quota.
This function retrieves an email filter's information.
Important:
When you disable the Receive Mail role, the system disables this function.
accountstringRequired
The email address that owns the filter.
filternamestringRequired
The filter's name.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
actionsarray<object>
An array of objects that contains the filter's actions.
actionstring
The filter's action. deliver - The filter sends mail to the destination address. fail - The filter forces a delivery failure. finish - The filter stops message processing. save - The filter saves mail to the destination file. * pipe - The filter sends mail to the destination application.
One of: deliverfailfinishsavepipe
destany
The destination to which the filter sends mail. A destination can be one of the following. A file path. An application path. * A valid email address.
numberinteger
The filter's position in the order of the account's filters.
filternamestring
The filter's name.
metadataobject
transformedinteger
Post-processing may have transformed the data.
One of: 1
rulesarray<object>
An array of objects that contains the filter's rules.
matchstring
The filter's match type. ismatchescontainsdoes not containbeginsdoes not beginendsdoes not enddoes not matchis aboveis not aboveis below * is not below
One of: ismatchescontainsdoes not containbeginsdoes not beginendsdoes not enddoes not matchis aboveis not aboveis below
numberinteger
The filter's position in the order of the account's filters.
optstring
The connection between multiple conditions. and - Match both conditions. or - Match either condition. * null - There is only one condition.
One of: andornull
partstring
The queried email section. $header_from: - Matches against the From: section. $header_subject: - Matches against the Subject: section. $header_to: - Matches against the To: section. $reply_address: - Matches against the Reply To: section. $message_body - Matches against the message's body. $message_headers - Matches against the message's headers. foranyaddress $h_to:,$h_cc:,$h_bcc: - Matches against all message recipients. not delivered - Matches if the message is not queued for delivery. * error_message - Matches if the incoming message bounced.
One of: $header_from:$header_subject:$header_to:$reply_address:$message_body$message_headersforanyaddress $h_to:,$h_cc:,$h_bcc:not deliverederror_message
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.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The account's maximum email quota, in bytes format. The function will return one of the following values: The system's default maximum quota (4 Pebibytes). The account's quota value, if it is less than the default system quota value.
This function retrieves the Apache SpamAssassin™ settings for the account.
Important:
When you disable the SpamFilter role, the system disables this function.
accountstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
cpuser_spam_auto_deleteinteger
The cPanel user's account-wide spam filter setting 1 - Enabled. 0 - Not enabled. NOTE: This key only appears if the account parameter is passed and the account does not have a custom setting
One of: 01
cpuser_spam_auto_delete_scoreinteger
The cPanel user's account-wide spam filter threshold score. For more information, see Email::add_spam_filter. NOTE: This key only appears if the account parameter is passed and the account does not have a custom setting
rewrites_subjectsinteger
Whether the user's spam filter rewrites the subject lines of spam messages. 1 - Rewrite. 0 - No rewrites.
One of: 01
spam_as_aclinteger
Whether the user's spam filter uses Apache SpamAssassin as an ACL. NOTE: The value of this parameter is always1 * 1 - SpamAssassin is an ACL.
One of: 1
spam_auto_deleteinteger
Whether the user's autodelete function is enabled. 1 - Enabled. 0 - Not enabled. NOTE:: This key does not appear if the cpuser_spam_auto_delete key appears
One of: 01
spam_auto_delete_scoreinteger
Displays the user's spam filter threshold. For more information, see Email::add_spam_filter. Note: This key does not appear if the cpuser_spam_auto_delete_score key appears
spam_box_enabledinteger
Whether the user's spam box is enabled. 1 - Enabled. 0 - Not enabled.
One of: 01
spam_enabledinteger
Whether the server's global spam filtering is enabled. 1 - Enabled. 0 - Not enabled. Note: This value will only return 0 if the cPanel user disables Apache SpamAssassin.
One of: 01
spam_status_changeableinteger
Whether the server allows cPanel users to configure Apache SpamAssassin settings. 1 - Allowed. 0 - Not allowed.
This function checks an account's administrative privileges on mailing lists.
Important:
When you disable the Receive Mail role, the system disables this function.
delegatestringRequired
The email address.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
Whether the email address has administrative privileges on one or more mailing lists on the cPanel account. 1 — The email address has administrative privileges. 0 — The email address does not have administrative privileges.
This function retrieves a domain's default address.
Important:
When you disable the Receive Mail role, the system disables this function.
userstringRequired
The user whose default addresses to list.
domainstringOptional
The domain. If you do not specify a value, the function lists default addresses for all of the cPanel account's domains.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
defaultaddressstring
The domain's default address. An email account username - The system forwards unroutable mail to this address. :fail: - The system bounces unroutable mail back to the sender, and sends a failure message. :blackhole: - The system deletes unroutable mail without a failure message. The path to an application - The system pipes unroutable mail to this application.
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.
accountmixedOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
actionsarray<object>
An array of objects that descibe each of the filter’s actions.
actionstring
The filter’s action. Some common ones include: deliver — The filter sends mail to the dest address. fail — The filter forces a delivery failure. finish — The filter stops message processing. save — The filter saves mail to the dest file. * pipe — The filter sends mail to the dest application. For more information, read Exim’s _Filter commands_ documentation.
deststring
The destination to which the filter sends mail. A file path. An application path. * A valid email address.
enabledinteger
Whether the filter is enabled.
filternamestring
The filter’s name.
rulesarray<object>
An array of objects that descibe each of the filter’s rules.
matchstring
The filter’s match type.
One of: ismatchescontainsdoes not containbeginsdoes not beginendsdoes not enddoes not matchis aboveis not aboveis below
optstring
The connection between multiple conditions. and — Match both conditions. or — Match either condition. * null — Only one condition exists.
One of: andornull
partstring
The queried email section. Some common ones include: $header_from: — Matches against the From: section. $header_subject: — Matches against the Subject: section. $header_to: — Matches against the To: section. $reply_address: — Matches against the Reply To: section. $message_body — Matches against the message’s body. $message_headers — Matches against the message’s headers. foranyaddress $h_to:,$h_cc:,$h_bcc: — Matches against all message recipients. not delivered — Matches if the system has not queued the message for delivery. * error_message — Matches if the incoming message bounced. For more options, read Exim’s documentation.
When you disable the Receive Mail role, the system disables this function.
domainstringRequired
The domain.
regexstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
deststring
The forwarded address.
forwardstring
The forwarded mail's destination.
html_deststring
The forwarded address in an HTML-compatible format.
html_forwardstring
The forwarded mail's destination in an HTML-compatible format.
uri_deststring
The forwarded address in a URI-encoded format.
uri_forwardstring
The forwarded mail's destination in a URI-encoded format.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
accesstypestring
The level of access that users have to the mailing list. private - The list has all of the following settings: The list has private archives. The administrator must approve subscriptions. The Mailman directory page does not display the list. public - The list has any of the following settings: The list has public archives. Anyone can subscribe. The Mailman directory page displays the list.
One of: privatepublic
advertisedinteger
Whether the Mailman directory page displays the list. 1 - The Mailman directory page displays the list. 0 - The Mailman directory page does not display the list.
One of: 01
archive_privateinteger
Whether the mailing list archive is private. 1 - The mailing list archive is private. 0 - The mailing list archive is public.
One of: 01
desthostany
The IP address or domain name that handles mail for the mailing list's domain. A valid hostname. An IPv4 address. Note: If the function cannot resolve the IP address to a hostname, it will return the IP address.
diskusedinteger
The disk space that the mailing list currently uses, measured in megabytes (MB).
humandiskusedstring
The disk space that the mailing list uses, in human-readable format.
liststring
The mailing list name and domain.
listadminstring
The mailing list's administrators' email addresses. A comma-separated list of email addresses.
listidstring
The mailing list's name and domain. The mailing list name, an underscore (_), and the domain.
subscribe_policyinteger
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.
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.
add_wwwintegerOptional
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 onlyexample.com.
include_wildcardintegerOptional
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 onlyexample.com.
return_temporary_domainbooleanOptional
Whether to include temporary domains (*.cpanel.site) in the output. By default, temporary domains are excluded.
selectstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
domainstring
The domain name.
selectinteger
The domain that you specified in the select input parameter. The function only returns this value if you included the select parameter when you called the function. Note: Because this value only appears if you included the select input parameter, The value always defaults to 1.
When you disable the DNS role, the system disables this function.
domainstringOptional
The domain to query. If you do not use this parameter, the function returns MX records for all of the cPanel account's domains.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
alwaysacceptinteger
Whether the domain's highest-priority mail exchanger accepts local mail. 1 - Accept local mail. 0 - Does not accept local mail.
One of: 01
detectedstring
The domain's highest-priority mail exchanger's type. autolocalremotesecondary
One of: autolocalremotesecondary
domainstring
The domain name.
entriesarray<object>
An array of objects that contains information about mail exchangers.
domainstring
The mail exchanger's domain.
entrycountinteger
The mail exchanger's order in the list of priorities. For example, the mail exchanger with the highest priority returns 1, and the next highest priority returns 2.
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.
domainstringOptional
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.
emailstringOptional
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 user@example.com.
get_restrictionsintegerOptional
Whether to display restriction status for each of the email addresses. 1 — Display. 0 — Do not display.
infinityimgstringOptional
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.
infinitylangintegerOptional
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.
maxaccountsintegerOptional
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_diskintegerOptional
Whether to skip the collection of disk usage information. 1 — Do not collect. 0 — Collect.
no_validateintegerOptional
Whether to skip email database validation. 1 — Skip validation. 0 — Perform the validation.
regexstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
_diskquotainteger
The disk quota. A positive value that represents the disk quota, in bytes. 0 - The account possesses an unlimited disk quota.
_diskusedinteger
The disk space that the email account uses. A positive value that represents the used disk space, in bytes. 0 - The account possesses an unlimited disk quota.
diskquotaany
The email account's disk quota. A positive value that represents the email address's quota, in megabytes (MB). unlimited, ∞, or HTML code to display an infinity image - The email account has an unlimited quota. Note: The infinityimg and infinitylang parameters determine the unlimited value for this return.
diskusedinteger
The disk space that the email account uses. A positive floating-point value that represents the used disk space, in megabytes (MB). 0 - The account possesses an unlimited disk quota.
diskusedpercentinteger
The percentage of disk space that the email account uses. A positive value. 0 - The account has an unlimited disk quota.
diskusedpercent20integer
The percentage of disk space that the email account uses. A positive value. 0 - The account possesses an unlimited disk quota.
diskusedpercent_floatnumber
The floating-point value from which the function derives the diskusedpercent return. A floating-point value. 0 - Unlimited or disabled disk quota. Note: The diskusedpercent_float number can contain scientific notation values. For example, 1.20494365692139e-05.
domainstring
The email account's domain. For example, example.com if the email address is user@example.com.
emailany
The email address, or the string Main Account. A valid email address. Main Account
has_suspendedinteger
Whether the email account possesses one of the following suspension parameters: suspended_loginsuspended_incomingsuspended_outgoinghold_outgoing1 - The email account has a suspension. 0 - The email account does not have a suspension. Note: The function only returns this value if you pass the get_restrictions=1 parameter.
One of: 01
hold_outgoinginteger
Whether the email account's outgoing email is held in Exim's queue. 1 - Outgoing email is held in Exim's queue. 0 - Outgoing email is not held in Exim's queue. Note: The function only returns this value if you pass the get_restrictions=1 parameter.
One of: 01
humandiskquotaany
The disk quota, in human-readable format. The disk quota and the unit of measure. None - The account possesses an unlimited disk quota.
humandiskusedstring
The disk space that the email account uses, in human-readable format. The disk space that the email account uses, a non-breaking space (\u00a0), and the unit of measure. None - The account possesses an unlimited disk quota.
loginany
The email address, or the main account username. A valid email address. The username for the main account.
mtimeinteger
The email account's last modification time, in Unix time format.
suspended_incominginteger
Whether the email account's incoming email is suspended. 1 - Suspended. 0 - Not suspended.
One of: 01
suspended_logininteger
Whether the user's ability to log in to, send mail from, and read their email account is suspended. 1 - Suspended. 0 - Not suspended.
One of: 01
suspended_outgoinginteger
Whether the email account's outgoing email is suspended. 1 - Suspended. 0 - Not suspended.
One of: 01
txtdiskquotaany
The email account's disk quota. A positive value that represents the email address's quota, in megabytes (MB). unlimited - The email account has an unlimited quota.
userstring
The email account username. For example, user if the email address is user@example.com.
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.
filter*stringRequired
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.
mailboxstringRequired
The email address.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
domainstringRequired
The mail exchanger's domain.
alwaysacceptstringOptional
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.
mxcheckstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
checkmxobject
An object containing the mail exchanger's data.
changedinteger
Whether a change occurred during the function. 1 — Change occurred. 0 — No change.
One of: 01
detectedstring
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.
One of: autolocalsecondaryremote
isprimaryinteger
Whether the mail exchanger is the primary mail exchanger. 1 — Primary. 0 — Not primary.
One of: 01
issecondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 — Secondary. 0 — Not secondary.
One of: 01
localinteger
Whether the mail exchanger is a local exchanger. 1 — Local. 0 — Not local.
One of: 01
mxcheckstring
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.
One of: autolocalsecondaryremote
remoteinteger
Whether the mail exchanger is a remote exchanger. 1 — Remote. 0 — Not remote.
One of: 01
secondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 — Secondary. 0 — Not secondary.
One of: 01
warningsarray<string>
An array of warning messages, if any exist. One or more warning messages.
detectedstring
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.
localinteger
Whether the mail exchanger is a local exchanger. 1 — Local. 0 — Not local.
One of: 01
mxcheckstring
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.
remoteinteger
Whether the mail exchanger is a remote exchanger. 1 — Remote. 0 — Not remote.
One of: 01
resultsstring
A message of success or a reason for failure. A message of success that includes the new type. A string that describes an error.
secondaryinteger
Whether the mail exchanger is a secondary exchanger. 1 — Secondary. 0 — Not secondary.
One of: 01
statusinteger
Whether the function succeeded. 1 — Success. 0 — Failure.
One of: 01
statusmsgstring
A message of success or a reason for failure. A message of success that includes the new type. A string that describes an error.
This function configures a default (catchall) email address.
Important:
When you disable the Mail Receive role, the system disables this function.
fwdoptstringRequired
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.
domainstringOptional
The domain whose default email behavior you want to configure. Note: This parameter defaults to the cPanel account’s main domain.
failmsgsstringOptional
The failure message for the message’s sender. Note: Use this parameter if you used the fail method for the fwdopt parameter.
fwdemailstringOptional
The email address to which the system forwards messages. Note: Use this parameter if you used the fwd method for the fwdopt parameter.
pipefwdstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:
deststring
The destination to which the system sends unroutable mail. - An email address The system forwards mail to this address. - :fail: The system bounces mail back to the sender, and sends a failure message. - :blackhole: The system deletes mail without a failure message. - The path to an application The system pipes mail to this application.
This function modifies a Mailman mailing list's privacy options.
Important:
When you disable the Receive Mail role, the system disables this function.
advertisedintegerRequired
Whether the Mailman directory page displays the list. 1 - Display. 0 - Does not display.
archive_privateintegerRequired
Whether the mailing list archive is private. 1 - Private. 0 - Public.
liststringRequired
The mailing list name.
subscribe_policyintegerRequired
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
domainstringRequired
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.
mx_hostmixedRequired
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
additionalPropertiesstring
The domain for which the function replaced the manual MX redirect entry. * null — The domain did not have an existing manual MX redirect entry. Note: This return's name is the domain parameter's value.
This function returns the status of the eximstats SQLite Database.
Important:
When you disable the Receive Mail role, the system disables this function.
No parameters.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
The disk space that the email account uses. active - The database is available and up-to-date. importing - The database is available, but a data import is currently in progress. * upcp - The database is unavailable because cPanel & WHM is updating. Note: If the eximstats database is running a cPanel & WHM update, but the database is available, this function will return active, notupcp.
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.
action*mixedRequired
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.
filternamestringRequired
The filter name.
match*mixedRequired
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: ismatchescontainsdoes not containbeginsdoes not beginendsdoes not enddoes not match Numeric operators: is aboveis not aboveis below * is not belowImportant: You must increment each match type. For example, pass the first match type as match1 and the second match type as match2.
part*mixedRequired
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.
val*mixedRequired
The value to match. Important: You must increment each value. For example, pass the first value as val1 and the second value as val2.
accountstringOptional
The email address, for user-level filters. If you do not use this parameter, the function creates an account-level filter.
dest*mixedOptional
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.
oldfilternamestringOptional
The name of an existing filter, to rename it. If you do not use this parameter, the function creates a new filter.
opt*mixedOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
accountstring
The filter's email address. The function only returns this value if it created a user-level filter.
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.
emailstringOptional
The email user's account name.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
emailstringRequired
The email user's account name.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
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.
emailstringRequired
The email account's username.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
Whether the function succeeded. 1 — The function succeeded. 0 — The function failed.
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.
msgstringRequired
The string to test. The function uses this string as the body of an email message, to check whether filters would match the string.
accountstringOptional
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
tracestring
A series of messages that describe the trace results. Note: This output may contain HTML.
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.
domainstringRequired
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.
Response — normalized as { ok, data, errors[], warnings[] }; data contains:
additionalPropertiesstring
The domain for which the function removed the manual MX redirect entry. * null — The domain did not have a manual MX redirect entry. Note: This return's name is the domain parameter's value.