Ensim WEBppliance TM Pro for Windows 2000 Mail Server API

Transcription

1 Ensim WEBppliance TM Pro for Windows 2000 Mail Server API September 17, 2003 Introduction Ensim WEBppliance TM Pro for Windows 2000 defines a fixed set of -related tasks that you can perform using the control panel at each level of administration. Each task maps to one or more mail server backend API (application programming interface) calls. WEBppliance Pro for Windows 2000 calls the API at appropriate times. Each API should be implemented as a VBScript (Visual Basic Scripting Edition). Each script has the following semantics: APIcommand.vbs <parameter1_value> <parameter2_value>... where APIcommand.vbs is the name of the script that implements the API call, <parameter1_value> is the value of the first parameter for the script, <parameter2_value> is the value of the second parameter for the script, and so on. Note: Any additional capabilities provided by your mail server are independent and will not be reflected in the WEBppliance Pro for Windows 2000 control panel. Ensim offers two API calls to help you integrate your mail server into the existing WEBppliance Pro for Windows 2000 setup: Mail Server API and Registration API. Mail Server API. This is a backend API used by WEBppliance Pro for Windows 2000 to carry out various actions on the underlying mail server. This API is called whenever you perform any action on the mail server through the WEBppliance Pro for Windows 2000 control panel. Registration API. This API is used by you to register your mail server add-on with WEBppliance Pro for Windows As part of the registration process, the mail server backend API that you provide gets plugged into WEBppliance Pro for Windows ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 1

2 This document defines the semantics of all the API calls. Topics in this document include: Before you start on page 2 Mail Server API calls on page 2 Registration API calls on page 24 Feedback and support on page 25 Legal and copyright notice on page 25 Before you start Before you start integrating the API calls, you may find it helpful to review the following list of rules. You must provide implementation for all the APIs described in this document. The server backend API calls use a script written in the Visual Basic Scripting Edition (VBScript). This script returns 0 on success and 1 on failure. Based on the result code, the output of the script is interpreted by WEBppliance Pro for Windows 2000 either as an output from the command or the error returned by the backend call. Each backend API implementation performs an input parameter validation and fails the call if any invalid parameters are passed to it. If you want to write the mail server backend API call in a programming language of your choice and not as VBScript, you can write placeholder VBScripts that just call down to the API. If certain functionality exposed by the WEBppliance Pro for Windows 2000 control panel is not supported by your mail server, you should provide a placeholder implementation for the API and fail the API call by returning 1 and printing the appropriate error message: This functionality is not provided by <xxx> mail server. Mail Server API calls The APIs in this section include: Add mail domain on page 4 Edit mail domain on page 4 Suspend mail domain on page 5 Resume mail domain on page 5 Delete mail domain on page 6 Get mail domain list on page 6 Add mail domain alias on page 7 ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 2

3 Delete mail domain alias on page 7 Get mail domain alias list on page 8 Add mail domain user on page 8 Edit mail domain user on page 9 Delete mail domain user on page 10 Get mail domain user list on page 10 Get mail domain user information on page 11 Authenticate mail domain user on page 12 Add mail domain user alias on page 12 Delete mail domain user alias on page 12 Get mail domain user alias list on page 13 Add mail domain user forward on page 14 Delete mail domain user forward on page 14 Get mail domain user forward list on page 15 Set up autoresponder for mail domain user on page 16 Get autoresponder record for mail domain user on page 16 Delete autoresponder record for mail domain user on page 17 Add spam filter for mail domain on page 17 Delete spam filter for mail domain on page 18 Get spam filter list on page 19 Get Web interface URL on page 19 Set Web interface URL on page 20 Delete Web interface URL on page 20 Start mail server on page 20 Stop mail server on page 21 Get mail server status on page 21 Check presence of mail server on page 21 Configure mail server on page 22 Back up mail server on page 22 Change domain IP address on page 23 Change network settings on page 23 ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 3

4 Add mail domain EAddDomain.vbs IpAddress - IP address for the mail domain. MailBoxDirectory - Full path to the directory where the mails for this mail domain should be stored. MaxMailBoxes - Maximum number of mail boxes allowed for this mail domain. MailDomainOwner - Owner of this mail domain. This user is same as the site administrator. MailDomainOwnerPassword - Plain text password for the owner of the mail domain specified by MailDomainOwner parameter. The API will add the mail domain, add the user specified by MailDomainOwner on the domain, and set the catchrest alias for the domain to point to this user. Edit mail domain EEditDomain.vbs MaxMailBoxes - Maximum number of mail boxes allowed for this mail domain. The API will verify whether the existing number of users on the mail domain is already above MaxMailBoxes. In such cases, the API will fail the call with the appropriate error message. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 4

5 Suspend mail domain ESuspendDomain.vbs If your mail server does not support suspending a mail domain, the API will provide a placeholder implementation. The placeholder implementation will simply return a success. Resume mail domain EResumeDomain.vbs If your mail server does not support suspending and resuming a mail domain, the API will provide a placeholder implementation. The placeholder implementation will simply return a success. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 5

6 Delete mail domain EDeleteDomain.vbs The API will delete all the information associated with the mail domain including its users, domain aliases, user forwards, and aliases. Note: WEBppliance Pro for Windows 2000 will not make any additional backend calls to clean the delete process. Get mail domain list EGetDomainList.vbs None The API will print a line per mail domain on the standard output. Each line will display five fields separated by spaces ( ) name of the mail domain, IP address of the mail domain, path of the directory where the messages are stored, maximum number of mailboxes, and number of users/mailboxes hosted on the mail domain. Example: foo.com c:\webppliance\conf\domains\foo\mail 20 5 ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 6

7 Add mail domain alias EAddDomainAlias.vbs DomainAlias - Name of the domain alias. The API will add a new mail domain alias. Note: WEBppliance Pro for Windows 2000 does not expect the API to add the necessary DNS records. You can choose to add the necessary DNS records on your own. Delete mail domain alias EDeleteDomainAlias.vbs DomainAlias - Name of the domain alias. The API will delete the specified mail domain alias. Note: WEBppliance Pro for Windows 2000 does not expect the API to remove the necessary DNS records. You can choose to remove the necessary DNS records on your own. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 7

8 Get mail domain alias list EGetDomainAliasList.vbs The API will print all domain aliases for mail domain specified by DomainName on standard output. Each domain alias name will be printed on a separate line. Add mail domain user EAddUser.vbs UserName - Name of the mail domain user. Password - Plain text password for the mail domain user. FirstName - First name of the user. MiddleName - Middle name of the user. LastName - Last name of the user. The API will add all the information associated with the mail domain user. Note: If your mail server stores the mail user display name as a single field instead of separate fields for FirstName, MiddleName, LastName, the API will covert these fields to form a single full name and store it on the mail server. Since WEBppliance Pro for Windows 2000 treats the display name as separate fields, the API implementation will return it back as separate fields when WEBppliance Pro for Windows 2000 asks for these fields in other APIs. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 8

9 Edit mail domain user EEditUser.vbs UserName - Name of the mail domain user. Password - Plain text password for the mail domain user. FirstName - First name of the user. MiddleName - Middle name of the user. LastName - Last name of the user. The API will modify all the information associated with the mail domain user. Note: If your mail server stores the mail user display name as a single field instead of separate fields for FirstName, MiddleName, LastName, the API will covert these fields to form a single full name and store it on the mail server. Since WEBppliance Pro for Windows 2000 treats the display name as separate fields, the API implementation will return it back as separate fields when WEBppliance Pro for Windows 2000 asks for these fields in other APIs. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 9

10 Delete mail domain user EDeleteUser.vbs UserName - Name of the mail domain user. The API will delete all the information associated with the mail domain user including aliases, forwards, and autoresponders associated with this user. It will also clean up the mail storage used by this user. Note: WEBppliance Pro for Windows 2000 will not make any additional backend calls to clean this up. Get mail domain user list EGetUserList.vbs The API will print a line per mail domain user on the standard output. Each line will have seven fields separated by colons (:) user name, password, first name, middle name, last name, 1/0 based on whether this user has forwarding set and 1/0 based on whether this user has autoresponders set. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 10

11 Example: There are two users, u1 (John B. Teddy) and u2 (Robert S. Smith) with the password ensim hosted on a mail domain, foo.com. If u1 forwards messages to u2 s address and if u2 has an autoresponder set up, then the output of EGetUserList.vbs foo.com will print the following information: u1:ensim:john:b:teddy:1:0 u2:ensim:robert:s:smith:0:1 Get mail domain user information EGetUserInfo.vbs UserName - Name of the mail domain user. The API will print a line per mail domain user on the standard output. Each line will have six fields separated by colons (:) password, first name, middle name, last name, 1/0 based on whether this user has forwarding set, and 1/0 based on whether this user has autoresponders set. Example: There are two users u1 (John B. Teddy) and u2 (Robert S. Smith) with password ensim hosted on a mail domain, foo.com. If u1 forwards messages to u2 s address and if u2 has an autoresponder set up, then the output of EGetUserInfo.vbs foo.com u1 will print the following information: ensim:john:b:teddy:1:0 And EGetUserInfo.vbs foo.com u2 will print the following information ensim:robert:s:smith:0:1 ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 11

12 Authenticate mail domain user EAuthenticateUser.vbs UserName - Name of the mail domain user Password - Plain text password for the mail domain user. The API will print 1 on standard output if the passwords match, else it will print 0. Add mail domain user alias EAddUserAlias.vbs UserName - Name of the mail domain user. UserAlias - User alias for UserName. The API will add the specified alias and ensure that there are no users hosted on DomainName with the same alias (as specified by UserAlias). Delete mail domain user alias EDeleteUserAlias.vbs UserName - Name of the mail domain user. UserAlias - User alias for the mail domain user. The API will delete the specified alias. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 12

13 Get mail domain user alias list EGetUserAliasList.vbs DomainName - Name of the mail domain The API will print a line for each mail user hosted on DomainName. Each line will contain two fields separated by a space ( ) UserName and comma separated list of user aliases for the UserName. Note: If certain user on the mail domain does not have any user aliases, it will only print the UserName. Example: There are two users, u1 and u2 hosted on a mail domain foo.com. If u1 has two aliases defined, al1 and al2, then the output of EGetUserAliasList.vbs foo.com will print the following on the standard output u1 al1,al2 u2 ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 13

14 Add mail domain user forward EAddForward.vbs UserName - Name of the mail domain user. UserForward - Forward address for UserName. The API will add the specified forward and ensure that there are no users hosted on DomainName with the same forward (as specified by UserForward). Delete mail domain user forward EDeleteForward.vbs UserName - Name of the mail domain user. UserForward - Forward address for UserName. The API will delete the specified forward. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 14

15 Get mail domain user forward list EGetForwardList.vbs UserName - Name of the mail domain user. The API will print a line for each mail user hosted on DomainName. Each line will contain two fields separated by a space ( ) UserName and comma separated list of forward records for the UserName. Note: If an empty UserName is passed the API, it will print forward records for all the users on the specified DomainName. Otherwise, it will print forward records for the specified UserName. If the specified UserName does not have a forward record, it will only print the UserName. Example: There are two users, u1 and u2, hosted on a mail domain foo.com. If u1 has two forward records defined: u1@alternat .com and u1@mymail.com and u2 has no forward records defined, then the output of EGetForwardList.vbs foo.com should print the following on the standard output u1 u1@alternat .com,u1@mymail.com u2 And the output of EgetForwardList.vbs foo.com u1 should print the following on standard output u1 u1@alternat .com,u1@mymail.com ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 15

16 Set up autoresponder for mail domain user ESetAutoResponder.vbs UserName - Name of the mail domain user. Subject - Subject text for auto-response . Message - Message text for auto-response . The API will set up an autoresponder with the specified text for the mail domain user. Note: If the message contains multiple lines, WEBppliance Pro for Windows 2000 will replace the new line characters with the Alt-255#Alt-255 sequence, that is, á#á before calling the API. The API will covert it back to the original message before carrying out this action on the mail server. This can be achieved in vbscript by using replace(message, á#á, vbcrlf) Get autoresponder record for mail domain user EGetAutoResponder.vbs UserName - Name of the mail domain user. The API will print Subject text and Message text on the standard output. The first line of output is treated as Subject text and rest is treated as Message text. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 16

17 Delete autoresponder record for mail domain user EDeleteAutoResponder.vbs UserName - Name of the mail domain user. The API will delete the all autoresponder records for the specified mail domain user. Add spam filter for mail domain EAddSpamFilter.vbs ballow - Flag to specify whether Allow/Block kind of record needs to be added. SpamFilterType - Type of spam filter. SpamFilter - Spam filter. The API will add a spam filter for the specified mail domain. Note: This API is supported only for IP based sites If ballow = 0, the API will add block type of spam filter If ballow = 1, API will add allow type of spam filter If SpamFilterType=1, the API will add spam filter If SpamFilterType=2, API will add IP spam filter If SpamFilterType=3, API will add SMTP connection spam filter If SpamFilterType=1, then SpamFilter parameter contains the domain name or address. In this case ballow parameter is ignored, that is, spam filters are always for block type of records. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 17

18 If SpamFilterType=2 or 3, then the SpamFilter parameter either contains a single IP address or a range of IP addresses. If a single IP address is specified, then it can contain wildcard characters and the API will expand it. For example, if the IP address is specified as * then the API will map it to a range of IP address to If the range of IP addresses are specified, they cannot contain wild card characters Example: To add a block type of spam filter, tom@banned.com for mail domain foo.com, the script may be called as follows: eaddspamfilter.vbs foo.com 0 1 tom@banned.com To add a block type of IP spam filter to a block range of IP addresses between to for mail domain foo.com, the script may be called as follows. eaddspamfilter.vbs foo.com * or eaddspamfilter.vbs foo.com Delete spam filter for mail domain EDeleteSpamFilter.vbs ballow - Flag to specify whether Allow/Block kind of record needs to be deleted. SpamFilterType - Type of spam filter. SpamFilter - Spam filter. The API will remove the spam filter for the specified mail domain. Note: Refer to the Notes section of Add spam filter for mail domain on page 17. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 18

19 Get spam filter list EGetSpamFilterList.vbs The API will print a line for each spam filter record hosted on the DomainName. Each line will contain three fields separated by spaces ( ) flag specifying whether it is a allow or block record, SpamfilterType, and SpamFilter. Example: There is domain called foo.com for which there is an spam filter for tom@banned.com and an IP spam filter for the range of IP addresses and an IP spam filter for a single IP address The output of this API will look like this: 0 1 tom@banned.com Get Web interface URL EGetMailURL.vbs If your mail server supports a Web based interface, the API will print the Web URL for the specified DomainName on standard output. Otherwise, the API will fail with an exit code of 1. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 19

20 Set Web interface URL ESetMailURL.vbs If your mail server supports a Web based interface, the API will perform all the tasks required to Web enable the specified DomainName. Delete Web interface URL EDelet URL.vbs If your mail server supports a Web based interface, the API will perform all the tasks required to remove the Web interface for the specified DomainName. Start mail server EStartMailServer.vbs None The API will perform the tasks required to start the following mail services: POP, SMTP, and IMAP. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 20

21 Stop mail server EStopMailServer.vbs None The API will perform the tasks required to stop the following mail services: POP, SMTP, and IMAP Get mail server status EGetStatus.vbs None The API will check if the mail services POP, SMTP, and IMAP are running. It will output 1/0 on standard output based on whether the mail services are running or not. Check presence of mail server EIsInstalled.vbs None The API will check if your mail server is installed on the system. It will output 0/1 on standard output based on whether the mail server is installed or not. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 21

22 Configure mail server EConfigur Server.vbs InstallPath - This is the location where all API scripts are installed. For example, if WEBppliance Pro for Windows 2000 is installed in the default location, then InstallPath will be c:\program files\ensim\webppliance\base\services\winmail\mailapi. If the EConfigur Server.vbs needs to call any mail APIs it can use this parameter to find the script path. bregister - Flag to indicate whether mail add-on is getting registered or getting removed. Note: This API is called during the mail add-on registration (bregister=1) and removal (bregister=0) process. This is a hook provided by the registration process and you can use this hook for any purpose. Back up mail server EBackupMailServer.vbs BackupDir - This is the directory where mail server should back up its configuration information. Note: WEBppliance Pro for Windows 2000 calls this API from its daily backup process. This is also called when someone attempts to change the primary IP address of the server through the network configuration utility or by using the changeip.vbs script ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 22

23 Change domain IP address EChangeDomainIP.vbs DomainName - Name of the mail domain IPAddress - New IP address for the mail domain The API changes the IP address of the specified domain to the value specified by IPAddress Change network settings EChangeNetworkSettings.vbs OldIPAddress - Original primary IP address of the server. OldFQDN - Original fully qualified domain name of the server. NewIPAddress - New primary IP address of the server. NewFQDN - New fully qualified domain name of the server. The API will update the mail server with new network settings Note: WEBppliance Pro for Windows 2000 calls this API when you change the primary IP address of the server and then use the network configuration utility provided by WEBppliance Pro for Windows 2000 to configure it for new network settings. The API will completely take care of updating the mail server with new network settings. WEBppliance Pro for Windows 2000 will not touch any mail server configuration. ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 23

24 Registration API calls Note: You must provide the implementation of the mail server backend API for all the APIs described in the previous section and package them as a single.zip file. The API exposed by WEBppliance Pro for Windows 2000 for registration/removal is as follows: Register mail add-on on page 24 Remove mail add-on on page 25 Register mail add-on RegisterMailAddon.vbs MailServerDisplayName - Name of the mail server. VendorName - Name of the vendor. MailServerVersion - Mail server version number. IsStartable - Flag (0/1) indicating whether mail server supports start/stop actions. Zippath - Path to the zip file, containing the implementation for all the APIs described in previous section. The API registers the specified add-on. Note: The RegisterMailAddon script resides in <install_dir>\util\mailaddon, where <install_dir> refers to the path where WEBppliance Pro for Windows 2000 is installed. For example, if WEBppliance Pro for Windows 2000 is installed in c:\program files\ensim\webppliance, then this script resides at c:\programfiles\ensim\webppliance\util\mailaddon\registermailaddon ENSIM WEBPPLIANCE PRO FOR WINDOWS 2000 MAIL SERVER API 24

25 Remove mail add-on UnregisterMailAddon.vbs None. The API removes the specified add-on. Feedback and support To take advantage of Ensim s support services or to find additional product documentation, visit the Ensim support site, To log in to Ensim online support, go to To provide feedback about Ensim products or documentation, please use the feedback form at Legal and copyright notice This document contains information proprietary to Ensim Corporation and its receipt or possession does not convey any rights to reproduce, disclose, manufacture, or sell anything it might describe. Reproduction, disclosure, or use without Ensim s specific written authorization is strictly forbidden. Ensim Corporation makes no representations or warranties with respect to the content or use of this document. It also reserves the right to revise this document at any time without the obligation to notify any person of such revision. Ensim, the Ensim logo, and ServerXchange are registered trademarks of Ensim Corporation. WEBppliance is a trademark of Ensim Corporation. All other trademarks and copyrights are the property of their respective owners Ensim Corporation. All rights reserved. Ensim Corporation 1366 Borregas Avenue Sunnyvale, CA (408) Ensim Corporation. All rights reserved. wwp36_2000_api_0_2