HCCEmail A Custom API for Cpanel Version 0.2.1 beta 11/MAY/2005 © 2003, 2005 Juan R. Pozo http://html.conclase.net/cp/scripts/ mailto:jrpozo@conclase.net Mailing list: http://www.conclase.net/mailman/listinfo/cpanel_conclase.net License This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Note: a copy of the GNU General Public License is available at: http://html.conclase.net/cp/scripts/license.html Installation 1) Check if the file HCCEmail.pm exists in your server inside the /usr/local/cpanel/Cpanel/ directory 2) If it exists and isn't a previous version of this API please contact me. Otherwise, follow steps 3 to 9 3) switch to root user 4) # cd /usr/local/cpanel/Cpanel/ 5) # wget –N http://html.conclase.net/cp/scripts/HCCEmail.pm 6) # chown root.root HCCEmail.pm 7) # chmod 0644 HCCEmail.pm 8) Add the following language variables to your language files: // HCCEmail (English) HCCEmail_Address=Address HCCEmail_Account=Account HCCEmail_Delete=Delete HCCEmail_Domain=Domain HCCEmail_EditPassword=Edit Password HCCEmail_EditQuota=Edit Quota HCCEmail_Login=Login HCCEmail_Next=Next HCCEmail_Outlook=Outlook Autoconfig HCCEmail_OutlookAlert1Pre=This will automatically install the proper mail setting for the HCCEmail_OutlookAlert1Mid=account into Microsoft (R) Outlook (Express)[tm]. Please close all running copies of Microsoft (R) Outlook (Express)[tm] before going forward! When finished start Microsoft (R) Outlook (Express)[tm] and it should have the HCCEmail_OutlookAlert1Post=account configured for you. HCCEmail_OutlookAlert2=If prompted to open or save this file choose "Open this file from its current location." HCCEmail_OutlookAlert3=When asked if you would like to enter the information into the Registry choose "Yes". HCCEmail_Previous=Previous HCCEmail_Quota=Quota HCCEmail_Webmail=Read Webmail HCCEmail_AddingAccount=Adding account HCCEmail_WrongAddressFormat=Wrong Address Format HCCEmail_MissingPassword=Missing Password HCCEmail_Aging=Aging // HCCEmail (Spanish) HCCEmail_Address=Dirección HCCEmail_Account=Cuenta HCCEmail_Delete=Borrar HCCEmail_Domain=Dominio HCCEmail_EditPassword=Editar Contraseña HCCEmail_EditQuota=Editar Cuota HCCEmail_Login=Usuario HCCEmail_Next=Siguiente HCCEmail_Outlook=Autoconf Outlook HCCEmail_OutlookAlert1Pre=A continuación se instalará la configuración de correo adecuada para la cuenta HCCEmail_OutlookAlert1Mid=en Microsoft (R) Outlook (Express)[tm]. Antes de continuar cierre todas las copias que se estén ejecutando de Microsoft (R) Outlook (Express)[tm]. Al final del proceso, la cuenta HCCEmail_OutlookAlert1Post=debería estar correctamente configurada. HCCEmail_OutlookAlert2=Si el navegador le pregunta si desea abrir o guardar este fichero, elija "Abrir este fichero desde su localización actual". HCCEmail_OutlookAlert3=Cuando el sistema le pregunte si desea introducir la información en el Registro elija "Sí". HCCEmail_Previous=Anterior HCCEmail_Quota=Cuota HCCEmail_Webmail=Leer Correo Web HCCEmail_AddingAccount=Añadiendo cuenta HCCEmail_WrongAddressFormat=Formato de dirección incorrecto HCCEmail_MissingPassword=Falta la contraseña HCCEmail_Aging=Caducidad // HCCEmail (Brazilian Portuguese) HCCEmail_Address=Endereço HCCEmail_Account=Nome da Conta HCCEmail_Delete=Remover HCCEmail_Domain=Domínio HCCEmail_EditPassword=Editar Senha HCCEmail_EditQuota=Editar Cota HCCEmail_Login=Usuário HCCEmail_Next=Próximo HCCEmail_Outlook=Config Outlook HCCEmail_OutlookAlert1Pre=Você selecionou a instalação automática da conta HCCEmail_OutlookAlert1Mid=no Microsoft (R) Outlook (Express)[tm]. Antes de continuar feche o Outlook (Express)[tm]. Ao final do proceso, a conta HCCEmail_OutlookAlert1Post=deverá estar corretamente configurada para você. HCCEmail_OutlookAlert2=Na próxima tela de alerta, escolha a opção "Executar Arquivo". HCCEmail_OutlookAlert3=Quando o sistema lhe perguntar se deseja inserir as informações no registro, responda "Sím". HCCEmail_Previous=Anterior HCCEmail_Quota=Cota HCCEmail_Webmail=Webmail HCCEmail_AddingAccount=Incluindo contato HCCEmail_WrongAddressFormat=Formato de endereço incorreto HCCEmail_MissingPassword=Falta a senha HCCEmail_Aging=Expurgo API Reference Displays a table containing length email accounts, starting from $FORM{'first'} (first account being account number 0). If length is 0 or empty, all accounts are listed. If all accounts cannot be listed in the available space, another navigation bar, with "Previous" and "Next" links, is also displayed (the language messages HCCEmail_Next and HCCEmail_Previous must exist in the corresponding language file). The position of the navigation bar depends on the value of the navpos parameter: top, bottom or both. Any other value is taken as bottom. The format parameter specifies the information that will be displayed about each account. This is a string of space separated values. Allowed values are: - account: the local name of the account (the part on the left hand side of the @ sign); in the header row it outputs the language string HCCEmail_Account; - address: the whole email address; in the header row it outputs the language string HCCEmail_Address; - login: the POP3/IMAP username. This is composed of: the local name of the account, plus the userchar character, plus the domain name. The default value for the userchar parameter is '+'. Other valid values are '@' and '%'; in the header row it outputs the language string HCCEmail_Login; - domain: the domain name of the account; in the header row it outputs the language string HCCEmail_Domain; - arrow: the string "=>"; - arrowimg: typically an arrow image. The actual image can be specified with the imagedir and the arrowimg parameters (see below); - quota: the space used by the account's inbox, and its quota if it's set, separated by a slash character; in the header row it outputs the language string HCCEmail_Quota; - delete: a link to the page containing a form to delete the account. The actual link can be defined with the delpoppg parameter (see below); - deleteimg: an image link to the page containing a form to delete the account. The actual image file and target page can be defined with the delpopimg and delpoppg parameters respectively (see below); - webmail: a link to Cpanel's webmail page for this account. By default, port 2095 is used for non-SSL connections and port 2096 is used for SSL connections. These values can be overriden by using the port and sslport parameters; - webmailimg: an image link to Cpanel's webmail page for this account. The actual image file can be defined with the webmailimg parameter (see below); - edquota: a link to the page containing a form to edit the account's quota. The actual link can be defined with the edquotapg parameter (see below); - edquotaimg: an image link to the page containing a form to edit the account's quota. The actual image file and target page can be defined with the edquotaimg and edquotapg parameters respectively (see below); - edpasswd: a link to the page containing a form to edit the account's password. The actual link can be defined with the edpasswdpg parameter (see below); - edpasswdimg: an image link to the page containing a form to edit the account's password. The actual image file and target page can be defined with the edpasswdimg and edpasswdpg parameters respectively (see below); - aging: a link to the page containing a form to edit the account's mail aging value. The actual link can be defined with the agingpg parameter (see below); - agingimg: an image link to the page containing a form to edit the account's mail aging value. The actual image file and target page can be defined with the agingimg and agingpg parameters respectively (see below); - outlook: a javascript generated link to execute the javascript function which uploads the registry configuration to the user's computer and automatically configures the account in MS Outlook Express. This functionality will only be included if not disabled from WHM. Specifying outlook in a format string where this functionality is disabled will result in an empty cell. - {verbatim}: includes verbatim text, i.e., text enclosed in curly braces will be copied to the output as it appears in the format string. - #: Account number in the current order scheme. - Any other value will result in a   character. Options can be specified in any order, and any number of options can be specified. The addmain parameter specifies where the main account should be placed. Valid values are: - no: not to include the main account at all; - once: to include it as the first account (i.e., it will appear in the first page only, regardless of the order scheme specified). The delpoppg, edquotapg, edpasswdpg, agingpg parameters specify the relative paths to the pages containing forms to delete the account, edit the account's quota, edit the account's password and edit the account's password aging value respectively. The images parameter specifies the directory under which the images specified in the img parameters are stored. The value is a path relative to the theme's index directory, i.e., if the theme's name is themename, and images is img, the absolute URL path will be /frontend/themename/img/. The default value is images. The delpopimg, webmailimg, edquotaimg, edpasswdimg, agingimg, outlookimg, arrowimg parameters specify the filenames of the images that will be used if requested in the format string. The images are expected to be stored in a subdirectory of the images directory specified via the images parameter (see above) with the same name as the user's language (the LANG value in the user's data file). In the example above, these would be /themename/img/english/, /themename/img/deutsch/, etc. Default values are delete.gif, webmail.gif, quota.gif, passwd.gif, aging.gif, outlook.gif and arrowr.gif respectively. Note: it seems that Cpanel doesn't recognise non ASCII characters as valid URL characters. Therefore, images stored under español will not be found. To prevent this, each character of the language name which that does not belong to the US ASCII set (i.e., whose ASCII code is greater than 127) is converted to a hyphen character. Thus, the images for language español should be stored in the espa-ol subdirectory, images for users of français should go into fran-ais, etc. The domains parameter is a space separated list of domains (which can include main domain, parked domains, addon domains, and their subdomains) which must be listed. The default value all means all domains. The default order in which accounts are printed out is domain order, i.e., domains listed in alphabetical order, and accounts of each domain listed in alphabetical order. If the order parameter is left as $FORM{'domain'}, the user can change the order by clicking on the header cells, according to the following: - If a domain column is inserted, the header cell allows to change between domain order (as described above) and revdomain order (domains listed in descending alphabetical order and accounts of each domain listed in descending alphabetical order). - If an address, login or account column is inserted, the header cell allows to change between addr order (accounts listed alphabetically) and revaddr order (inverse order). - If a quota column is inserted, the header cell allows to change between quota order (accounts listed in descending order by space used) and revquota order (same, in ascending order). For CSS formatting purposes, the following class attributes are set: - The pop table has class="hcc-email-poptable". - The navigation table has class="hcc-email-popnavigation". - The cells of the first column of each table have class="hcc-first". - The cells of the last column of each table have class="hcc-last". - All other cells have class="hcc-col-X" where X is the column number, i.e., a table with four columns would have cells of classes hcc-first, hcc-col-2, hcc-col-3 and hcc-last. - Even rows of the pop table have class="hcc-even". - Odd rows of the pop table (except for the headers row) have class="hcc-odd". A full example follows. Email Accounts Adds several accounts at once. The $FORM{'csvlist'} is a list of comma separated value lines. Each line of the list must have the following format: account@domain, password or account@domain, password, quota Changelog 0.2.1 Beta – May 11, 2005 Fixed lang function to account for Cpanel's cachelang mechanism. Added aging column. Improved inbox size calculation. Fixed webmail login URL. Added Brazilian Portuguese language file by Wilton Bennet. 0.2 Beta – January 30, 2004 Add AddAccounts API call. 0.1.1 Beta – September 23, 2003 Follow same convention for key values in language files than in the other HCC Api modules, i.e., HCCEmail_Domain instead of HCCEmailDomain, etc. 0.1 Beta – June 19, 2003 First public release. Please consider making a donation today. Visit my amazon.com wishlist at: http://html.conclase.net/link/wishlist Thank you :)