Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation



integrationblogcta.jpg

Email Module Documentation

Overview

This module allows you to access email account functions.

The functions within this module sometimes require a feature list. This list varies between functions. To view a list of the available feature sets on a cPanel server, see the Feature Manager interface in WHM.

Account functions

The following functions relate to email accounts.

Email::addpop

API Version: 2 — Read the documentation for this version.
Description: This function adds a new email account.
Parameters: domain (string)
  The domain for the new email account. (For example, example.com if the address is user@example.com.)
  email (string)
  The username for the new email account. (For example, user if the address is user@example.com.)
  password (string)
  The password for the new email account.
  quota (integer)
  A positive integer that defines the disk quota for the email account. A value of 0 indicates an unlimited quota.
Returns:
<data>
  <reason> A string value that is undefined if the address is added successfully, or a reason for failure if it was not.</reason>
  <result> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</result>
</data>

Email::delpop

API Version: 2 — Read the documentation for this version.
Description: This function deletes an email account.
Parameters: domain (string)
  The domain for the email account you wish to remove. (For example, example.com if the address is user@example.com.)
  email (string)
  The username for the email address you wish to remove. (For example, user if the address is user@example.com.)
Returns:
<data>
  <rawout> A string value that is undefined if the account is successfully removed or if the reason for failure is that the account does not exist. This value contains a message from the Whostmgr binary if the function could not remove the account.</rawout>
  <reason> A string value of OK if the account is successfully removed, or that contains a reason for failure if the account is not removed.</reason>
  <result> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</result>
</data>

Email::editquota

API Version: 2 — Read the documentation for this version.
Description: This function modifies an email account's quota.
Parameters: domain (string)
  The domain for the email account you wish to modify. (For example, example.com if the address is user@example.com.)
  email (string)
  The username for the email address you wish to modify. (For example, user if the address is user@example.com.)
  quota (integer)
  A positive integer that indicates the desired 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 that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</result>
</data>

Email::passwdpop

API Version: 2 — Read the documentation for this version.
Description: This function changes an email account's password.
Parameters: domain (string)
  The domain for the email address for which you wish to change the password. (For example, example.com if the address is user@example.com.)
  email (string)
  The username for the email address for which you wish to change the password. (For example, user if the address is user@example.com.)
  password (string)
  The desired password for the account.
Returns:
<data>
  <reason> A string value that is undefined if the password is changed successfully, or contains a reason for failure.</reason>
  <result> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</result>
</data>

Email::clearpopcache

API Version: 2 — Read the documentation for this version.
Description: This function rebuilds an email address's cache file.
Parameters: username (string)
  The username for the email account for which you wish to rebuild the cache file.
Returns:
<data>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</status>
</data>

Email::listpops

API Version: 2 — Read the documentation for this version.
Description: This function retrieves a list of email accounts associated with your cPanel account.
note Note: Email::listpopswithdisk is the preferred function to retrieve a list of email accounts.
Parameters: regex (Regular Expression (optional))
  The regular expression by which you wish to filter the results.
Returns:
<data>
  <email> A string value that contains an email address or returns Main Account if the email address is the main account. </email>
  <login> A string value that contains the login used to authenticate mail services.</login>
</data>

Email::listpopssingle

API Version: 2 — Read the documentation for this version.
Description: This function retrieves a list of email accounts and logins associated with your cPanel account. The list includes email addresses from the main domain, addon domains, and parked domains.
Parameters: regex (Regular Expression (optional))
  The regular expression by which you wish to filter the results.
Returns:
<data>
  <email> A string value that contains an email address or returns Main Account if the email address is the main account. </email>
  <login> A string value that contains the login used to authenticate mail services.</login>
</data>

Email::listpopswithimage

API Version: 2 — Read the documentation for this version.
Description: This function retrieves a list of email accounts and logins associated with your cPanel account. This list includes email addresses from the main domain, addon domains, and parked domains. This list also contains the account's username and an HTML link to the mainacct.jpg graphic, based on the account's style (skin).
Parameters: regex (Regular Expression (optional))
  The regular expression by which you wish to filter the results.
Returns:
<data>
  <email> A string value that contains an email address or returns Main Account if the email address is the main account. </email>
  <login> A string value that contains the login used to authenticate mail services.</login>
  <login> A string value that contains the HTML link to the mainacct.jpg graphic. (For example, <img src="/frontend/cpanel-skin/images/mainacct.jpg">.)</login>
</data>

Email::listpopswithdisk

API Version: 2 — Read the documentation for this version.
Description: This function lists email accounts that correspond to a particular domain. This function also lists quota and disk usage information.
Parameters: domain (string (optional))
  The domain for which you wish to view email accounts.
  nearquotaonly (boolean (optional))
  If you pass 1 to this parameter, you will only view accounts that use 95% or more of their allotted disk space.
  no_validate (boolean (optional))
  If you pass 1 to this parameter, the function only reads data from your .cpanel/email_accounts.yaml file. Enter 0 or do not use this parameter if you wish for the function to check the passwd file, quota files, etc. 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>
  <_diskquota> An integer value that contains the disk quota in bytes. </_diskquota>
  <_diskused> An integer value that contains the disk space used in bytes. </_diskused>
  <diskquota> An integer or string value that contains the disk quota in megabytes. This value is affected by the account's locale. (For example, 250 or unlimited.) </diskquota>
  <diskused> A floating point value that contains the disk space used in megabytes. (For example, 108.83.) </diskused>
  <diskusedpercent> An integer value that contains the percentage of disk space used. </diskusedpercent>
  <diskusedpercent20> An integer value that contains the percentage of disk space used. </diskusedpercent20>
  <domain> A string value that contains the domain name you queried. </domain>
  <email> A string value that contains the email address or returns Main Account if the email address is the main account. </email>
  <humandiskquota> A string value that contains the disk quota and the descriptor. (For example, 250 MB.) </humandiskquota>
  <humandiskused> A string value that contains the amount of disk space used and the descriptor. (For example, 109.39 MB or none.) </humandiskused>
  <login> A string value that contains the login used to authenticate mail services.</login>
  <mtime> An integer value that contains the file modification timestamp. </mtime>
  <txtdiskquota> An integer value that contains the disk quota in megabytes. </txtdiskquota>
  <user> A string value that contains the username that corresponds to the queried domain. </user>
</data>

Email::accountname

API Version: 2 — Read the documentation for this version.
Description: This function displays the account name or All Mail On Your Account. This function is useful if you wish to retrieve the account name in a webmail interface.
Parameters: account (string)
  Specifies the account name or email address. The function will return whichever of these values you do not specify.
  display (string)
  If present, and you do not specify an account, the function will return the string All Mail On Your Account.
Returns:
<data>
  <account> A string value that contains either the name of the account specified or All Mail On Your Account.</account>
</data>

Email::getdiskusage

API Version: 2 — Read the documentation for this version.
Description: This function retrieves information about a specified email account's disk usage.
Parameters: domain (string)
  The domain that corresponds to the email address for which you wish to view disk usage. (For example, example.com.)
  user (string)
  The username of the email address for which you wish to view disk usage. (For example, user if the email address is user@example.com.)
Returns:
<data>
  <diskused> A floating point decimal value of the disk space used in megabytes.</diskused>
  <domain> A string value that contains the domain section of the email address.</domain>
  <login> A string value that contains the username section of the email address.</login>
  <user> A string value that contains the username section of the email address.</user>
</data>

Email::listmaildomains

API Version: 2 — Read the documentation for this version.
Description: This function retrieves a list of the 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))
  Pass 1 to this variable to skip the main domain.
Returns:
<data>
  <domain> A string value that contains a mail domain associated with your cPanel account.</domain>
</data>

Email::has_delegated_mailman_lists

API Version: 2 — Read the documentation for this version.
Description: This function determines whether a specified account is a delegate on any mailing list.
Parameters: delegate (string)
  The email address of the webmail user for whom you wish to check delegated administrative rights. (For example, username@example.com.)
Returns:
<data>
<has_delegated_mailman_lists> This value indicates whether the specified address has administrative rights delegated to it. A value of 1 indicates that the address has administrative rights delegated to it.</has_delegated_mailman_lists>
</data>

Email::listlists

API Version: 2 — Read the documentation for this version.
Description: Lists mailing lists associated with a domain.
Parameters: domain (string (optional))
  The domain for which you wish to view a list of mailing lists.
  regex (regular expression (optional))
  Regular expressions allow you to filter results based on a set of criteria.
Returns:
<data>
  <desthost> A string value that contains the IP address of the domain for which you wish to view a list of mailing lists.</desthost>
  <diskused> A floating point value that contains the disk space used in megabytes.</diskused>
  <humandiskused> A string value that contains the amount of disk space used and the descriptor. (For example, 250 MB or none.)</humandiskused>
  <listadmin> A comma-separated list of list administrator email addresses.</listadmin>
  <accesstype> A string value that indicates level of access that users have to the mailing list. Possible values are:
private — This list has private archives, the administrator must approve subscriptions, and the list is not advertised on the mailman page.
public — This list has public archives, the subscriptions are open, or the list is advertised on the Mailman page.</accesstype>
  <subscribe_policy> A string value that indicates the level of control the administrator has over new subscribers.</subscribe_policy>
  <archive_private> A string value that indicates whether the mailing list archive are private.</archive_private>
  <advertised> A string value that indicates whether the mailing list is advertised in the Mailman lists directory.</advertised>
  <list> A string value that contains the name of the mailing list and the domain, separated by @. (For example, user@example.com.)</list>
  <listid> A string value that contains the name of the mailing list and the domain, separated by an underscore (_). (For example, user_example.com.)</listid>
</data>

Unroutable mail functions

The following functions relate to unroutable mail.

Email::setdefaultaddress

API Version: 2 — Read the documentation for this version.
Description: Configure a default (catchall) email address. The default address handles unroutable mail sent to a domain.
note Note: Irrelevant parameters are passed to the function, regardless of its configuration, and will be included in the rule.
Parameters:  
  fwdopt (string)
  This parameter defines how unroutable mail will be handled. The valid values for this option are:
fail — Bounces unroutable messages and returns a failure message to the sender.
fwd — Forwards unroutable messages to another email address.
blackhole — Sends undeliverable mail to /dev/null/ and does not generate a failure notice.
pipe — Pipes undeliverable mail to a program.
  domain (string)
  Specifies the domain to which you wish to apply the rule. The user must own this domain. If this parameter is not specified, cPanel will use the account's main domain.
  failmsgs (string (optional))
  Specifies the failure message that you wish to send if an incoming message bounces. The default value is No such person at this address. This parameter only takes effect if fwdopt=fail.
  fwdemail (string (optional))
  Specifies the email address to which mail received by the default address is forwarded. This parameter only takes effect if fwdopt=fwd. Enter the email address in standard format. (For example, user@example.com.)
  pipefwd (string (optional))
  Specifies the program to which messages received by the default address are piped. cPanel appends the user's home directory to the beginning of the value.
Returns:
<data>
  <dest> A string value that contains the destination of messages received by the catchall address. (For example, :fail:, No such person at this address, forwardto@example.com, | /home/$user/PROGAM, :blackhole:)</dest>
  <domain> A string value that contains the domain.</domain>
</data>

Email::checkmaindiscard

API Version: 2 — Read the documentation for this version.
Description: Checks how the main email account for a domain handles undeliverable mail.
Returns:
<data>
  <status> A boolean value that describes how unroutable messages are handled. A value of 1 indicates that unroutable emails are deleted. A value of 0 indicates that messages are forwarded to another address or piped to a program.</status>
</data>

Email::listdefaultaddresses

API Version: 2 — Read the documentation for this version.
Description: Retrieves the default address and the action taken when the default address receives unroutable messages.
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. (For example, :fail: failure message or :blackhole:.)</defaultaddress>
  <domain> A string value that contains the domain that corresponds to the default address. (For example, example.com.)</domain>
</data>

Email::listaliasbackups

API Version: 2 — Read the documentation for this version.
Description: Retrieves 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. (For example, example.com.)</domain>
</data>

Forwarder functions

The following functions relate to forwarders.

Email::addforward

API Version: 2 — Read the documentation for this version.
Description: Creates an email forwarder for the specified address. You can forward mail to a new address or pipe mail to a program.
Parameters: domain (string)
  The domain for which you wish to add a forwarder. (For example, example.com.)
  email (string )
  The username of the email address for which you wish to add a forwarder. (For example, user if the address is user@example.com.)
  fwdopt (string)
  This parameter defines which type of forwarder you wish to use. The valid values for this option are:
pipe — Forwards to a program.
fwd — Forwards to another non-system email address.
system — Forwards to an account on the system.
blackhole — Bounces emails with the blackhole functionality.
fail — Bounces emails with the fail functionality.
  fwdemail (string (optional))
  The email address to which you wish to forward mail. Use this parameter when fwdopt=fwd.
  fwdsystem (string (optional))
  The system account to which you wish to forward email. Use this parameter when fwdopt=system.
  failmsgs (string (optional))
  Use this parameter to define the correct failure message. Use this parameter when fwdopt=fail.
  pipefwd (string (optional))
  The path to the program to which you wish to pipe email. Use this parameter when fwdopt=pipe.
Returns:
<data>
  <domain> The domain that corresponds to the forwarder.</domain>
  <email> The email address that acts as the forwarder.</email>
  <fwdemail> The email address that receives forwarded mail.</fwdemail>
</data>

Email::listforwards

API Version: 2 — Read the documentation for this version.
Description: List forwarders associated with a specific domain.
Parameters: domain (string (optional))
  The domain name for which you wish to review forwarders.
  regex (regular expression (optional))
  Regular expressions allow you to filter results based on a set of criteria.
Returns:
<data>
  <dest> A string value that contains the address from which mail forwards in plain text. (For example, forwardfrom@example.com.)</dest>
  <forward> A string value that contains the address to which mail forwards in plain text. (For example, forwardto@example.com.)</forward>
  <html_dest> A string value that contains the address from which mail forwards in an HTML-safe format. (For example, forwardfrom@example.com.)</html_dest>
  <html_forward> A string value that contains the address to which mail forwards in an HTML-safe format. (For example, forwardto@example.com.)</html_forward>
  <uri_dest> A string value that contains the address from which mail forwards in a URI encoded format. (For example, forwardfrom%40example.com.)</uri_dest>
  <uri_forward> A string value that contains the address to which mail forwards in a URI encoded format. (For example, forwardto%40example.com.) </uri_forward>
</data>

Email::listdomainforwards

API Version: 2 — Read the documentation for this version.
Description: Retrieves the destination to which a domain forwarder forwards email.
Parameters: domain (string)
  The domain that corresponds to the forwarder for which you wish to view the destination.
Returns:
<data>
  <dest> A string value that contains the domain that receives forwarded mail.</dest>
  <forward> A string value that contains the local domain responsible for forwarding messages.</forward>
</data>

Filter functions

The following functions relate to email filters.

Email::storefilter

API Version: 2 — Read the documentation for this version.
Description: Creates a new email filter. It is possible to specify multiple values for the same parameter when you use this function.
  • To specify multiple values to the same parameters, you must append a number to certain parameters, indicated by an asterisk below. Append a 1 to the parameter names for the first set of conditions, a 2 to the second set, etc.
  • You may have up to 4096 conditions.
  • Unless you wish to specify a second set of actions, you only need incremental versions of the part, match, val, and opt parameters.
  • To specify a second set of actions, you must create incremental versions of action and dest.
  • For example, if you wished to call the storefilter function with a single set of actions but two sets of conditions, you might define part1, match1, val1, opt1, action1, and dest1 for your first incremental set. You would then define part2, match2, val2, and opt2 to create the second set of conditions.
Parameters: account (string)
  To configure a user-level filter, enter the email address to which you wish to apply the rule. If you wish to set up an account-level filter, do not enter a value for this parameter. If you wish to configure a filter for the default email account, enter the username that corresponds to the catch-all address to which the new rule applies.
  action* (string)
  Specifies the action that the filter takes. Acceptable values include deliver, fail, finish, save, and pipe. Specify an incremental version of this parameter only if you wish the filter to take more than one action.
  dest* (string (optional))
  Specifies the destination of mail that the filter receives, if one is required. (For example, /dev/null.) This parameter corresponds to the action parameter. Specify an incremental version of this parameter only if you wish the filter to take more than one action.
  filtername (string)
  Specifies the name you wish to give to the new filter.
  match* (string)
  Specifies 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 four 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 if you do not specify a value.
  part* (string)
  The section of the email to which you wish 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 three options require you to enable SpamAssassin.) You may also use the values error_message or not delivered, which do not require the match parameter.
  val* (string)
  Specifies the value against which you wish to match. (For example, free or prescriptions.)
Returns:
<data>
  <ok> A boolean value that indicates success or failure. The function returns a 1 if it completed successfully.</ok>
  <account> A string value that contains the account name that corresponds to the filter.</account>
  <error> A boolean value that indicates success, or a string value that contains an error message. The function returns a 0 if it completed successfully.</error>
  <result> A string value that returns Filter Saved if the function completed successfully. If the function did not complete successfully, this string value contains an error message.</result>
</data>

Email::deletefilter

API Version: 2 — Read the documentation for this version.
Description: Deletes an email filter.
Parameters: account (string (optional))
  Specifies an email address or account username that corresponds to the user-level filter you wish to remove. When you specify an email address, the function effects user-level filters associated with the account. When you specify a username, the function will remove user-level filters associated with the account's default email address. If you do not specify a value for this parameter, the function will remove an account-level filter.
  filtername (string)
  Specifies the name of the filter you wish to delete.
Returns:
<data>
  <deleted> A boolean value that indicates success or failure. The function returns a 1 if the filter was removed, or a 0 if it was not.</deleted>
  <filtername> A string value that contains the name of the filter you attempted to remove.</filtername>
</data>

Email::tracefilter

API Version: 2 — Read the documentation for this version.
Description: Tests the action of account-level mail filters. You can only test filters for your 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 the $home/filters directory. If you do not specify this parameter you will test your main domain's filters 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 a reason for failure, the name of the file you examined, and the destination of the filter.</trace>
</data>

Email::filterlist

API Version: 2 — Read the documentation for this version.
Description: Retrieves a list of email filters.
Parameters: account (string (optional))
  Specifies the email address or account username. If you specify an email address, the function will retrieve user-level filters associated with the account. If you specify a username, the function will 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>
  <actions>
    <action> A string value that contains a description of the action the filter takes.</action>
    <dest> A string value that contains the destination of filtered mail. (For example, /dev/null.)</dest>
  </actions>
  <enabled> A boolean value that indicates whether the filter is enabled.</enabled>
  <filtername> A string value that contains the filter's name.</filtername>
  <rules>
    <match> A string value that contains the match type. (For example, is or contains.)</match>
    <opt> A string value that contains or or and as a connector for the next rule in the list.</opt>
    <part> A string value that contains the section of the email covered by the filter. (For example, $header_from:.)</part>
    <val> A string value that contains the phrase for which the filter searches.</val>
  </rules>
    <unescaped> A boolean value.</unescaped>

</data>

Email::loadfilter

API Version: 2 — Read the documentation for this version.
Description: Retrieves the rules and actions associated with an email filter.
Parameters: account (string (optional))
  Specifies the email address or account username. If you specify an email address, the function will retrieve user-level filters associated with the account. If you specify a username, the function will 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.
  filtername (string)
  Specifies the name of the filter you wish to review.
Returns:
<data>
  <actions>
    <action> A string value that contains a description of the action the filter takes.</action>
    <dest> A string value that contains the destination of filtered mail. (For example, /dev/null.)</dest>
    <number> An integer value that contains the order of the rule in the list. The first rule returns 1 as the value. </number>
  </actions>
  <filtername> A string value that contains the filter's name.</filtername>
  <rules>
    <match> A string value that contains the match type. (For example, is or contains.)</match>
    <number> An integer value that contains the order of the rule in the list. The first rule returns 1 as the value. </number>
    <opt> A string value that contains or or and as a connector for the next rule in the list.</opt>
    <part> A string value that contains the section of the email covered by the filter. (For example, $header_from:.)</part>
    <val> A string value that contains the phrase for which the filter searches.</val>
  </rules>

</data>

Email::filtername

API Version: 2 — Read the documentation for this version.
Description: Counts the number of email filters and returns a default suggested rule name in a Rule [1 + count] format. (For example, if user@example.com used three user-level filters, this function would return Rule 4.)
Parameters: account (string (optional))
  Specifies the email address associated with the account for which you wish to return a result. If you do not specify a value for this parameter, the function will return a value based on account-level filters. If you pass a username to this parameter, the function will scan the account's filters for the default email account.
  filtername (string (optional))
  Specifies a fallback in the case that the function cannot find any relevant filter files. Under certain conditions, the function will create empty versions of missing files, which will result in erroneous output when the function is run a second time.
Returns:
<data>
  <filtername> A string value that contains the suggested rule name. The function counts the number of existing filters and adds one in order to calculate this value. </filtername>
</data>

Email::listfilterbackups

API Version: 2 — Read the documentation for this version.
Description: Retrieves a list of domains that use domain-level filters.
Returns:
<data>
  <domain> A string value that contains the domain name that corresponds to a file in /etc/vfilters. </domain>
</data>

Email::listfilters

API Version: 2 — Read the documentation for this version.
Description: Lists 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 the filter takes. (For example, Discard.) </nicedest>
  <filter> A string value that contains information about the filter. </filter>
  <dest> A string value that contains the destination for filtered mail. (For example, /dev/null.)</dest>
</data>

Autoresponder functions

The following functions relate to autoresponders.

Email::listautoresponders

API Version: 2 — Read the documentation for this version.
Description: Retrieves a list of auto responders associated with the specified domain.
Parameters: domain (string (optional))
  The domain for which you wish to view auto responders.
  regex (Regular Expression (optional))
  Regular expressions allow you to filter results based on a set of criteria.
Returns:
<data>
  <email> A string value that contains the email address for which the auto responder is configured.</email>
  <subject> A string value that contains the subject of the email sent in the auto response. </subject>
</data>

Email::fetchautoresponder

API Version: 2 — Read the documentation for this version.
Description: Retrieves information about an auto responder that corresponds to a specified email address.
Parameters: email (string)
  The email address that corresponds to the auto responder you wish to review.
Returns:
<data>
  <body> A string value that contains the message in the body portion of the email.</body>
  <charset> A string value that contains the name of the character set that the auto responder uses.</charset>
  <from> A string value that contains the from portion of the email.</from>
  <interval> The amount of time, in hours, that the auto responder will wait between responses to the same email address. </interval>
  <ishtml> A boolean value that indicates whether the email is HTML-forwarded. A value of 1 indicates that the email is HTML-forwarded. </ishtml>
  <start> The start time. This value will return undefined if the start time was immediately when you created the filter. </start>
  <stop> The stop time. This value will return undefined if the stop time was never when you created the filter. </stop>
  <subject> A string value that contains the subject portion of the email.</subject>
</data>

Archiving functions

The following functions relate to email archiving.

Email::set_archiving_configuration

API Version: 2 — Read the documentation for this version.
Description: Sets the email archiving configuration for the specified domain. This API call is available as of cPanel & WHM 11.34.
Parameters: domains (string)
  A comma separated list of domains for which you wish to change the configuration.
  (type) (string)
  An integer, or empty-string, value that indicates the length of time to keep mail archives of the given type. (For example, incoming, outgoing, or mailman.) An empty string will disable the archive type. A value of 0 sets the specified type to archive indefinitely.
Returns:
<data>
  <domain> The list of specified domains for which you attempted to change the configuration. </domain>
  <type> A list of the specified types of mail archives, and the length of time to keep each type. </type>
</data>

Email::set_archiving_default_configuration

API Version: 2 — Read the documentation for this version.
Description: Sets the default email archiving configuration for any new domains created under the user account. This API call is available as of cPanel & WHM 11.34.
Parameters:  
  (type)* (string)
  An integer, or empty-string, value that indicates the length of time to keep mail archives of the given type. (For example, incoming, outgoing, or mailman.) An empty string will disable the archive type. A value of 0 sets the specified type to archive indefinitely.
Returns:
<data>
  <direction> A string value that indicates the message archiving type for which information is displayed. If no type is indicated, all types will be disabled. </direction>
  <enabled>A boolean value that indicates whether the archiving type is enabled or disabled. A value of 1 indicates that it is enabled. A value of 0 indicates that it is disabled.</enabled>
<retention_period>A numerical value that represents the length of time, in days, that messages are retained. A value of -1 indicates that messages are kept forever.</retention_period>
<status> A boolean value that indicates success or failure. </status>
<retention_period> A string value that contains a status message. </retention_period>
</data>

Email::get_archiving_configuration

API Version: 2 — Read the documentation for this version.
Description: Lists the email archiving configuration for the specified domain. This API call is available as of cPanel & WHM 11.34.
Parameters: domain ((string) optional)
  The domain name for which you wish to view email archiving configuration information.
  regex ((string) optional)
  A case-sensitive regular expression used to filter by domain.
Returns:
<data>
  <archive_incoming> A boolean value that indicates whether incoming messages are archived. A value of 1 indicates that incoming messages are archived. A value of 0 indicates that they are not. </archive_incoming>
  <archive_incoming_retain_days> A numerical value that represents the number of days that incoming messages will be retained. A value of 0 indicates forever. No return value indicates that messages are not archived. </archive_incoming_retain_days>
  <archive_mailman> A boolean value that indicates whether emails sent through mailing lists are archived. A value of 1 indicates that mailman messages are archived. A value of 0 indicates they are not. </archive_mailman>
  <archive_mailman_retain_days> A numerical value that represents the number of days that mailman messages will be retained. A value of 0 indicates forever. No return value indicates that messages are not archived. </archive_mailman_retain_days>
  <archive_outgoing> A boolean value that indicates whether outgoing messages are archived. A value of 1 indicates outgoing messages are archived. A value of 0 indicates that they are not. </archive_outgoing>
  <archive_outgoing_retain_days> A numerical value that represents the number of days that outgoing messages are archived. A value of 0 indicates forever. No return value indicates that messages are not archived. </archive_outgoing_retain_days>
  <disk_used> A value that indicates the amount of disk space that is used by the archived messages. </disk_used>
  <domain> The domain that corresponds to the archived messages information. </domain>
  <has_archive> A boolean value that represents whether message archiving is enabled or disabled. A value of 1 indicates message archiving is enabled. A value of 0 indicates it is disabled. </has_archive>
</data>

Email::get_archiving_default_configuration

API Version: 2 — Read the documentation for this version.
Description: Lists the default email archiving configuration for the specified domain. This API call is available as of cPanel & WHM 11.34.
Parameters: domain (string)
  The domain for which you wish to view the default configuration.
Returns:
<data>
  <direction>The archiving type that corresponds to the displayed information. </direction>
  <enabled> A boolean value that indicates 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 that represents the length of time, in days, for which the messages are archived. The value 0 indicates forever, the value 32 indicates one month, the value 93 indicates three months, the value 366 indicates one year, the value 731 indicates two years, the value 1826 indicates five years, and the value 3651 indicates 10 years. </retention_period>
</data>

Email::get_archiving_types

API Version: 2 — Read the documentation for this version.
Description: Displays the different types of email archiving that are available. This API call is available as of cPanel & WHM 11.34.
Returns:
<data>
  <incoming> Incoming Message Archive </incoming>
  <mailman> Mailman Message Archive </mailman>
<outgoing> Outgoing Message Archive </outgoing>
</data>

Mail directory functions

The following functions relate to mail directories.

Email::getabsbrowsedir

API Version: 2 — Read the documentation for this version.
Description: Retrieves 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 that corresponds to the directory for which you wish to find the path. (For example, user@example.com.)
  dir (string (optional))
  The mail folder that you wish to query for its full path. If you do not specify this parameter, it will default to the value mail.
Returns:
<data>
  <absdir> A string value that contains the full path to the requested directory.</absdir>
</data>

Email::browseboxes

API Version: 2 — Read the documentation for this version.
Description: Retrieves 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. If you specify default or mail, the function will list information for all of your domain's mail directories. If you specify a domain (for example, mail.example.com or example.com) the function displays account directories related to the domain.
  showdotfiles (boolean (optional))
  A boolean variable that allows you to specify whether you wish to view hidden directories and files. (For example, hidden-dir.)
Returns:
<data>
  <depth> An integer value that represents how many directories deep inside the home directory the item in the list resides. </depth>
  <file> A string value that contains the base name for the file or directory. (For example, example.com.) </file>
  <fullpath> A string value that contains the item in the list.</fullpath>
  <isleaf> A boolean value that specifies whether the item in the list is a file. A value of 1 indicates that it is a file. A value of 0 indicates that it is not a file.</isleaf>
  <ismailbox> A boolean value that specifies whether the item in the list is a mailbox. A value of 1 indicates that it is a mailbox. A value of 0 indicates that it is not a mailbox.</ismailbox>
  <mtime> An integer value that contains the last modification time epochal. (For example, 1258338752.)</mtime>
  <path> A string value that contains the full path to the file or directory.</path>
  <relpath> A string value that contains the relative path to the mail directory including the initial slash. (For example, /example.com.)</relpath>
  <type> A string value that contains dir or file. A value of dir indicates that the item in the list is a directory. A value of file indicates that the item in the list is a file. Generally, this value will always be dir.</type>
</data>

Mail exchanger (MX) functions

The following functions relate to mail exchangers.

Email::addmx

API Version: 2 — Read the documentation for this version.
Description: Adds an MX record. You must have access to the changemx feature in order to use this function.
Parameters: domain (string)
  The domain to which you wish to add the mail exchanger.
  exchange (string)
  The name of the mail exchanger you wish to add. (For example, mail.example.com.) You can also use the parameter names newmx or exchanger to set this parameter.
  oldexchange (string)
  The name of the exchanger you wish to replace. You can also use the parameter names oldmx or oldexchanger to set this parameter.
  oldpreference (string)
  The priority value of the old exchanger. If two entries for oldexchange match, the function will decide which value to use. You can also use the parameter name oldpriority to set this parameter.
  preference (integer)
  The priority of the mail exchanger. Lower values translate to higher priorities, with 0 as the highest priority exchanger. Traditionally, increments of 5 or 10 are used. You can also use the parameter name priority to set this parameter.
  alwaysaccept (string (optional))
  This value describes whether the local machine should accept mail for this domain. This parameter accepts the following values:
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>
  <checkmx>
    <changed> A boolean value that indicates whether a change has occurred. A value of 1 indicates that a change has occurred. A value of 0 indicates that no change occurred.</changed>
    <detected> This value is the same as mxcheck.</detected>
    <isprimary> A boolean value that indicates whether the mail exchanger is the primary (local) mail exchanger. A value of 1 indicates that it is the primary mail exchanger. A value of 0 indicates that it is not. </isprimary>
    <issecondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </issecondary>
    <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
    <mxcheck> A string value that contains the type of mail exchanger you have added. (For example, local, remote, secondary, or auto.) </mxcheck>
    <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
    <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
  </checkmx>
  <warnings> A string value that contains any warnings.</warnings>
  <results> A string value that contains a success message or a reason for failure. (For example, Bind reloading on tom using rndc zone: [domain] if successful.)</results>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</status>
  <statusmsg> A string that contains a success message or a reason for failure.</statusmsg>
</data>

Email::setmxcheck

API Version: 2 — Read the documentation for this version.
Description: Sets a specified domain's mail exchanger to the local, remote, secondary, or auto settings. You must have access to the changemx feature in order to use this function.
note Notes:
  • If you set the value to auto, cPanel will determine the appropriate role for the mail exchanger.
  • This function only affects the cPanel configuration. You will need to configure the MX's DNS entry elsewhere.
  • Internally, this call functions as an alias to Email::setalwaysaccept. However, this call is parsed as a unique call when used in a hook or custom event handler.
Parameters: domain (string)
  The domain that corresponds to the mail exchanger you wish to set.
  mxcheck (string)
  The status of the mail exchanger as it corresponds to cPanel's configuration. This parameter accepts the following values:
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>
  <checkmx>
    <changed> A boolean value that indicates whether a change has occurred. A value of 1 indicates that a change has occurred. A value of 0 indicates that no change occurred.</changed>
    <detected> A string value that contains the previous mxcheck value.</detected>
    <isprimary> A boolean value that indicates whether the mail exchanger is the primary (local) mail exchanger. A value of 1 indicates that it is the primary mail exchanger. A value of 0 indicates that it is not. </isprimary>
    <issecondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </issecondary>
    <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
    <mxcheck> A string value that contains the type of mail exchanger you specified in the input parameters. (For example, local, remote, secondary, or auto.) </mxcheck>
    <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
    <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
    <warnings> A string value that contains any warnings.</warnings>
  </checkmx>
  <detected> A string value that contains the input value specified in the input parameters if the function ran successfully.</detected>
  <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
  <mxcheck> A string value that contains the type of mail exchanger you specified in the input parameters. (For example, local, remote, secondary, or auto.) </mxcheck>
  <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
  <results> A string value that contains a success message or a reason for failure. (For example, Bind reloading on tom using rndc zone: [domain] if successful.)</results>
  <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</status>
  <statusmsg> A string that contains a success message or a reason for failure.</statusmsg>
</data>

Email::setalwaysaccept

API Version: 2 — Read the documentation for this version.
Description: Sets 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. You must have access to the changemx feature in order to use this function.
note Note: This function only affects the cPanel configuration. You will need to configure the MX's DNS entry elsewhere.
Parameters: domain (string)
  The domain that corresponds to the mail exchanger you wish to set.
  mxcheck (string)
  The status of the mail exchanger as it corresponds to cPanel's configuration. This parameter accepts the following values:
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.
  user (string)
  The cPanel account username that corresponds to the domain for which you wish to set a mail exchanger.
Returns:
<data>
  <checkmx>
    <changed> A boolean value that indicates whether a change has occurred. A value of 1 indicates that a change has occurred. A value of 0 indicates that no change occurred.</changed>
    <detected> A string value that contains the previous mxcheck value.</detected>
    <isprimary> A boolean value that indicates whether the mail exchanger is the primary (local) mail exchanger. A value of 1 indicates that it is the primary mail exchanger. A value of 0 indicates that it is not. </isprimary>
    <issecondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </issecondary>
    <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
    <mxcheck> A string value that contains the type of mail exchanger you specified in the input parameters. (For example, local, remote, secondary, or auto.) </mxcheck>
    <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
    <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
  </checkmx>
  <detected> A string value that contains the input value specified in the input parameters if the function ran successfully.</detected>
  <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
  <mxcheck> A string value that contains the type of mail exchanger you specified in the input parameters. (For example, local, remote, secondary, or auto.) </mxcheck>
  <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
  <results> A string value that contains a success message or a reason for failure. (For example, Bind reloading on tom using rndc zone: [domain] if successful.)</results>
  <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</status>
  <statusmsg> A string that contains a success message or a reason for failure.</statusmsg>
</data>

Email::delmx

API Version: 2 — Read the documentation for this version.
Description: Deletes an MX record. You must have access to the changemx feature in order to use this function.
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. (For example, mail.example.com.)
  preference (integer)
  The priority of the mail exchanger. A value of 0 indicates the highest priority exchanger. Generally, increments of 5 or 10 are used.
Returns:  
 
<data>
  <checkmx>
    <changed> A boolean value that indicates whether a change has occurred. A value of 1 indicates that a change has occurred. A value of 0 indicates that no change occurred.</changed>
    <detected> A string value that contains the previous mxcheck value.</detected>
    <isprimary> A boolean value that indicates whether the mail exchanger is the primary (local) mail exchanger. A value of 1 indicates that it is the primary mail exchanger. A value of 0 indicates that it is not. </isprimary>
    <issecondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </issecondary>
    <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
    <mxcheck> A string value that contains the type of mail exchanger you specified in the input parameters. (For example, local, remote, secondary, or auto.) </mxcheck>
    <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
    <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
  </checkmx>
  <results> A string value that contains a success message or a reason for failure. (For example, Bind reloading on user using rndc zone: [domain] if successful.)</results>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</status>
  <statusmsg> A string that contains a success message or a reason for failure.</statusmsg>
</data>

Email::changemx

API Version: 2 — Read the documentation for this version.
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 that corresponds to the MX record you wish to change.
  exchange (string)
  The name of 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>
  <checkmx>
    <changed> A boolean value that indicates whether a change has occurred. A value of 1 indicates that a change has occurred. A value of 0 indicates that no change occurred.</changed>
    <detected> A string value that contains the previous mxcheck value.</detected>
    <isprimary> A boolean value that indicates whether the mail exchanger is the primary (local) mail exchanger. A value of 1 indicates that it is the primary mail exchanger. A value of 0 indicates that it is not. </isprimary>
    <issecondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </issecondary>
    <local> A boolean value that indicates whether the mail exchanger is the local mail exchanger. A value of 1 indicates that it is the local mail exchanger. A value of 0 indicates that it is not. </local>
    <mxcheck> A string value that contains the type of mail exchanger you specified in the input parameters. (For example, local, remote, secondary, or auto.) </mxcheck>
    <remote> A boolean value that indicates whether the mail exchanger is a remote mail exchanger. A value of 1 indicates that it is a remote mail exchanger. A value of 0 indicates that it is not. </remote>
    <secondary> A boolean value that indicates whether the mail exchanger is a secondary mail exchanger. A value of 1 indicates that it is a secondary mail exchanger. A value of 0 indicates that it is not. </secondary>
  </checkmx>
  <results> A string value that contains a success message or a reason for failure. (For example, Bind reloading on user using rndc zone: [domain] if successful.)</results>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure.</status>
  <statusmsg> A string that contains a success message or a reason for failure.</statusmsg>
</data>

Email::getalwaysaccept

API Version: 2 — Read the documentation for this version.
Description: Checks whether a domain uses the local server as a mail exchanger in the cPanel configuration. You must have access to the changemx feature in order to use this function.
PICK Remember: This function checks the cPanel configuration, not the DNS records.
Parameters: domain (string (optional))
  The domain you wish to examine. If you do not specify this value, the function will return output for each domain you own.
Returns:
<data>
  <alwaysaccept> A boolean value that indicates whether the domain accepts all local mail. A value of 0 indicates that the domain is not set to accept mail locally. A value of 1 indicates that the domain accepts mail locally.</alwaysaccept>
  <domain> A string value that contains the domain that corresponds to the data.</domain>
  <mxcheck> A string value that always returns auto.</mxcheck>
</data>

Email::listmxs

Read the documentation for this version.API Version: 2 — Read the documentation for this version.
Description: Lists all mail exchangers associated with a domain. You must have access to the changemx feature in order to use this function.
Parameters: domain (string)
  The domain for which you wish to view mail exchangers.
Returns:  
 
<data>
  <alwaysaccept> A boolean value that describes whether the mail exchanger always accepts local mail. A value of 1 indicates that it always accepts local mail. A value of 0 indicates that it does not. </alwaysaccept>
  <detected> A string value that describes whether cPanel regards the mail exchanger as local, remote, secondary, or auto. </detected>
  <domain> The domain to which the mail exchanger belongs. (For example, example.com.) </domain>
  <entries>
    <domain> The domain to which the mail exchanger belongs. (For example, example.com.) </domain>
    <entrycount> An integer value that contains the mail exchanger's priority order. A value of 1 indicates the highest priority, a value of 2 indicates the second highest priority, etc. </entrycount>
    <mx> A string value that contains the name of the mail exchanger. (For example, mail.example.com.) </mx>
    <priority> An integer value that contains the priority of the mail exchanger. A value of 0 indicates the highest priority exchanger. </priority>
    <row> A string value that contains the mail exchanger's entry count. (For example, odd or even.) </row>
</entries>
  <local> A boolean value that indicates whether the mail exchanger is a local mail exchanger. A value of 1 indicates that the mail exchanger is local to the server. A value of 0 indicates that it is not. </local>
  <mx> A string value that contains the name of the mail exchanger. (For example, mail.example.com.) </mx>
  <mxcheck> A string value that contains how cPanel regards the mail exchanger. (For example, local, remote, secondary, or auto.) </mxcheck>
  <remote> A boolean value that indicates whether the mail exchanger is a remote exchanger. A value of 1 indicates that the mail exchanger is remote. A value of 0 indicates that it is not. </remote>
  <secondary> A boolean value that indicates whether the mail exchanger is a secondary exchanger. A value of 1 indicates that the mail exchanger is secondary. A value of 0 indicates that it is not. </secondary>
  <status> A boolean value that indicates success or failure. A value of 1 indicates success. A value of 0 indicates failure. </status>
  <statusmsg> A string value that contains a status message. (For example, Fetched MX List.) </statusmsg>
</data>

DKIM functions

The following functions relate to DKIM.

Email::get_email_signing

API Version: 2 — Read the documentation for this version.
Description: Indicates whether Exim supports DKIM whether DKIM is enabled for the authenticated account. This API call is only available as of 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>

Email::set_email_signing

API Version: 2 — Read the documentation for this version.
Description: Enables or disables DKIM for the authenticated account. This change applies to all of the domains associated with the account. This function's output will contain one or more strings after the boolean value in the 0th position. This API call is available as of cPanel & WHM 11.32.
Parameters: dkim (boolean)
  Enables or disables DKIM for the account. A value of 1, y, yes, or on will enable DKIM. A value of 0, n, no, or off will disable 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>

Misc. email functions

You can also perform the following Email function.

Email::fetchcharmaps

API Version: 2 — Read the documentation for this version.
Description: Retrieves a list of character encodings that cPanel supports.
Returns:
<data>
  <map> A string value that contains an acceptable character encoding.</map>
</data>

Topic revision: r7 - 19 Sep 2013 - 17:21:32 - Main.LaurenceSimon