.pdf)
WHM Plugins
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Check to see how the main email account for a domain handles undeliverable mail. Unroutable messages may be sent to /dev/null, :fail:, :blackhole:, forwarded to another address, or piped to a program. |
| Returns: | |
<data> <status> A boolean value describing how unroutable messages are handled. A value of '1' means that unroutable emails are deleted. A value of '0' means that messages are forwarded to another address or piped to a program.</status> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Modify an email account's quota. |
| Parameters: | |
| domain (string) | |
| The domain of the email account you wish to modify (e.g. 'example.com' if the address was 'user@example.com'). | |
| email (string) | |
| The username portion of the email address (e.g. 'user' if the address was 'user@example.com'). | |
| quota (integer) | |
| A positive integer indicating the new disk quota value in megabytes. Enter 0 for an unlimited quota. | |
| Returns: | |
<data> <reason> A string value that contains a success message or a reason for failure.</reason> <result> A boolean value indicating success or failure. 1 for success. 0 for failure.</result> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Delete an e-mail account. |
| Parameters: | |
| domain (string) | |
| The domain corresponding to the email account you wish to remove. (This value should consist of the text after the 'at' (@) sign. For example, example.com if the address you wished to remove was user@example.com). | |
| email (string) | |
| The username corresponding to the email account you wish to remove. (This value should consist of the text before the 'at' (@) sign. For example, user if the address you wished to remove was user@example.com). | |
| Returns: | |
<data> <result> A boolean value that indicates whether or not the email account was successfully removed. '1' if successful. '0' if failed.</result> <reason> A string value that is undefined if the account was successfully removed. This value will contain a reason for failure if the account was not removed.</reason> <rawout> A string value that is undefined if the account was successfully removed. This value will contain a message from the Whostmgr binary if the account was not removed.</rawout> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | List forwarders associated with a specific domain. |
| Parameters: | |
| domain (string (optional)) | |
| The domain name whose forwarders you wish to review. | |
| regex (regular expression (optional)) | |
| Regular expressions allow you to filter results based on a set of criteria. | |
| Returns: | |
<data> <uri_dest> A string value that contains the address from which mail is forwarded in a URI encoded format.</uri_dest> <forward> A string value that contains the address to which mail is forwarded in plain text. </forward> <html_dest> A string value that contains the address from which mail is forwarded in an HTML-safe format. </html_dest> <uri_forward> A string value that contains the address to which mail is forwarded in a URI encoded format. </uri_forward> <dest> A string value that contains the address from which mail is forwarded in plain text. </dest> <html_forward> A string value that contains the address to which mail is forwarded in an HTML-safe format. </html_forward> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Add (create) an e-mail account. |
| Parameters: | |
| domain (string) | |
| Domain name for the e-mail account. | |
| email (string) | |
| Username part of the e-mail account (the address part before "@"). | |
| password (string) | |
| Password for the e-mail account. | |
| quota (integer) | |
| Positive integer defining a disk quota for the e-mail account; could be 0 for unlimited. | |
| Returns: | |
<data> <reason> A string value that contains the email address if the function completes successfully. This value will contain a reason for failure if the function encounters an error.</reason> <result> A boolean value that indicates success or failure. '1' indicates that the function completed successfully.</result> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Lists mailing lists. |
| Parameters: | |
| domain (string (optional)) | |
| The domain whose mailing lists you wish to view. | |
| regex (regular expression (optional)) | |
| Regular expressions allow you to filter results based on a set of criteria. | |
| Returns: | |
<data> <list> A string value that contains the name of a mailing list including the domain, separated by an at (@) sign. (e.g. listname@example.com)</list> <desthost> A string value that contains the IP address corresponding to the domain whose mailing lists you are viewing.</desthost> <listid> A string value that contains the name of a mailing list including the domain, separated by an underscore (_). (e.g. listname_exampe.com)</listid> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Check the cPanel configuration to see if a domain uses the local server as a mail exchanger. This function is not available to users that do not have access to the 'changemx' feature. Remember: This function checks the cPanel configuration, not DNS records. |
| Parameters: | |
| domain (string (optional)) | |
| The domain you wish to examine. If this value is not specified, the function will return output for each domain you own. | |
| Returns: | |
<data> <alwaysaccept> A boolean value indicating whether or not the domain accepts all local mail. '0' if the domain is not set to always accept mail locally. '1' if the domain accepts mail locally.</alwaysaccept> <mxcheck> A string value that should always return 'auto'.</mxcheck> <domain> A string value that contains the domain corresponding to the data you are examining.</domain> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Create an email forwarder for a specified address. You can forward mail to a new address or pipe incoming email to a program. |
| Parameters: | |
| domain (string) | |
| The domain for which you wish to add a forwarder (e.g. example.com). | |
| email (string ) | |
| The local address you wish to use as a forwarder (e.g. 'user' if the address was user@example.com). | |
| fwdopt (string) | |
| This parameter defines what type of forwarder should be used. The valid values for this option are: 'pipe' - for forwarding to a program 'fwd' - for forwarding to another non-system email address 'system' - for forwarding to an account on the system 'blackhole' - for bouncing emails using the blackhole functionality 'fail' - for bounding emails using the fail functionality. |
|
| fwdemail (string (optional)) | |
| The email address to which you want to forward mail. | |
| fwdsystem (string (optional)) | |
| The system account that you wish to forward email to, this should only be used if 'fwdopt' equals 'system'. | |
| failmsgs (string (optional)) | |
| If fwdopt is 'fail' this needs to be defined to determine the correct failure message. This should only be used if 'fwdopt' equals 'fail'. | |
| pipefwd (string (optional)) | |
| The path to the program to which you wish to pipe email. | |
| Returns: | |
<data> <fwdemail> The email address that will receive forwarded mail.</fwdemail> <domain> The domain for which the forwarder was configured.</domain> <email> The email address that will act as the forwarder.</email> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Configure a default (catchall) email address. A default address handles unroutable mail sent to a domain. Note: Irrelevant parameters are passed to the function regardless of its configuration and will be included in the rule. This will not cause any problems. |
| Parameters: | |
| fwdopt (string) | |
| Describes how unroutable mail will be handled. The following options are available: 'fail' => Bounce unroutable messages, returning a failure message to the sender. 'fwd' => Forward unroutable messages to another email address. 'blackhole' => Send undeliverable mail to /dev/null. This option will not generate a failure notice. 'pipe' => Pipe undeliverable mail to a program. . |
|
| domain (string) | |
| The domain to which the rule will apply. If this parameter is not specified, cPanel will attempt to use the cPanel account's main domain. Note: The user must own this domain. | |
| failmsgs (string (optional)) | |
| The failure message that will be sent to the sender in the event an incoming message is bounced. The default value is set to, "No such person at this address." Note: This parameter only takes effect if fwdopt = 'fail'. | |
| fwdemail (string (optional)) | |
| The email address to which mail received by the default address will be sent. Note: This parameter only takes effect if fwdopt = 'fwd'. Enter the email address in standard format. (e.g. 'user@example.com'). | |
| pipefwd (string (optional)) | |
| The program to which messages received by the default address will be piped (|). Note: cPanel will append the user's home directory to the beginning of the value. | |
| Returns: | |
<data> <domain> A string value that contains the domain for which the catchall rule was added.</domain> <dest> A string value that contains the destination of messages received by the catchall address. (e.g. ':fail:', 'No such person at this address', 'forwardto@example.com', "| /home/$user/PROGAM", ':blackhole:'.)</dest> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Set a mail exchanger for a specified domain to local, remote, secondary, or auto. The 'auto' value allows cPanel to determine the appropriate role for the mail exchanger. Note: This function only affects the cPanel configuration. You will need to configure the MX's DNS entry elsewhere. Remember: This function is not available if the 'changemx' feature is not enabled for the user. |
| Parameters: | |
| domain (string) | |
| The domain corresponding to the mail exchanger you wish to set. | |
| mxcheck (string) | |
| The status of the mail exchanger as it corresponds to cPanel's configuration. Input options are as follows: 'auto' - Allow cPanel to determine the appropriate role based on a DNS query on the MX record. 'local' - Always accept and route mail for the domain. 'secondary' - Accept mail for the domain until a high priority (lower numbered) mail server becomes available. 'remote' - Do not accept mail for the domain. |
|
| user (string) | |
| The user of the cPanel account whose domain corresponds to the mail exchanger you wish to set. | |
| Returns: | |
<data> <mxcheck> A string value that contains the input value specified in the input parameters.</mxcheck> <statusmsg> A string value that contains a message of success or a reason for failure.</statusmsg> <checkmx> Note: The following values pertain to the old mail exchanger. <mxcheck> A string value that contains the input value specified in the input parameters.</mxcheck> <detected> A string value that contains the previous 'mxcheck' value.</detected> <isprimary> A boolean value that indicates whether or not the mail exchanger is the primary mail exchanger. '1' if the mail exchanger is the primary exchanger.</isprimary> <secondary> A boolean value that indicates whether or not the mail exchanger is the secondary mail exchanger. '1' if the mail exchanger is the secondary exchanger.</secondary> <remote> A boolean value that indicates whether or not the mail exchanger is a remote exchanger. '1' if the exchanger is remote.</remote> <changed> A boolean value indicating whether or not the new setting is different from the old. In practice, this value is always '1'.</changed> <warnings> A string value that contains any warnings or error messages that may arise.</warnings> <issecondary> A boolean value that indicates whether or not the mail exchanger is the secondary mail exchanger. '1' if the mail exchanger is the secondary exchanger.</issecondary> <local> A boolean value that indicates whether or not the mail exchanger is a local exchanger. '1' if the mail exchanger is a local exchanger.</local> </checkmx> <detected> A string value that contains the input value specified in the input parameters if the function ran successfully.</detected> <results> A string value that contains a success message or reason for failure.</results> <secondary> A boolean value that indicates whether or not the mail exchanger is the secondary mail exchanger. '1' if the mail exchanger is the secondary exchanger.</secondary> <remote> A boolean value that indicates whether or not the mail exchanger is a remote exchanger. '1' if the exchanger is remote.</remote> <status> A boolean value indicating success or failure. '1' if the function completed successfully.</status> <local> A boolean value that indicates whether or not the mail exchanger is a local exchanger. '1' if the mail exchanger is a local exchanger.</local> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of email accounts and logins associated with your cPanel account. This will include email addresses from the the main domain, addon domains and parked domains. |
| Returns: | |
<data> <login> A string value that contains the login corresponding to the account you are viewing. This value contains the domain associated with the account. (e.g. user@example.com)</login> <email> A string value that contains the full email address corresponding to the account you are viewing. (e.g. user@example.com)</email> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of domains associated with your account that send and receive email. This list includes the main domain, addon domains, and parked domains. |
| Parameters: | |
| skipmain (Boolean (optional)) | |
| By passing '1' to this variable, you may skip the main domain. | |
| Returns: | |
<data> <domain> A string value that contains a mail domain associated with your cPanel account.</domain> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Change values for a specific MX record. This function is not available in DEMO mode. You must have access to the 'changemx' feature to use this function. |
| Parameters: | |
| domain (string) | |
| The domain corresponding to the MX record you wish to change. | |
| exchange (string) | |
| The name you wish to give to the new exchanger. | |
| oldexchange (string (optional)) | |
| The name of the exchanger you wish to replace. If you do not specify this parameter, a new entry will be created. | |
| oldpreference (integer) | |
| The priority value of the old exchanger. If two entries for 'oldexchange' match, the function will decide which value will be used. | |
| preference (integer) | |
| The new exchanger's priority value. | |
| alwaysaccept (string (optional)) | |
| This parameter specifies how the new exchanger should behave. Possible values are 'local', 'secondary', 'backup', or 'remote'. If you choose not to specify this parameter, cPanel will choose the best possible value. | |
| Returns: | |
<data> <status> A boolean value that indicates success or failure. '1' if the function completed successfully.</status> <statusmsg> A string value that contains a message describing the action taken by the function. (e.g. Replacing existing entry on line matched old entry and old priority: [integer]: Bind reloading on bilbo using rndc zone: [example.com])</statusmsg> <checkmx> These values indicate the status of the mail exchanger you have added: <mxcheck> A string value that contains the type of mail exchanger you have added. (e.g. local, remote, secondary, or auto)</mxcheck> <detected> This value is the same as mxcheck.</detected> <isprimary> A boolean value that indicates whether or not the mail exchanger is the primary (local) mail exchanger. '1' if it is the secondary mail exchanger. '0' if it is not.</isprimary> <secondary> A boolean value that indicates whether or not the mail exchanger is a secondary mail exchanger. '1' if it is the secondary mail exchanger. '0' if it is not.</secondary> <remote> A boolean value that indicates whether or not the mail exchanger is a remote mail exchanger. '1' if it is the remote mail exchanger. '0' if it is not.</remote> <changed> A boolean value that indicates whether or not a change has occurred. '1' if a change has occurred. '0' if a change has not occurred.</changed> <warnings> A string value that contains warnings if there are any.</warnings> <issecondary> A boolean value that indicates whether or not the mail exchanger is a secondary mail exchanger. '1' if it is the primary mail exchanger. '0' if it is not.</issecondary> <local> A boolean value that indicates whether or not the mail exchanger is the local mail exchanger. '1' if it is the local mail exchanger. '0' if it is not.</local> </checkmx> <results> A string value that contains a message of success or a reason for failure. This value is often identical to 'statusmsg'.</results> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Add an MX record. This function will not work if you do not have access to the 'changemx' feature. |
| Parameters: | |
| domain (string) | |
| The domain to which you wish to add the mail exchanger. | |
| exchange (string) | |
| The name of the mail exchanger (e.g. mail.example.com). | |
| preference (integer) | |
| The priority of the mail exchanger. Remember: Lower values translate to higher priorities, with 0 being the highest priority exchanger. Traditionally, increments of 5 or 10 are used. | |
| alwaysaccept (string (optional)) | |
| This value describes whether or not the local machine should accept mail for this domain. Possible values are as follows: 'auto' - Allow cPanel to determine the appropriate role based on a DNS query on the MX record. 'local' - Always accept and route mail for the domain. 'secondary' - Accept mail for the domain until a higher priority (lower numbered) mail server becomes available. 'remote' - Do not accept mail for the domain. |
|
| Returns: | |
<data> <status> A boolean value indicating success or failure. '1' if successful. '0' if failed.</status> <statusmsg> A string that contains a success message or reason for failure.</statusmsg> <checkmx> These values indicate the status of the mail exchanger you have added: <mxcheck> A string value that contains the type of mail exchanger you have added. (e.g. local, remote, secondary, or auto)</mxcheck> <detected> This value is the same as mxcheck.</detected> <isprimary> A boolean value that indicates whether or not the mail exchanger is the primary (local) mail exchanger. '1' if it is the primary mail exchanger. '0' if it is not.</isprimary> <secondary> A boolean value that indicates whether or not the mail exchanger is a secondary mail exchanger. '1' if it is the primary mail exchanger. '0' if it is not.</secondary> <remote> A boolean value that indicates whether or not the mail exchanger is a remote mail exchanger. '1' if it is the primary mail exchanger. '0' if it is not.</remote> <changed> A boolean value that indicates whether or not a change has occurred. '1' if a change has occurred. '0' if a change has not occurred.</changed> <warnings> A string value that contains warnings if there are any.</warnings> <issecondary> A boolean value that indicates whether or not the mail exchanger is a secondary mail exchanger. '1' if it is the primary mail exchanger. '0' if it is not.</issecondary> <local> A boolean value that indicates whether or not the mail exchanger is the local mail exchanger. '1' if it is the local mail exchanger. '0' if it is not.</local> </checkmx> <results> A string that contains a success message or reason for failure., (e.g 'Bind reloading on tom using rndc zone: [domain]' if successful.)</results> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | List all mail exchangers associated with a domain. You must have access to the 'changemx' feature to use this function. |
| Parameters: | |
| domain (string) | |
| The domain whose mail exchangers you wish to view. | |
| Returns: | |
<data> <statusmsg> A string value that contains a status message. (e.g. Fetched MX List)</statusmsg> <status> A boolean value indicating success or failure. '1' if successful. '0' if failed.</status> <entries> This value is a list of hashes, one for each MX: <priority> An integer value that contains the priority of the mail exchanger, with '0' being the highest priority exchanger.</priority> <mx> A string value that contains the name of the mail exchanger. (e.g. mail.example.com)</mx> <domain> The domain to which the mail exchanger belongs. (e.g. example.com)</domain> <entrycount> An integer value that contains the mail exchanger's priority order. '1' for highest priority, '2' for second highest priority, etc.</entrycount> <row> A string value that contains the mail exchanger's entry count. (e.g. 'odd' or 'even')</row> </entries> <local> A boolean value indicating whether or not the mail exchanger is a local mail exchanger. '1' if the mail exchanger is local to this server.</local> <remote> A boolean value that indicates whether or not the mail exchanger is a remote exchanger. '1' if mail exchanger is remote.</remote> <detected> A string value that describes whether cPanel regards the mail exchanger as 'local', 'remote', 'secondary', or 'auto'.</detected> <mx> A string value that contains the name of the mail exchanger. (e.g. mail.example.com)</mx> <domain> A string value that contains the domain to which the mail exchanger belongs. (e.g. example.com)</domain> <secondary> A boolean value that indicates whether or not the mail exchanger is a secondary exchanger. '1' if the mail exchanger is a secondary exchanger.</secondary> <mxcheck> A string value that contains how cPanel regards the mail exchanger. (e.g. 'auto', 'local', 'secondary', or 'remote')</mxcheck> <alwaysaccept> A boolean value that describes whether the mail exchanger will always accept local email. '1' if local, '0' if it is not.</alwaysaccept> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | List all of the old-style email filters in your .filter file. This function lists both account-level and user-level filters. |
| Returns: | |
<data> <nicedest> A string value that describes the action taken by the filter. (e.g. Discard)</nicedest> <filter> A string value that contains information about the filter.</filter> <dest> A string value that contains the destination for filtered mail. (e.g. /dev/null)</dest> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of character encodings supported by cPanel. |
| Returns: | |
<data> <map> A string value that contains an acceptable character encoding.</map> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of auto responders associated with a domain. |
| Parameters: | |
| domain (string (optional)) | |
| The domain whose auto responders you wish to view. | |
| regex (Regular Expression (optional)) | |
| Regular expressions allow you to filter results based on a set of criteria. | |
| Returns: | |
<data> <subject> A string value that contains the subject of the email that will be sent in the auto response.</subject> <email> A string value that contains the email address for which the auto responder is configured.</email> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Delete an MX record. This function will not work if the 'changemx' feature is disabled for the current user. |
| Parameters: | |
| domain (string) | |
| The domain that corresponds to the mail exchanger you wish to remove. | |
| exchange (string) | |
| The name of the mail exchanger you wish to remove (e.g. 'mail.example.com'). | |
| preference (integer) | |
| The priority of the mail exchanger, 0 being the highest priority exchanger. Traditionally, increments of 5 or 10 are used. | |
| Returns: | |
<data> <status> A boolean value indicating success or failure. '1' for success. '0' for failure.</status> <statusmsg> A string value that contains a success message or a reason for failure.</statusmsg> <checkmx> These values indicate the status of the mail exchanger you have just removed. <mxcheck> A string value that contains the type of mail exchanger that has been deleted. (e.g. 'local', 'remote', 'secondary', or 'auto'.)</mxcheck> <detected> This value is the same same as mxcheck.</detected> <isprimary> A boolean value that represents whether or not the mail exchanger that has just been deleted was a primary mail exchanger. '1' if the exchanger primary (local) mail exchanger. '0' if it was not.</isprimary> <secondary> A boolean value that represents whether or not the mail exchanger that has just been deleted was a secondary mail exchanger. '1' if the exchanger was a secondary mail exchanger. '0' if it was not.</secondary> <remote> A boolean value that represents whether or not the mail exchanger that has just been deleted was a remote mail exchanger. '1' if the exchanger was a remote mail exchanger. '0' if it was not.</remote> <changed> A boolean value that represents whether or not a change has occurred. '1' if a change has occurred. '0' if one has not.</changed> <warnings> A string value that contains any warnings about the deletion of the mail exchanger.</warnings> <issecondary> A boolean value that represents whether or not the mail exchanger that has just been deleted was a secondary mail exchanger. '1' if the exchanger was a secondary exchanger. '0' if it was not.</issecondary> <local> A boolean value that represents whether or not the mail exchanger that has just been deleted was a local mail exchanger. '1' if the exchanger was local. '0' if it was not.</local> </checkmx> <results> A string value that represents the status of the mail exchanger's removal. This message is often similar to 'statusmsg'.</results> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve the destination for email forwarded by a domain forwarder. |
| Parameters: | |
| domain (string) | |
| The domain corresponding to the forwarder whose destination you wish to view. | |
| Returns: | |
<data> <forward> A string value that contains the local domain responsible for forwarding messages.</forward> <dest> A string value that contains the domain that will receive forwarded mail.</dest> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of email accounts and logins associated with your cPanel account. This list includes email addresses from the the main domain, addon domains, and parked domains. This list will also contain your account's username and an HTML link to the 'mainacct.jpg' graphic, based on your account's style (skin). |
| Returns: | |
<data> <login> A string value that contains the login that corresponds to the account you are viewing. This value contains the domain. (e.g. user@hosted-domain.com)</login> <email> A string value that contains the email address that corresponds to the email account you are viewing. (e.g. user@hosted-domain.com)</email> <login> A string value that contains the HTML link to the 'mainacct.jpg' graphic. (e.g. img src="/frontend/cpanel-skin/images/mainacct.jpg")</login> <email> A string value that contains your cPanel username.</email> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of email accounts associated with your cPanel account. Email::listpopswithdisk is the preferred way of retrieving a list of email accounts. |
| Parameters: | |
| regex (Regular Expression (optional)) | |
| Regular expressions allow you to filter results based on a set of criteria. | |
| Returns: | |
<data> <login> A string value that contains an email address or 'Main Account' if the email address is the main account.</login> <email> A string value that contains the login used to authenticate mail services.</email> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve the default address or action taken when unroutable messages are received by the default address. |
| Parameters: | |
| domain (string) | |
| The domain that corresponds to the default address and information you wish to view. | |
| Returns: | |
<data> <defaultaddress> A string value that contains the default address or the action taken when unroutable mail is received.</defaultaddress> <Thedefaultaddress> This email address will receive unroutable mail.</Thedefaultaddress> <:Fail:> A string value indicating that the address responsible for sending unroutable mail will receive a failure message explaining that the message was not delivered.</:Fail:> <:blackhole:> A string value that indicates that unroutable mail is silently discarded.</:blackhole:> <domain> A string value that contains the domain corresponding to the default address. (e.g. example.com)</domain> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | List email accounts associated with a particular domain. This function will also list quota and disk usage information. |
| Parameters: | |
| domain (string (optional)) | |
| The domain whose email accounts you wish to view. | |
| nearquotaonly (boolean (optional)) | |
| Passing '1' to this parameter allows you to only view accounts that have used 95% or more of their allotted disk space. | |
| no_validate (boolean (optional)) | |
| Passing '1' to this parameter will cause the function to only read data from your '.cpanel/email_accounts.yaml' file. This parameter is 'off' by default, causing the function to check the passwd file, quota files, etc. Theoretically, each of these files should contain identical values. | |
| regex (Regular Expressions (optional)) | |
| Regular expressions allow you to filter results based on a set of criteria. | |
| Returns: | |
<data> <txtdiskquota> An integer value that contains the disk quota in megabytes.</txtdiskquota> <diskquota> An integer or string value that contains the disk quota in megabytes. This value is affected by the account's locale (language). (e.g. '250' or 'unlimited')</diskquota> <diskusedpercent> An integer value that contains the percentage of disk space used.</diskusedpercent> <diskused> A floating point value that contains the disk space used in megabytes. (e.g. 108.83)</diskused> <humandiskquota> A string value that contains the disk quota with the descriptor. (e.g. '250 MB')</humandiskquota> <_diskused> An integer value that contains the disk space used in bytes.</_diskused> <login> A string value that contains the login name of the account. This value contains the domain. (e.g. user@example.com)</login> <email> A string value that contains the email address of the account.</email> <domain> A string value that contains the domain name you have queried. (e.g. example.com)</domain> <user> A string value that contains the username that corresponds to the domain.</user> <humandiskused> A string value that contains the amount of disk space used and the signifier. (e.g. '109.39 MB' or 'none')</humandiskused> <diskusedpercent20> An integer value that contains the percentage of disk space used.</diskusedpercent20> <_diskquota> An integer value that contains the disk quota in bytes.</_diskquota> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Change an email account's password. |
| Parameters: | |
| domain (string) | |
| The domain corresponding to the email address whose password you wish to change. (This value should consist of the text after the 'at' (@) sign. For example, example.com if the address you wished to remove was user@example.com). | |
| email (string) | |
| The username corresponding to the email address whose password you wish to change. (This value should consist of the text before the 'at' (@) sign. For example, user if the address you wished to remove was user@example.com). | |
| password (string) | |
| The new password for the account. | |
| Returns: | |
<data> <reason> A string value that is undefined if the password was changed. This value will contain a reason for failure if the account's password was not changed.</reason> <result> A boolean value indicating success or failure. '1' if successful. '0' if failed.</result> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve the full path to a specified mail folder. This directory needs to be under the account's main mail directory. |
| Parameters: | |
| account (string) | |
| The email address corresponding to the directory whose path you wish to find (e.g. user@example.com). | |
| dir (string (optional)) | |
| The mail folder you wish to query for its full path. If you do not specify this parameter, 'mail' will be used. | |
| Returns: | |
<data> <absdir> A string value that contains the full path to the requested directory.</absdir> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of mail-related subdirectories (boxes) in your mail directory. |
| Parameters: | |
| account (string (optional)) | |
| The name of the email account you wish to review. | |
| dir (string (optional)) | |
| This parameter allows you to specify which mail directories will be displayed. Specifying 'default' or 'mail' will cause the function to list all of your domains' mail directories. By providing a domain (e.g. 'mail/example.com' or 'example.com'), the function will display account directories related to the domain. | |
| showdotfiles (boolean (optional)) | |
| A boolean variable that allows you to specify whether or not you wish to view hidden directories and files (e.g. '.hidden-dir'). | |
| Returns: | |
<data> <mtime> An integer value that contains the last modification time epochal. (e.g. 1258338752)</mtime> <isleaf> A boolean value that specifies whether or not the item in the list is a file. '1' if it is a file.</isleaf> <file> A string value that contains the base name of the file or directory. (e.g. example.com)</file> <path> A string value that contains the full path to the file or directory.</path> <depth> An integer value that contains the number of directories deep inside the absolute home directory the item in the list is.</depth> <relpath> A string value that contains the relative path to the 'mail' directory including the initial slash. (e.g. /example.com)</relpath> <ismailbox> A boolean value that specifies whether or not the item in the list is a mailbox. '1' if the item is a mailbox.</ismailbox> <fullpath> A string value that contains the item in the list.</fullpath> <type> A string value that contains 'dir' or 'file' depending on whether the item in the list is a directory or a file. This value is always 'dir' at the moment.</type> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of email filters. |
| Parameters: | |
| account (string (optional)) | |
| This parameter allows you to specify an email address or account username to review user-level filters. Specifying an email address will cause the function to retrieve user-level filters associated with the account. Entering a cPanel username will cause the function to return user-level filters associated with your account's default email address. If you do not specify this value, the function will retrieve account-level filter information. | |
| Returns: | |
<data> <filtername> A string value that contains the filter's name.</filtername> <actions> <dest> A string value that contains the destination of filtered mail. (e.g. /dev/null)</dest> <action> A string value that contains a description of the action taken by the filter.</action> </actions> <rules> <part> A string value that contains the section of the email covered by the filter. (e.g. $header_from:)</part> <match> A string value that contains the match type. (e.g. 'is' or 'contains')</match> <val> A string value that contains a phrase for which the filter is searching.</val> <opt> A string value that contains either 'or' or 'and' as a connector for the next rule in the list.</opt> </rules> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Rebuild an email address' cache file. |
| Parameters: | |
| username (string) | |
| The username corresponding to the account whose cache file you wish to rebuild. | |
| Returns: | |
<data> <status> A boolean value indicating success or failure. '1' if successful. '0' if failed.</status> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Create a new email filter. Note the asterisks after some of the parameter names. Since it is possible to have more than one set of conditions, your first set of conditions must have a '1' appended to the parameter names. The second set of conditions with a '2', etc. You may have up to 4096 conditions. Generally, you will only need a second set of 'part', 'match', 'val', and 'opt',parameters unless you a want second set of actions. In this case, you will need to create incremental versions of 'action' and 'dest'. You will need to define ' part1', 'match1', 'val1', 'opt1', 'action1', and 'dest1'. In addition, you may want values for 'part2', 'match2', 'val2', and 'opt2' if you need a complex rule. See the cPanel interface for reference. |
| Parameters: | |
| account (string) | |
| To configure a user-level filter, enter the email address to which you would like to apply the rule. If you would like to set up an account-level filter, do not enter a value for this parameter. If you would like to configure a filter for the default email account, enter the cPanel username corresponding to the catch-all address to which the new rule will apply. | |
| action* (string) | |
| The action taken by the filter. Acceptable values include 'deliver', 'fail', 'finish', 'save', and 'pipe'. If you do not wish for this filter to take more than one action, you will not need to specify an incremental version of this parameter. | |
| dest* (string (optional)) | |
| The destination for mail received by the filter, if one is required. (e.g. /dev/null) This parameter corresponds with the 'action' parameter. You do not need an incremental version of this parameter if you do not need more than one action. | |
| filtername (string) | |
| The name you wish to give to the new filter. | |
| match* (string) | |
| The new filter match type. Acceptable values are 'is', 'matches', 'contains', 'does not contain', 'begins', 'ends', 'does not begin', 'does not end', 'does not match', 'is above', 'is not above', 'is below', and 'is not below'. The last 4 options pertain only to numbers. | |
| oldfiltername (string (optional)) | |
| This function can also be used to rename an existing filter. To change the filter's name, supply the existing filter's name in this parameter and the new name in the 'filtername' parameter. | |
| opt* (string) | |
| This parameter connects conditionals. Acceptable values are 'and' or 'or'. This value defaults to 'or'. | |
| part* (string) | |
| The section of the email to which you want to apply the 'match' parameter. Acceptable values are '$header_from:', '$header_subject:', '$header_to:', '$reply_address:', '$message_body', '$message_headers', 'foranyaddress $h_to",$h_cc:,$h_bcc:', 'not delivered', 'error_message', '$h_X-Spam-Status:', '$h_X-Spam-Score:', and '$h_X-Spam-Bar:'. The last 3 options require SpamAssassin to be enabled. You may also use 'error_message' or 'not delivered' which do not require the 'match' parameter. | |
| val* (string) | |
| The value against which you want to match. (e.g. 'cheap prescriptions' or 'free stuff'). | |
| Returns: | |
<data> <ok> A boolean value indicating success or failure. '1' if the function completed successfully.</ok> <account> A string value that contains the account name for which the filter was created.</account> <error> A boolean value of '0' if the function completed successfully. Otherwise, this will be a string value that contains an error message.</error> <result> A string value that contains 'Filter Saved' if the function completed successfully. Otherwise, this string value will contain an error message.</result> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Test the action of account-level mail filters. You can only test filters for your cPanel account's main domain. This function only tests the body of the message. You must have access to the 'blockers' feature to use this function. |
| Parameters: | |
| account (string (Optional)) | |
| This parameter allows you to specify and test old-style cPanel filters in your $home/filters directory. By not specifying this parameter, you will test your main domain's filters found in the /etc/vfilters/ directory. | |
| msg (string) | |
| The contents of the body of the message you wish to test. | |
| Returns: | |
<data> <trace> A string value that contains a message of success or reason for failure, the name of the file that was examined, and the destination of the filter.</trace> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Delete an email filter. |
| Parameters: | |
| account (string (optional)) | |
| This parameter allows you to specify an email address or account username to remove user-level filters. By specifying an email address, the function will effect user-level filters associated with the account. Entering a cPanel username will cause the function to remove user-level filters associated with your account's default email address. By not specifying this value, the function will remove an account-level filter. | |
| filtername (string) | |
| The name of the filter you wish to delete. | |
| Returns: | |
<data> <filtername> A string value that contains the name of the filter you attempted to remove.</filtername> <deleted> A boolean value that indicates whether or not the filter was successfully deleted. '1' if the filter was removed; '0' if it was not.</deleted> <statusmsg> A string value that describes the success or failure of the request.</statusmsg> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve the rules and actions associated with an email filter. |
| Parameters: | |
| account (string (optional)) | |
| This parameter allows you to specify an email address or account username to review user-level filters. By specifying an email address, the function will retrieve user-level filters associated with the account. Entering a cPanel username will cause the function to return user-level filters associated with your account's default email address. By not specifying this value, the function will retrieve account-level filter information. | |
| filtername (string) | |
| The name of the filter you wish to review. | |
| Returns: | |
<data> <filtername> A string value that contains the name of the filter.</filtername> <actions> A hash or list of hashes that contain the actions of the filter. <number> An integer value that contains the order of the rule in the list. The first rule will be '1'.</number> <dest> A string value that contains the destination of filtered mail.</dest> <action> A string value that contains the type of action.</action> </actions> <rules> A hash or list of hashes that contain the rules for filtering mail. <number> An integer value that contains the order of the rule in the list. The first rule will be '1'.</number> <part> A string value that contains the section of the email covered by the filter. (e.g. $header_from:)</part> <match> A string value that contains the match type. (e.g. contains)</match> <val> A string value that contains a phrase for which the filter is searching.</val> <opt> A string value that contains either 'or' or 'and' as a connector for the next rule in the list.</opt> </rules> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Count the number of email filters and return a default suggested rule name (e.g. Rule [1 + count]). For example, if user@example.com used 3 user-level filters, this function would return 'Rule 4'. |
| Parameters: | |
| account (string (optional)) | |
| An email address associated with an account from which you wish to read the user-level filter file in order to receive the appropriate result. If you choose not to specify a value for this variable, the function will return a value based on account-level filters. Passing a username to this variable will cause the function to scan the account's filters for the default email account. | |
| filtername (string (optional)) | |
| A fallback in case the function cannot find any relevant filter files. Under certain conditions, the function will create empty versions of missing files, resulting in erroneous output when the function is run again. | |
| Returns: | |
<data> <filtername> A string value that contains the suggested rule name. This value is calculated by counting the number of existing filters and adding one. (e.g 'Rule 3', if there were already 2 rules.)</filtername> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Display the account name or 'All Mail On Your Account'. This is useful if you wish to retrieve the account name in a webmail interface. |
| Parameters: | |
| account (string) | |
| An account name or email address. The function will return whichever is not specified. | |
| display (string) | |
| If present, and an account is not specified, a string that contains 'All Mail On Your Account' is returned. | |
| Returns: | |
<data> <account> A string value that contains either the name of the account specified or 'All Mail On Your Account'.</account> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve information about an auto responder used by a specified email address. |
| Parameters: | |
| email (string) | |
| The email address corresponding to the auto responder information you wish to review. | |
| Returns: | |
<data> <charset> A string value that contains the name of the character set the auto responder is using.</charset> <ishtml> A boolean value that indicates whether or not the email is HTML-forwarded. '1' if email is HTML-forwarded.</ishtml> <body> A string value that contains the message contained within the 'body' portion of the email.</body> <subject> A string value that contains the 'subject' portion of the auto response email.</subject> <from> A string value that contains the 'from' portion of the auto response email.</from> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve information about a specific email account's disk usage. |
| Parameters: | |
| domain (string) | |
| The domain that corresponds to the email address whose disk usage information you wish to view. This value needs to be the section of the email address after the 'at' (@) sign (e.g. example.com). | |
| login (string) | |
| The username section of the email address whose disk usage information you wish to view. This value needs to be the section of the email address before the 'at' (@) sign (e.g. user). | |
| Returns: | |
<data> <diskused> A floating point decimal value of the disk space used in megabytes.</diskused> <login> A string value that contains the username section of the email address. (e.g. user)</login> <domain> A string value that contains the domain section of the email address. (e.g. example.com)</domain> <user> A string value that contains the username section of the email address. (e.g. user)</user> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of domains that use domain-level filters. |
| Returns: | |
<data> <domain> A string value that contains the domain name corresponding to a file in /etc/vfilters.</domain> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Retrieve a list of domains that use aliases and custom catch-all addresses. |
| Returns: | |
<data> <domain> A string value that contains the domain that corresponds to a file in /etc/valiases. (e.g. example.tld)</domain> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Set a mail exchanger for a specified domain to local, remote, secondary, or auto. The 'auto' value allows cPanel to determine the appropriate role for the mail exchanger. Note: This function only affects the cPanel configuration. You will need to configure the MX's DNS entry elsewhere. Remember: This function is not available if the 'changemx' feature is not enabled for the user. Internally, this call functions as an alias to Email::setalwaysaccept. However, this call will be parsed as a unique call when used in a hook or custom event handler. |
| Parameters: | |
| domain (string) | |
| The domain corresponding to the mail exchanger you wish to set. | |
| mxcheck (string) | |
| The status of the mail exchanger as it corresponds to cPanel's configuration. Input options are as follows: 'auto' - Allow cPanel to determine the appropriate role based on a DNS query on the MX record. 'local' - Always accept and route mail for the domain. 'secondary' - Accept mail for the domain until a high priority (lower numbered) mail server becomes available. 'remote' - Do not accept mail for the domain. |
|
| Returns: | |
<data> <mxcheck> A string value that contains the input value specified in the input parameters.</mxcheck> <statusmsg> A string value that contains a message of success or a reason for failure.</statusmsg> <checkmx> Note: The following values pertain to the old mail exchanger. <mxcheck> A string value that contains the input value specified in the input parameters.</mxcheck> <detected> A string value that contains the previous 'mxcheck' value.</detected> <isprimary> A boolean value that indicates whether or not the mail exchanger is the primary mail exchanger. '1' if the mail exchanger is the primary exchanger.</isprimary> <secondary> A boolean value that indicates whether or not the mail exchanger is the secondary mail exchanger. '1' if the mail exchanger is the secondary exchanger.</secondary> <remote> A boolean value that indicates whether or not the mail exchanger is a remote exchanger. '1' if the exchanger is remote.</remote> <changed> A boolean value indicating whether or not the new setting is different from the old. In practice, this value is always '1'.</changed> <warnings> A string value that contains any warnings or error messages that may arise.</warnings> <issecondary> A boolean value that indicates whether or not the mail exchanger is the secondary mail exchanger. '1' if the mail exchanger is the secondary exchanger.</issecondary> <local> A boolean value that indicates whether or not the mail exchanger is a local exchanger. '1' if the mail exchanger is a local exchanger.</local> </checkmx> <detected> A string value that contains the input value specified in the input parameters if the function ran successfully.</detected> <results> A string value that contains a success message or reason for failure.</results> <secondary> A boolean value that indicates whether or not the mail exchanger is the secondary mail exchanger. '1' if the mail exchanger is the secondary exchanger.</secondary> <remote> A boolean value that indicates whether or not the mail exchanger is a remote exchanger. '1' if the exchanger is remote.</remote> <status> A boolean value indicating success or failure. '1' if the function completed successfully.</status> <local> A boolean value that indicates whether or not the mail exchanger is a local exchanger. '1' if the mail exchanger is a local exchanger.</local> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Indicates whether DKIM is supported by Exim and enabled for the authenticated account. This API call is only available in cPanel & WHM 11.32. |
| Returns: | |
<data> <dkim_available> A boolean value that indicates whether Exim supports DKIM. A value of 1 indicates that the system's Exim supports DKIM.</dkim_available> <dkim> A boolean value that indicates whether DKIM is enabled for the authenticated domain. A value of 1 indicates that the account can use DKIM.</dkim> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Enable or disable DKIM for the authenticated account. This change applies to all of the domains associated with the account. This function's output will contain 1 or more strings after the boolean value in the 0th position. This API call is only available in cPanel & WHM 11.32. |
| Parameters: | |
| dkim (boolean) | |
| Enables or disables DKIM for the account. A value of 1 will enable DKIM. | |
| Returns: | |
<data> <result> An array that contains the function's result. [0] contains a boolean value that indicates success or failure. [i] contains strings that describe the success or failiure. </result> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Gets the email archiving configuration for the specified domain. This API call is available in cPanel & WHM 11.34. |
| Parameters: | |
| domain ((string) optional) | |
| The domain name for which you wish to get the email archiving configuration information. | |
| regex ((string) optional) | |
| A case-sensitive regular expression used to filter by domain. | |
| Returns: | |
<data> <archive_incoming> A boolean value indicating if incoming messages are archived. A value of '1' indicates incoming messages are archived where a value of '0' indicates that they are not. </archive_incoming> <archive_incoming_retain_days> A numerical value representing the number of days that incoming messages will be retained. A value of '0' indicates forever. No return value indicates that messages are not being archived. </archive_incoming_retain_days> <archive_mailman> A boolean value indicating if emails sent through mailing lists (mailman) will be archived. A value of '1' indicates that mailman messages will be archived, where a value of '0' indicates they are not. </archive_mailman> <archive_mailman_retain_days> A numerical value representing the number of days that mailman messages will be retained. A value of '0' indicates forever. No return value indicates that messages are not being archived. </archive_mailman_retain_days> <archive_outgoing> A boolean value indicating if outgoing messages are archived. A value of '1' indicates outgoing messages are being archived, where a value of '0' indicates that they are not. </archive_outgoing> <archive_outgoing_retain_days> A numerical value representing the number of days that outgoing messages are archived. A value of '0' indicates forever. No return value indicates that messages are not being archived. </archive_outgoing_retain_days> <disk_used> A value indicating the amount of disk space that is being used by the archived messages. </disk_used> <domain> The domain for which the archived messages information is being retrieved. </domain> <has_archive> A boolean value representing whether message archiving is enabled or disabled. A value of '1' indicates message archiving is enabled, while a value of '0' indicates it is disabled. </has_archive> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Sets the email archiving configuration for the specified domain. This API call is available in cPanel & WHM 11.34. |
| Parameters: | |
| domains (string) | |
| A comma separated list of domains whose configuration will be changed. | |
| (type) (string) | |
| An integer, or empty-string, value indicating the length of time to keep mail archives of the given type (e.g., incoming, outgoing, mailman). An empty string will disable the archive type and a value of '0' will set the type to archive indefinitely/forever. | |
| Returns: | |
<data> <domain> example1.com,example2.com,example3.com </domain> <type> incoming=44&outgoing=3& </type> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Displays the different types of email archiving that are available. This API call is available in cPanel & WHM 11.34. |
| Returns: | |
<data> <incoming> Incoming Message Archive </incoming> <mailman> Mailman Message Archive </mailman> <outgoing> Outgoing Message Archive </outgoing> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Gets the default email archiving configuration for the specified domain. This API call is available in cPanel & WHM 11.34. |
| Parameters: | |
| domain (string) | |
| The domain whose default configuration you are inquiring for. | |
| Returns: | |
<data> <direction>The archiving type whose information is being displayed. Incoming, mailman, or outgoing are the possible types. </direction> <enabled> A boolean value indicating whether the archive type is enabled or disabled. A value of '1' indicates that archiving for the type is enabled. A value of '0' indicates that archiving for the type is disabled. </enabled> <retention_period> A numerical value representing the length of time that the messages should be archived. The value '0' indicates forever, the value '32' indicates 1 month, the value '93' indicates 3 months, the value '366' indicates 1 year, the value '731' indicates 2 years, the value '1826' indicates 5 years, and the value '3651' indicates 10 years. </retention_period> </data> |
| API Version: | 2 - Click here for documentation |
|---|---|
| Description: | Sets the default email archiving configuration for any new domains created under the user account. This API call is available in cPanel & WHM 11.34. |
| Parameters: | |
| (type)* (string) | |
| An integer, or empty-string, value indicating the length of time to keep mail archives of the given type (e.g., incoming, outgoing, mailman). An empty string will disable the archive type and a value of '0' will set the type to archive indefinitely/forever. | |
| Returns: | |
<data> <direction>The message archiving type whose information is being displayed. Incoming, mailman, or outgoing are possible types. If no type is indicated, all types will be disabled. </direction> <enabled>A boolean value indicating whether the archiving type is enabled or disabled. A value of '1' indicates the archiving type should be enabled. A value of '0' indicates that archiving should be disabled.</enabled> <retention_period>A numerical value representing the length of time, in days, that messages should be retained. A value of -1 indicates that messages should be kept forever.</retention_period> </data> |