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

This module allows you to access email account functions.

The functions within this module may or may not be governed by a feature list. The required feature list may vary from function to function, to review a total list of the available features sets on a cPanel server, please see "Feature Manager" in WHM.

Email::checkfastmail

API Version: 1 - Click here for documentation
Syntax: Email::checkfastmail( pipe_name )
Description: Check to see if a script that receives forwarded mail should be preceded by a hashbang or a pipe. This will set the boolean cPvariables "pipefwd_needs_hashbang" and "pipefwd_needs_fixup" if either of these are needed in front of the pipe.
Parameters:  
  pipe_name (string)
  The piped program you wish to check.
Returns:  
 
This function does not produce any output.

Email::addautoresponder

API Version: 1 - Click here for documentation
Syntax: Email::addautoresponder( email, from, subject, body, domain, html, charset, interval, start, stop )
Description: Add an auto responder to a specified email account. This function requires access to the 'auto responders' feature. This function is not available in demo mode.
Parameters:  
  email (string)
  The email account for which to configure the auto responder (e.g., user if the email address were user@example.com).
  from (string)
  The person's name that should appear in the From: field.
  subject (string)
  The subject that will appear in the Subject field of the auto responder.
  body (string)
  The contents of the Body section of the auto responder.
  domain (string)
  The domain name corresponding to the email address for which to configure the auto responder (e.g., example.com).
  html (boolean)
  Passing 1 to this parameter causes the function to insert an HTML content type declaration at the top of the body.
  charset (string (optional))
  The character set to use. This value defaults to us-ascii.
  interval (integer)
  The amount of time, in hours, that the autoresponder will wait before sending another response to the same email account.
  start (integer)
  The Unix time at which the autoresponder will be enabled.
  stop (integer)
  The Unix time at which the autoresponder will be disabled.
Returns:  
 
This function does not produce any output.

Email::addspambox

API Version: 1 - Click here for documentation
Syntax: Email::addspambox( )
Description: Enable the SpamAssassin Spam Box for an account.
Returns:  
 
This function does not produce any output.

Email::addlist

API Version: 1 - Click here for documentation
Syntax: Email::addlist( list, password, domain )
Description: Create a Mailman mailing list.
Parameters:  
  list (string)
  The name of the list.
  password (string)
  The password for the mailing list.
  domain (string)
  The domain on which to add the mailing list.
Returns:  
 
This function does not generate any output.

Email::addmx

API Version: 1 - Click here for documentation
Syntax: Email::addmx( domain, exchange, preference, alwaysaccept )
Description: Add an MX entry.
Parameters:  
  domain (string)
  The domain on which to add the mail exchanger.
  exchange (string)
  The name of the new mail exchanger (e.g., mail.example.com).
  preference (integer)
  The mail exchanger's priority. Remember: Lower numeric values indicate higher priorities, with 0 being the highest priority exchanger. Traditionally, increments of 5 or 10 are used.
  alwaysaccept (boolean (optional))
  Whether or not the mail exchanger should accept email for the specified domain.
Returns:  
 
This function does not produce any output.

Email::addfilter

API Version: 1 - Click here for documentation
Syntax: Email::addfilter( match value, method, msgpart, dest )
Description: Add an account-wide email filter.
Parameters:  
  match value (string)
  The text or value for which to check.
  method (string)
  The type of matching to use. The following values are accepted for numeric operations: is above, is not above, is below, is not below, equals. The following values are accepted for string operations: contains or begins.
  msgpart (string)
  The section of the email to check. Valid values include header_from, header_subject, header_to, reply_address, message_body, message_headers, h_to, h_cc, h_bcc, not delivered, error_message, h_X-Spam-Status, h_X-Spam-Score, and h_X-Spam-Bar.
  dest (string)
  The destination for filtered email. This value can be another email address, Discard, or a pipe to a shell application.
Returns:  
 
This function does not produce any output.

Email::addpop

API Version: 1 - Click here for documentation
Syntax: Email::addpop( email, password, quota, domain )
Description: Create an email account. This is the API1 version of the 'addpop' call. We recommend using the API2 version.
Parameters:  
  email (string)
  The username section of the email address. This is the part of the email address before the @ sign.
  password (string)
  The password for the new email account.
  quota (integer)
  A positive integer that indicates the amount of disk space the new email account is able to use. Entering 0 gives the account an unlimited disk quota.
  domain (string)
  The domain that will host the new email account (e.g., example.com).
Returns:  
 
The output of this function will contain the new email address (e.g., user@example.com).

Email::addspam

API Version: 1 - Click here for documentation
Syntax: Email::addspam( )
Description: Enable SpamAssassin for an account.
Returns:  
 
This function does not produce any output.

Email::addspamfilter

API Version: 1 - Click here for documentation
Syntax: Email::addspamfilter( required_score )
Description: Adjust the spam score required for email to be considered spam by SpamAssassin.
Parameters:  
  required_score (integer (optional))
  An integer value that indicates the new spam score to use. If this parameter is not specified, it will reset to the default value.
Returns:  
 
This function does not produce any output.

Email::clearspambox

API Version: 1 - Click here for documentation
Syntax: Email::clearspambox( )
Description: Remove the spam box for all email addresses associated with the cPanel account.
Returns:  
 
The following line is repeated for each mailbox associated with the account:

Clearing spam mailbox for $accountname... Done<br>

Email::changemx

API Version: 1 - Click here for documentation
Syntax: Email::changemx( domain, exchange, preference, alwaysaccept, oldexchange, oldpreference )
Description: Change values for a specific MX record. This is the API1 version of the 'changemx' function. We recommend using the API2 version.
Parameters:  
  domain (string)
  The domain corresponding to the MX record to be changed.
  exchange (string)
  The name of the new exchanger.
  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 this parameter is not specified, cPanel will choose the best possible value.
  oldexchange (string (optional))
  The name of the exchanger to replace. If this parameter is not specified, cPanel will create a new entry.
  oldpreference (integer)
  The priority value of the old exchanger. If 2 entries for 'oldexchange' match, this function will decide which value will be used.
Returns:  
 
This function does not produce any output.

Email::checkfastmail

API Version: 1 - Click here for documentation
Syntax: Email::checkfastmail( )
Description: This function will check whether BlackBerry(tm) support for FastMail is enabled on the server. The function will also set the boolean fastmail cPvariable, which can then be checked later via a tag.
Returns:  
 
This function does not produce any output.

Email::checkpipefwd

API Version: 1 - Click here for documentation
Syntax: Email::checkpipefwd( pipe_name )
Description: Discern whether a script that receives forwarded mail should be preceded by a hashbang or a pipe. This will set the boolean cPvariables "pipefwd_needs_hashbang" and "pipefwd_needs_fixup" if either is needed in front of the pipe.
Parameters:  
  pipe_name (string)
  The piped program to check.
Returns:  
 
This function does not produce any output.

Email::delautoresponder

API Version: 1 - Click here for documentation
Syntax: Email::delautoresponder( email )
Description: Remove an auto responder.
Parameters:  
  email (string)
  The email address corresponding to the auto responder to be removed.
Returns:  
 
This function does not produce any output.

Email::delspam

API Version: 1 - Click here for documentation
Syntax: Email::delspam( )
Description: Disable SpamAssassin for an account.
Returns:  
 
This function does not produce any output.

Email::editquota

API Version: 1 - Click here for documentation
Syntax: Email::editquota( email, domain, quota )
Description: Change an email account's mail quota. This is the API1 version of the 'editquota' call. We recommend using the Email::editquota API2 call.
Parameters:  
  email (string)
  The local part of the email address whose quota will be changed (e.g., the part before the @ sign).
  domain (string)
  The domain that owns the email address.
  quota (integer)
  The quota (in megabytes) to set for the address. To specify an unlimited quota, set this parameter to 0.
Returns:  
 
This function does not produce any output.

Email::disable_spam_autodelete

API Version: 1 - Click here for documentation
Syntax: Email::disable_spam_autodelete( )
Description: Disable SpamAssassin's auto-delete spam feature.
Returns:  
 
This function does not produce any output.

Email::enable_spam_autodelete

API Version: 1 - Click here for documentation
Syntax: Email::enable_spam_autodelete( )
Description: Enable SpamAssassin's auto-delete spam feature.
Returns:  
 
This function does not produce any output.

Email::deldforward

API Version: 1 - Click here for documentation
Syntax: Email::deldforward( domain )
Description: Remove domain-wide forwarding.
Parameters:  
  domain (string)
  The domain corresponding to the forwarders to be removed.
Returns:  
 
This function does not produce any output.

Email::delspambox

API Version: 1 - Click here for documentation
Syntax: Email::delspambox( )
Description: Disable the SpamAssassin spam box for an account.
Returns:  
 
This function does not produce any output.

Email::dellist

API Version: 1 - Click here for documentation
Syntax: Email::dellist( list )
Description: Delete a mailing list.
Parameters:  
  list (string)
  The Mailman mailing list to remove. This input parameter should be formatted as list@example.com.
Returns:  
 
This function does not produce any output.

Email::delmx

API Version: 1 - Click here for documentation
Syntax: Email::delmx( domain, exchange, preference )
Description: Delete an MX record. This is the API1 version of the 'delmx' call. We recommend using the Email::delmx API2 call.
Parameters:  
  domain (string)
  The domain that corresponds to the mail exchanger to be removed.
  exchange (string)
  The name of the mail exchanger to be removed (e.g., 'mail.example.com').
  preference (integer (optional))
  The priority of the mail exchanger, 0 being the highest priority exchanger. Traditionally, increments of 5 or 10 are used.
Returns:  
 
This function does not produce any output.

Email::delfilter

API Version: 1 - Click here for documentation
Syntax: Email::delfilter( email, dest )
Description: Delete an email filter. This is the API1 version of the 'delfilter' call. We recommend using the Email::deletefilter API2 call.
Parameters:  
  email (string)
  The email address that owns the filter to be removed.
  dest (string)
  The destination of the filter to be removed. This parameter can take another email address or a shell pipe.
Returns:  
 
This function does not produce any output.

Email::delpop

API Version: 1 - Click here for documentation
Syntax: Email::delpop( email, flags, domain )
Description: Remove an email account. This is the API1 version of the 'delpop' call. We recommend using the Email::delpop API2 call.
Parameters:  
  email (string)
  The local part of the email address to delete (e.g., the part before the @ sign).
  flags (string)
  This parameter tells 'delpop' to remove the entry for the email address from the domain's passwd file. This parameter is optional; however, it should state passwd for 99% of uses.
  domain (string)
  The domain that owns the email address to remove.
Returns:  
 
This function does not produce any output.

Email::getarsinterval

API Version: 1 - Click here for documentation
Syntax: Email::getarsinterval( email )
Description: Get the auto responder interval for a particular account.
Parameters:  
  email (string)
  The email address that owns the auto responder whose interval will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
An integer value containing the auto responder's interval.

Email::has_spam_as_acl

API Version: 1 - Click here for documentation
Syntax: Email::has_spam_as_acl( )
Description: This function will determine whether the server is configured to use SpamAssassin as an ACL. It will also set the boolean cPvariable spam_as_acl. This variable can be used later in a cpanelif tag.
Returns:  
 
This function does not produce any output.

Email::getarsbody

API Version: 1 - Click here for documentation
Syntax: Email::getarsbody( email )
Description: Retrieve an auto responder's body field for a specified account.
Parameters:  
  email (string)
  The email address that owns the auto responder whose body field will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
A string containing the auto responder's body.

Email::has_spam_autodelete

API Version: 1 - Click here for documentation
Syntax: Email::has_spam_autodelete( )
Description: This function will determine whether the server is configured to use SpamAssassin to automatically delete messages that exceed a defined spam score. This function also sets the boolean cPvariable spam_auto_delete and the integer cPvariable spam_auto_delete_score. You can use both of these cPvariables later via cpanelif or cpanel print tags.
Returns:  
 
This function does not produce any output.

Email::getmailserveruser

API Version: 1 - Click here for documentation
Syntax: Email::getmailserveruser( account )
Description: Retrieve the username that should be used when a particular account attempts to authenticate to its mail server. This function merely takes the domain passed via the account parameter and changes the @ sign to +.
Parameters:  
  account (string (optional))
  The email account corresponding to the username that will be retrieved (e.g., user@example.com).
Returns:  
 
user+example.com

Email::getmailserver

API Version: 1 - Click here for documentation
Syntax: Email::getmailserver( account )
Description: Display a specific account's mail server. This function takes the mail domain passed in the account parameter and prepends mail. to the domain.
Parameters:  
  account (string (optional))
  The email account whose mail server will be displayed (e.g., user@example.com).
Returns:  
 
mail.example.com

Email::getarsfrom

API Version: 1 - Click here for documentation
Syntax: Email::getarsfrom( email )
Description: Retrieve an account's auto responder's from field.
Parameters:  
  email (string)
  The email address that owns the auto responder whose from field will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
A string containing the auto responder's from field.

Email::getarshtml

API Version: 1 - Click here for documentation
Syntax: Email::getarshtml( email )
Description: Retrieve a specific account's auto responder HTML body.
Parameters:  
  email (string)
  The email address that owns the auto responder whose HTML body will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
A string containing the auto responder's HTML body.

Email::getaging

API Version: 1 - Click here for documentation
Syntax: Email::getaging( email )
Description: Get the Email aging setting for a particular account.
Parameters:  
  email (string)
  The email address whose aging setting will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
The output will contain an integer that indicates the aging setting for the specified account.

Email::getarssubject

API Version: 1 - Click here for documentation
Syntax: Email::getarssubject( email )
Description: Retrieve an account's auto responder's subject field.
Parameters:  
  email (string)
  The email address that owns the auto responder whose subject field will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
A string containing the auto responder's subject.

Email::getarscharset

API Version: 1 - Click here for documentation
Syntax: Email::getarscharset( email )
Description: Retrieve the auto responder's character set for a specified account.
Parameters:  
  email (string)
  The email address corresponding to the auto responder whose character set will be retrieved. Note: This setting is not required for webmail.
Returns:  
 
A string containing the auto responder's character set.

Email::getpopquota

API Version: 1 - Click here for documentation
Syntax: Email::getpopquota( email, domain )
Description: Retrieve an email account's quota.
Parameters:  
  email (string)
  The local part of the email address (e.g., the part before the @ symbol).
  domain (string)
  The domain that owns the email address whose quota will be retrieved (e.g., example.com).
Returns:  
 
An integer representing the email quota.

Email::passwdpop

API Version: 1 - Click here for documentation
Syntax: Email::passwdpop( email, password, quota, domain )
Description: Change an email account's password. This is the API1 version of the 'passwdpop' call. We recommend using the API2 version.
Parameters:  
  email (string)
  The username section of the email address. This is the part of the email address before the @ sign.
  password (string)
  The new password for the email account.
  quota (integer)
  A positive integer that indicates the amount of disk space the new email account is able to use. Entering 0 gives the account an unlimited disk quota.
  domain (string)
  The domain that hosts the email account (e.g., example.com).
Returns:  
 
Nothing.

Email::delforward

API Version: 1 - Click here for documentation
Syntax: Email::delforward( forwarder )
Description: Delete a mail forwarder.
Parameters:  
  forwarder (string)
  The forwarder to delete. This parameter should contain both the local email address and the destination address, separated by an equal (=) sign. For example, a forwarder from user@example.com to user@example.net should be formatted as user@example.com=user@example.net.
Returns:  
 
Nothing.

Email::passwdlist

API Version: 1 - Click here for documentation
Syntax: Email::passwdlist( list, password )
Description: Change a mailing list password.
Parameters:  
  list (string)
  The mailing list whose password will be changed.
  password (string)
  The password that to use for the mailing list.
Returns:  
 
Nothing.

Email::spamstatus

API Version: 1 - Click here for documentation
Syntax: Email::spamstatus( )
Description: This function will display whether SpamAssassin is enabled or disabled for an account. This will also set the spamstatus boolean cPvariable, which can be used later inside of a tag.
Returns:  
 
Enabled if SpamAssassin is enabled. Otherwise the function will output Disabled.

Email::mainacctdiskused

API Version: 1 - Click here for documentation
Syntax: Email::mainacctdiskused( )
Description: Display the amount of disk space used by the main mail account.
Returns:  
 
A string that contains the amount of disk space used by the main mail account.

Email::tracefilter

API Version: 1 - Click here for documentation
Syntax: Email::tracefilter( account, msg )
Description: Test the action of an account's mail filters. Only filters for a cPanel account's main domain will be tested. In addition, this function only tests filters applied the body of the message. This is the API1 version of the tracefilter call. We recommend using the Email::tracefilter API2 call instead.
Parameters:  
  account (string (Optional))
  This parameter accepts the name of the account whose old-style cPanel filters, which reside in the account's $home/filters directory, will be tested. If this parameter is unspecified, the function will test the main domain's filters in the /etc/vfilters/ directory.
  msg (string)
  The contents of the body section of the message to be tested.
Returns:  
 
A string value that contains a message of success or failure, the name of the file that was examined, and the destination of the filter.

Email::listmaildomainsoptndef

API Version: 1 - Click here for documentation
Syntax: Email::listmaildomainsoptndef( sdomain )
Description: Retrieve a list of domains available for email within
Parameters:  
  sdomain (string)
  The domain to mark as Selected; that is, the default.
Returns:  
 
The output should resemble the following, with one line for every available domain:
<option value="selectedexample.com"" selected>selectedexample.com</option>
<option value="example.com">example.com</option>


Email::listmaildomains

API Version: 1 - Click here for documentation
Syntax: Email::listmaildomains( )
Description: List available domains for email within %lt;option> HTML tags. This version of this call will automatically select the main domain for an account. This is an API1 call. We recommend using the API2 call Email::listmaildomains instead.
Returns:  
 
A repetition of the following for every available mail domain on an account.
<option value="maindomain.com"" selected>maindomain.com</option>
<option value="domain.com">domain.com</option>


Email::setmxaccept

API Version: 1 - Click here for documentation
Syntax: Email::setmxaccept( domain, mxcheck )
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. The MX's DNS entry will need to be configured elsewhere. This is the API1 version of this call; we recommend using the Email::setalwaysaccept API2 call instead.
Parameters:  
  domain (string)
  The domain corresponding to the mail exchanger to be 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 higher priority (lower numbered) mail server becomes available.
* remote - Do not accept mail for the domain.
Returns:  
 
This function does not produce any output.

Email::spamboxstatus

API Version: 1 - Click here for documentation
Syntax: Email::spamboxstatus( )
Description: This function will display whether SpamAssassin's spam box feature is enabled or disabled for an account.
Returns:  
 
Enabled if the spam box feature is enabled. Otherwise, the function will output Disabled.

Email::getarsstart

API Version: 1 - Click here for documentation
Syntax: Email::getarsstart( email )
Description: Retrieve the start time of an autoresponder.
Parameters:  
  email (string)
  The email address for which to retrieve the start time.
Returns:  
 
The Unix time when the auto responder was or will be disabled.

Email::adddforward

API Version: 1 - Click here for documentation
Syntax: Email::adddforward( domain, destdomain )
Description: Create a domain-level email forwarder.
Parameters:  
  domain (string)
  The domain for which email will be forwarded.
  destdomain (string)
  The domain that will receive forwarded email.
Returns:  
 
This function will produce a string if it encounters an error. Otherwise, this function will not produce any output.

Email::listmaildomainsopt

API Version: 1 - Click here for documentation
Syntax: Email::listmaildomainsopt( )
Description: Generate HTML option tags for all domains that can accept mail.
Returns:  
 
The output should resemble the following:
<option value="example.com">example.com</option>
<option value="subdomain.example.com">subdomain.example.com</option>
<option value="example2.com">example2.com</option>
etc.

Email::getarsstop

API Version: 1 - Click here for documentation
Syntax: Email::getarsstop( email )
Description: Retrieve the stop time of an autoresponder.
Parameters:  
  email (string)
  The email address for which to retrieve the stop time.
Returns:  
 
The Unix time that specifies when the autoresponder was or will be enabled.

Topic revision: r5 - 27 Mar 2013 - 16:13:11 - Main.LaurenceSimon