----------- OVERVIEW ----------- This file documents the XML-RPC API provided by SecurityGateway for Exchange/SMTP. -------------------- TABLE OF CONTENTS -------------------- Revision history Integrating your custom applications with SecurityGateway for Exchange/SMTP Intro to XML-RPC XML-RPC Methods
XML-RPC Access functions XML-RPC Domain functions XML-RPC User functions XML-RPC Alias functions XML-RPC Domain Mail Server functions XML-RPC User Verification Source functions XML-RPC Administrator Rights functions XML-RPC External Administrator functions Sample VBScripts ------------------- REVISION HISTORY ------------------- v1.1.0 ------- This is the initial release of this document and of the API. --------------------------------------------------------------- This section will track additions, deletions and changes to the API in future revisions. Back to Table of Contents -------------------------------------------------------------------------------------- Integrating your custom applications with SecurityGateway for Exchange/SMTP -------------------------------------------------------------------------------------- SecurityGateway for Exchange/SMTP provides an XML-RPC API to manage domains, users, administrators, aliases, domain mail servers, and user verification sources. Using a standard XML-RPC client or library, customers can automate many tasks and integrate with their custom software applications. Back to Table of Contents ------------------- Intro to XML-RPC ------------------- XML-RPC is a widely adopted standard used for client and server communication that uses HTTP-Post to send Remote Procedure Calls in an easy to read XML format. Many scripting languages provide native support and there are many libraries available for most languages. The XML-RPC support in SecurityGateway for Exchange/SMTP will work with any client that conforms to the specification. SecurityGateway for Exchange/SMTP accepts a single method with a single params entry per HTTP-Post. The params entry can have multiple param entries. All param entries can have a single value and it must be of type string. The return value is a similarly encoded response with either a single fault entry or a single params entry. Here's an example of an XML-RPC request:POST /RPC2 HTTP/1.0 User-Agent: Mozilla/4.0 Host: user1.example.com Content-Type: text/xml Content-length: 223<?xml version="1.0"?> <methodCall> <methodName>securityGateway.MethodHelp</methodName> <params> <param> <value><string>CreateUser</string></value> </param> </params> </methodCall>
The example is calling MethodHelp for CreateUser. Here is an example of what would be returned from the above request by SecurityGateway for Exchange/SMTP: HTTP/1.0 200 OK Server: ALT-N SecurityGateway 1.1.0 Date: Mon, 13 Oct 2008 15:01:30 GMT MIME-Version: 1.0 Content-Type: text/xml; charset=utf-8 Content-Length: 469 Pragma: No-cache Expires: Thu, 01 Jan 1970 00:00:00 GMT Connection: close <?xml version="1.0" encoding="UTF-8"?> <methodResponse> <params><param><value> <array><data> <value> <string>CreateUser - expects an email address for a valid domain, optional parameters are 'enabled|disabled', 'name', 'comment' and 'password'</string> </value> <value> <string>Example: CreateUser newuser@dom.com enabled name 'John Smith' comment 'Some comment' password test123</string> </value> </data></array> </value></param></params> </methodResponse> The following is an example of a returned fault: <?xml version="1.0" encoding="UTF-8"?> <methodResponse> <fault><value><struct> <member> <name>faultCode</name> <value> <int>4</int> </value> </member> <member> <name>faultString</name> <value> <string>Access Denied: Logon Required</string> </value> </member> </struct></value></fault> </methodResponse> Each of the supported XML-RPC methods will be discussed in their own sections. Back to Table of Contents ------------------- XML-RPC Methods ------------------- The methods are divided into the following groups: ADMIN FUNCTIONS Logon Logout ListMethods MethodSignature MethodHelp DOMAIN FUNCTIONS CreateDomain EditDomain DeleteDomain ListDomains USER FUNCTIONS CreateUser EditUser DeleteUser ListUsers ALIAS FUNCTIONS CreateAlias EditAlias DeleteAlias ListAliases DOMAIN MAIL SERVER FUNCTIONS CreateDMS EditDMS DeleteDMS ListDMS AddDMSForDomain DeleteDMSForDomain ListDMSForDomain USER VERIFICATION SOURCE FUNCTIONS CreateUVS EditUVS DeleteUVS ListUVS AddUVSForDomain DeleteUVSForDomain ListUVSForDomain ADMINISTRATION RIGHTS FUNCTIONS AddDomainAdmin RemoveDomainAdmin ListDomainAdmins AddGlobalAdmin RemoveGlobalAdmin ListGlobalAdmins EXTERNAL ADMINISTRATOR FUNCTIONS CreateExternalAdmin EditExternalAdmin DeleteExternalAdmin Back to Table of Contents -------------------- ACCESS FUNCTIONS -------------------- These XML-RPC methods allow a user to gain access to SecurityGateway for Exchange/SMTP and retrieve information about the supported XML-RPC methods. Logon and logout are used to start and end a browser session. ListMethods, MethodSignature and MethodHelp are used for XML-RPC introspection and allow a client to discover and use methods supported by the server. Back to Table of Contents Logon(string User, string Password) This function is used to start a session with SecurityGateway for Exchange/SMTP. Parameters User - this is the email address or alias of the user. Password - this is the password of the user. Return values This function returns success if the user is able to logon or a fault otherwise. Remarks It is only necessary to logon once, unless logout is called or a session timeout occurs. Example Request <methodCall> <methodName>securityGateway.Logon</methodName> <params> <param> <value><string>admin@example.com</string></value> </param> <param> <value><string>test123</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods Logout( ) This function is used to end a session with SecurityGateway for Exchange/SMTP. Parameters None Return values This function returns success if the user is able to logout or a fault otherwise. Remarks It is only necessary to logout once. Example Request <methodCall> <methodName>securityGateway.Logout</methodName> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListMethods( ) This function is used to get a list of all the supported method names. Parameters None. Return values If successful, this function returns a string array. Otherwise it returns a fault. Remarks This method does not require logon. Example Request <methodCall> <methodName>securityGateway.ListMethods</methodName> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><string>securityGateway.ListMethods</string></value> <value><string>securityGateway.MethodSignature</string></value> <value><string>securityGateway.MethodHelp</string></value> <value><string>securityGateway.Logon</string></value> ... <value><string>securityGateway.ListUVS</string></value> <value><string>securityGateway.ListUVSForDomain</string></value> <value><string>securityGateway.AddUVSForDomain</string></value> <value><string>securityGateway.DeleteUVSForDomain</string></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods MethodSignature(string Method) This function is used to get the return and parameter types of supported methods. Parameters Method - this is the method being queried. Return values If successful, this function returns an array of strings representing the methods signature. The first string is the return type of the function and the remainder are the parameters. Parameters enclosed in [] are optional. Otherwise it returns a fault. Remarks This method does not require logon. Example Request <methodCall> <methodName>securityGateway.MethodSignature</methodName> <params><param><value> <string>CreateUser</string> </value></param></params> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><string>none</string></value> <value><string>string</string></value> <value><string>[string]</string></value> <value><string>[string string]</string></value> <value><string>[string string]</string></value> <value><string>[string string]</string></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods MethodHelp(string Method) This function returns a summary of the method and an example. Parameters Method - this is the method being queried. Return values If successful, this function returns two strings, the first is the summary and the second is an example. Otherwise, it returns a fault. Remarks This method does not require logon. Example Request <methodCall> <methodName>securityGateway.MethodHelp</methodName> <params><param> <value><string>CreateUser</string></value> </param></params> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><string>CreateUser - expects an email address for a valid domain, optional parameters are 'enabled|disabled', 'name', 'comment' and 'password'</string> </value> <value><string>Example: CreateUser newuser@dom.com enabled name 'John Smith' comment 'Some comment' password test123</string> </value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods -------------------- DOMAIN FUNCTIONS -------------------- These methods allow for creating, editing, deleting and listing of domains. The caller must be logged in as a global administrator to use these methods. Back to Table of Contents CreateDomain(string Name, ...) This function creates a domain. Parameters Name - this is the domain being created. LimitUsers - (optional) the number of users allowed to be created Password - (optional) password to be used if domain verification fails NoUvs - (optional) Specifies that no user verification source is allowed. Return values This function returns success if the domain was created or a fault otherwise. Remarks Requires global administrator rights. LimitUsers and Password are stored in the XML as a pair of strings, the first being a label and the second being a value. The labels are 'limitusers' and 'password'. See the example XML below. Example Request <methodCall> <methodName>securityGateway.CreateDomain</methodName> <params> <param><value> <string>newdomain.com</string> </value></param> <param><value> <string>limitusers</string> </value></param> <param><value> <string>50</string> </value></param> <param><value> <string>password</string> </value></param> <param><value> <string>testing123</string> </value></param> <param><value> <string>nouvs</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods EditDomain(string Name, ...) This function edits an existing domain. Parameters Name - this is the domain being edited. NewDomain - (optional) the new domain name LimitUsers - (optional) the number of users allowed to be created Password - (optional) password to be used if domain verification fails Uvs|NoUvs - (optional) Specifies whether user verification source is allowed. Return values This function returns success if the domain was edited or a fault otherwise. Remarks Requires global administrator rights. LimitUsers and Password are stored in the XML as a pair of strings, the first being a label and the second being a value. The labels are 'newdomain', 'limitusers' and 'password'. See the example XML below. Example Request <methodCall> <methodName>securityGateway.EditDomain</methodName> <params> <param><value> <string>domain.com</string> </value></param> <param><value> <string>newdomain</string> </value></param> <param><value> <string>newdomain.net</string> </value></param> <param><value> <string>limitusers</string> </value></param> <param><value> <string>75</string> </value></param> <param><value> <string>password</string> </value></param> <param><value> <string>test123</string> </value></param> <param><value> <string>nouvs</string> </value></param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteDomain(string Name) This function deletes an existing domain. Parameters Name - this is the domain being deleted. Return values This function returns success if the domain was deleted or a fault otherwise. Remarks Caller can not delete their own domain. Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.DeleteDomain</methodName> <params> <param><value> <string>domain.com</string> </value></param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListDomains( ) This function is used to get a list of the existing domains. Parameters None. Return values If successful, returns an array of domain objects. Otherwise, returns a fault. Remarks A value of -1 for MaxUsers represents no user limit. Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.ListDomains</methodName> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>177</string></value> </member> <member> <name>Name</name> <value><string>test2.com</string></value> </member> <member> <name>NumberOfUsers</name> <value><string>4</string></value> </member> <member> <name>MaxUsers</name> <value><string>150</string></value> </member> <member> <name>NoUvs</name> <value><string>0</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>1</string></value> </member> <member> <name>Name</name> <value><string>test.int</string></value> </member> <member> <name>NumberOfUsers</name> <value><string>3</string></value> </member> <member> <name>MaxUsers</name> <value><string>-1</string></value> </member> <member> <name>NoUvs</name> <value><string>0</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods ----------------- USER FUNCTIONS ----------------- These methods allow for creating, editing, deleting and listing of users. The caller must be either a global administrator or administrator of the user's domain. Back to Table of Contents CreateUser(string Email, ...) This function creates a user in a specific domain. Parameters Email - this is the mailbox and domain of the new user. Enabled|Disabled - (optional) to enable/disable the new account Name - (optional) real name of the new user Comment - (optional) text based information about the new user Password - (optional) the new user's password Return values This function returns success if the user was created or a fault otherwise. Remarks Requires domain administrator rights. Name, Comment and Password are stored in the XML as a pair of strings, the first being a label and the second being a value. The labels are 'name', 'comment' and 'password'. See the example XML below. Example Request <methodCall> <methodName>securityGateway.CreateUser</methodName> <params> <param> <value><string>newuser@domain.com</string></value> </param> <param> <value><string>enabled</string></value> </param> <param> <value><string>name</string></value> </param> <param> <value><string>John Smith</string></value> </param> <param> <value><string>comment</string></value> </param> <param> <value><string>Traveling Salesman</string></value> </param> <param> <value><string>password</string></value> </param> <param> <value><string>testing123</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods EditUser(string Email, ...) This function edits an existing user. Parameters Email - this is the mailbox and domain of the user. Enabled|Disabled - (optional) to enable/disable the account NewMailbox - (optional) new email of the user Name - (optional) new real name of the user Comment - (optional) new text based information about the user Password - (optional) the user's new password Return values This function returns success if the email was edited or a fault otherwise. Remarks Requires domain administrator rights. NewMailbox, Name, Comment and Password are stored in the XML as a pair of strings, the first being a label and the second being a value. The labels for this method are 'newmailbox', 'name', 'comment' and 'password'. See the example XML below. Example Request <methodCall> <methodName>securityGateway.EditUser</methodName> <params> <param> <value><string>user@domain.com</string></value> </param> <param> <value><string>enabled</string></value> </param> <param> <value><string>newmailbox</string></value> </param> <param> <value><string>johns@domain.com</string></value> </param> <param> <value><string>name</string></value> </param> <param> <value><string>John Smith</string></value> </param> <param> <value><string>comment</string></value> </param> <param> <value><string>Traveling Salesman</string></value> </param> <param> <value><string>password</string></value> </param> <param> <value><string>testing123</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteUser(string Email) This function deletes an existing user. Parameters Email - this is the mailbox being deleted. Return values This function returns success if the user was deleted or a fault otherwise. Remarks Requires domain administrator rights. The caller can not delete their own account. Example Request <methodCall> <methodName>securityGateway.DeleteUser</methodName> <params> <param> <value><string>user@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListUsers(string Domain) This function is used to get a list of users for an existing domain. Parameters Domain - the domain that is to be queried. Return values If successful, returns an array of user objects. Otherwise, returns a fault. Remarks Requires domain administrator rights. Example Request <methodCall> <methodName>securityGateway.ListUsers</methodName> <params> <param> <value><string>domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> <array><data><value> <struct> <member> <name>Id</name> <value><string>725</string></value> </member> <member> <name>IsEnabled</name> <value><string>1</string></value> </member> <member> <name>MailBox</name> <value><string>joem</string></value> </member> <member> <name>Domain</name> <value><string>test2.com</string></value> </member> <member> <name>RealName</name> <value><string>Joe Montana</string></value> </member> <member> <name>Comment</name> <value><string></string></value> </member> <member> <name>IsGlobalAdmin</name> <value><string>0</string></value> </member> <member> <name>IsDomainAdmin</name> <value><string>0</string></value> </member> </struct> </value> <value> <struct> <member> <name>Id</name> <value><string>723</string></value> </member> <member> <name>IsEnabled</name> <value><string>0</string></value> </member> <member> <name>MailBox</name> <value><string>joen</string></value> </member> <member> <name>Domain</name> <value><string>test2.com</string></value> </member> <member> <name>RealName</name> <value><string>Joe Namath</string></value> </member> <member> <name>Comment</name> <value><string></string></value> </member> <member> <name>IsGlobalAdmin</name> <value><string>0</string></value> </member> <member> <name>IsDomainAdmin</name> <value><string>0</string></value> </member> </struct> </value></data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods ------------------- ALIAS FUNCTIONS ------------------- These methods allow for creating, editing, deleting and listing of aliases. The caller must be either a global administrator or administrator of the user's domain. Back to Table of Contents CreateAlias(string Email, string Alias) This function creates an alias for the specified email. Parameters Email - this is the mailbox and domain of the user Alias - this is the mailbox and domain of the alias to be created Return values This function returns success if the alias was created or a fault otherwise. Remarks Requires domain administrator rights. Example Request <methodCall> <methodName>securityGateway.CreateAlias</methodName> <params> <param> <value><string>user@domain.com</string></value> </param> <param> <value><string>alias@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods EditAlias(string Alias, string NewAlias) This function edits an existing alias. Parameters Alias - this is the mailbox and domain of an alias NewAlias - this is the mailbox and domain of a new alias Return values This function returns success if the alias was edited or a fault otherwise. Remarks Requires domain administrator rights. Example Request <methodCall> <methodName>securityGateway.EditAlias</methodName> <params> <param> <value><string>alias@domain.com</string></value> </param> <param> <value><string>newalias@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteAlias(string Alias) This function deletes an existing alias. Parameters Alias - this is the alias being deleted. Return values This function returns success if the alias was deleted or a fault otherwise. Remarks Requires domain administrator rights. Example Request <methodCall> <methodName>securityGateway.DeleteAlias</methodName> <params> <param> <value><string>alias@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListAliases(string Email) This function is used to get a list of aliases for an existing user. Parameters Email - the email that is to be queried. Return values If successful, returns a string array. Otherwise, returns a fault. Remarks Requires domain administrator rights. Example Request <methodCall> <methodName>securityGateway.ListAliases</methodName> <params> <param> <value><string>user@dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>1</string></value> </member> <member> <name>Address</name> <value><string>admin@test.int</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>1</string></value> </member> <member> <name>Address</name> <value><string>sgdeveloper@test.int</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods ------------------------------------ DOMAIN MAIL SERVER FUNCTIONS ------------------------------------ These methods allow for creating, editing, deleting and listing of domain mail servers. The caller must be a global administrator to use these methods. Back to Table of Contents CreateDMS(string Name, string Host, ...) This function creates a domain mail server entry in the DB. Parameters Name - the name of the Domain Mail Server. Host - the host name or IP address of the server Default - (optional) enables the DMS as a default server Port - (optional) the port to use on the server (default is 25) RequireSMTPAuth - (optional) specifies a logon and password must be used Logon - (Required Auth) specifies the logon name to use Password - (Required Auth) specifies the password to use Return values This function returns success if the DMS was created or a fault otherwise. Remarks Requires global administrator rights. Port is stored in the XML as a pair of strings, the first is the label 'port' followed by the port number to use. Required Auth is stored in the XML as 3 strings, the first is the label 'requireauth', the second is the logon name to use, the third is the password to use. See the example XML below. Example Request <methodCall> <methodName>securityGateway.CreateDMS</methodName> <params> <param><value>test2</value></param> <param><value>123.45.67.89</value></param> <param><value>port</value></param> <param><value>1234</value></param> <param><value>requiresmtpauth</value></param> <param><value>admin</value></param> <param><value>adminpword</value></param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods EditDMS(string ID, ...) This function edits an existing domain mail server. Parameters ID - the ID of the Domain Mail Server. Name - (optional) the name of the Domain Mail Server. Host - (optional) the host name or IP address of the server Default|NotDefault - (optional) enables|disables the DMS as a default server Port - (optional) the port to use on the server (default 25) NoAuth - (optional) specifies no logon or password is needed RequireSMTPAuth - (optional) specifies a logon and password must be used Logon - (Required Auth) specifies the logon name to use Password - (Required Auth) specifies the password to use Return values This function returns success if the DMS was edited or a fault otherwise. Remarks Requires global administrator rights. Name, host and port are stored in the XML as a pair of strings, the first is the label, followed by the value. Required Auth is stored in the XML as 3 strings, the first is the label 'requireauth', the second is the logon name to use, the third is the password to use. See the example XML below. The NoAuth option will clear previously saved logon and password information. Example Request <methodCall> <methodName>securityGateway.CreateDMS</methodName> <params> <param><value>12</value></param> <param><value>name</value></param> <param><value>test2</value></param> <param><value>host</value></param> <param><value>123.45.67.89</value></param> <param><value>port</value></param> <param><value>1234</value></param> <param><value>requiresmtpauth</value></param> <param><value>admin</value></param> <param><value>adminpword</value></param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteDMS(string ID) This function deletes an existing domain mail server. Parameters ID - the ID of the Domain Mail Server. Return values This function returns success if the DMS was deleted or a fault otherwise. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.DeleteDMS</methodName> <params> <param> <value><string>12</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListDMS( ) This function is used to get a list of all domain mail servers. Parameters None Return values If successful, returns an array of DMS objects. Otherwise, returns a fault. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.ListDMS</methodName> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>2</string></value> </member> <member> <name>Name</name> <value><string>Local Mail Server</string></value> </member> <member> <name>Host</name> <value><string>localhost</string></value> </member> <member> <name>Port</name> <value><string>25</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>6</string></value> </member> <member> <name>Name</name> <value><string>Local Mail Server</string></value> </member> <member> <name>Host</name> <value><string>localhost</string></value> </member> <member> <name>Port</name> <value><string>2525</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods AddDMSForDomain(string ID, string Domain) This function links a domain mail server entry to a domain. Parameters ID - the ID of the Domain Mail Server. Domain - the domain to associate with the DMS. Return values This function returns success if the DMS was associated to the domain or a fault otherwise. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.AddDMSForDomain</methodName> <params> <param> <value><string>17</string></value> </param> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteDMSForDomain(string ID, string Domain) This function unlinks a domain mail server entry from a domain. Parameters ID - the ID of the Domain Mail Server. Domain - the domain to associate with the DMS. Return values Returns success if the DMS and domain were unlinked or a fault otherwise. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.DeleteDMSForDomain</methodName> <params> <param> <value><string>17</string></value> </param> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListDMSForDomain(string Domain) This function lists the domain mail servers for a specific domain. Parameters Domain - the domain to be listed. Return values This function returns an array of DMS structures or a fault otherwise. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.ListDMSForDomain</methodName> <params> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>2</string></value> </member> <member> <name>Name</name> <value><string>Local Mail Server</string></value> </member> <member> <name>Host</name> <value><string>localhost</string></value> </member> <member> <name>Port</name> <value><string>25</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>6</string></value> </member> <member> <name>Name</name> <value><string>Local Mail Server</string></value> </member> <member> <name>Host</name> <value><string>localhost</string></value> </member> <member> <name>Port</name> <value><string>2525</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods ------------------------------------------ USER VERIFICATION SOURCE FUNCTIONS ------------------------------------------ These methods allow for creating, editing, deleting and listing of user verification sources. The caller must be a global administrator to use these methods. Back to Table of Contents CreateUVS(string Name, string Host, string Port, string Method, ...) This function creates a user verification source. Parameters Name - the name of the User Verification Source Host - the host name or IP address of the server Port - the port to use on the server Method - the verification method used (AD, LDAP, SMTP, or Minger) Default - (optional) enables the UVS as a default server RequireAuth - (optional) specifies a logon and password must be used Logon - (Required Auth) specifies the logon name to use Password - (Required Auth) specifies the password to use Return values This function returns success if the UVS was created or a fault otherwise. Remarks Requires global administrator rights. Required Auth is stored in the XML as 3 strings, the first is the label 'requireauth', the second is the logon name to use, the third is the password to use. See the example XML below. Example Request <methodCall> <methodName>securityGateway.CreateDMS</methodName> <params> <param><value>test3</value></param> <param><value>123.45.67.89</value></param> <param><value>1234</value></param> <param><value>SMTP</value></param> <param><value>requireauth</value></param> <param><value>admin</value></param> <param><value>adminpword</value></param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods EditUVS(string ID, ...) This function edits an existing user verification source. Parameters ID - the ID of the User Verification Source. Name - (optional) the name of the UVS Host - (optional) the host name or IP address of the server Port - (optional) the port to use on the server Method - the verification method used (AD, LDAP, SMTP, or Minger) Default|NotDefault - (optional) enables|disables the UVS as a default server NoAuth - (optional) specifies no logon or password is needed RequireAuth - (optional) specifies a logon and password must be used Logon - (Required Auth) specifies the logon name to use Password - (Required Auth) specifies the password to use Return values This function returns success if the UVS was edited or a fault otherwise. Remarks Requires global administrator rights. Name, host, port and method are passed as a pair of strings, the first is the label, followed by the value. Labels are 'name', 'host', 'port' and 'authmethod'. Required Auth is stored in the XML as 3 strings, the first is the label 'requireauth', the second is the logon name to use, the third is the password to use. See the example XML below. The NoAuth option will clear previously saved logon and password information. Example Request <methodCall> <methodName>securityGateway.CreateDMS</methodName> <params> <param><value>12</value></param> <param><value>name</value></param> <param><value>test3</value></param> <param><value>host</value></param> <param><value>123.45.67.89</value></param> <param><value>port</value></param> <param><value>1234</value></param> <param><value>authmethod</value></param> <param><value>SMTP</value></param> <param><value>requireauth</value></param> <param><value>admin</value></param> <param><value>adminpword</value></param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteUVS(string ID) This function deletes an existing user verification source. Parameters ID - the ID of the User Verification Source. Return values This function returns success if the UVS was deleted or a fault otherwise. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.DeleteUVS</methodName> <params> <param> <value><string>17</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListUVS( ) This function is used to get a list of user verification sources. Parameters None Return values If successful, returns an array of UVS objects. Otherwise, returns a fault. Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.ListUVS</methodName> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>8</string></value> </member> <member> <name>Name</name> <value><string>test3</string></value> </member> <member> <name>Host</name> <value><string>123.45.67.89</string></value> </member> <member> <name>Port</name> <value><string>1234</string></value> </member> <member> <name>Type</name> <value><string>SMTP</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>11</string></value> </member> <member> <name>Name</name> <value><string>test3</string></value> </member> <member> <name>Host</name> <value><string>123.45.67.89</string></value> </member> <member> <name>Port</name> <value><string>1234</string></value> </member> <member> <name>Type</name> <value><string>SMTP</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods AddUVSForDomain(string ID, string Domain) This function links a user verification source to a domain. Parameters ID - the ID of the User Verification Source Domain - the domain to associate with the UVS Return values Requires global administrator rights. This function returns success if the UVS was associated to the domain or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.AddUVSForDomain</methodName> <params> <param> <value><string>17</string></value> </param> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteUVSForDomain(string ID, string Domain) This function unlinks a user verification source from a domain. Parameters ID - the ID of the User Verification Source Domain - the domain to disassociate from the UVS Return values Requires global administrator rights. This function returns success if the UVS was disassociated from the domain or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.DeleteUVSForDomain</methodName> <params> <param> <value><string>17</string></value> </param> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListUVSForDomain(string Domain) This function lists the user verification source for a domain. Parameters Domain - the domain to be listed Return values Requires global administrator rights. This function returns an array of UVS structures or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.ListUVSForDomain</methodName> <params> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>8</string></value> </member> <member> <name>Name</name> <value><string>test3</string></value> </member> <member> <name>Host</name> <value><string>123.45.67.89</string></value> </member> <member> <name>Port</name> <value><string>1234</string></value> </member> <member> <name>Type</name> <value><string>SMTP</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>11</string></value> </member> <member> <name>Name</name> <value><string>test3</string></value> </member> <member> <name>Host</name> <value><string>123.45.67.89</string></value> </member> <member> <name>Port</name> <value><string>1234</string></value> </member> <member> <name>Type</name> <value><string>SMTP</string></value> </member> <member> <name>RequireLogon</name> <value><string>0</string></value> </member> <member> <name>Default</name> <value><string>0</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods Back to Table of Contents -------------------------------------- ADMINISTRATOR RIGHTS FUNCTIONS -------------------------------------- These methods allow for assigning and removing administrator rights. The caller must be a global administrator to use these methods. Back to Table of Contents AddDomainAdmin(string User, string Domain) This function assigns domain administrator rights to the user. Parameters User - the user that will administer the domain Domain - the domain to be administered Return values Requires global administrator rights. This function returns success if the user was given domain administration rights or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.AddDomainAdmin</methodName> <params> <param> <value><string>admin@dom.com</string></value> </param> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods RemoveDomainAdmin(string User, string Domain) This function removes domain administrator rights from the user. Parameters User - the user that will be removed as a domain administrator Domain - the domain the administrator will be removed from Return values Requires global administrator rights. This function returns success if the domain administration rights were removed or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.RemoveDomainAdmin</methodName> <params> <param> <value><string>admin@dom.com</string></value> </param> <param> <value><string>dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> ListDomainAdmins(string Domain, ...) This function lists users that have administrator rights for the domain. Parameters Domain - the domain that is being listed LocalOrExternal - (optional) limits administrators listed, 'local' or 'external' defaults to all domain administrators if not included Return values Requires domain administrator rights. This function returns an array of domain administrator objects or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.ListDomainAdmins</methodName> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>8</string></value> </member> <member> <name>Email</name> <value><string>admin@dom.com</string></value> </member> <member> <name>Name</name> <value><string>Joe Namath</string></value> </member> <member> <name>Enabled</name> <value><string>1</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>132</string></value> </member> <member> <name>Email</name> <value><string>admin@freedom.com</string></value> </member> <member> <name>Name</name> <value><string>Terry Bradshaw</string></value> </member> <member> <name>Enabled</name> <value><string>1</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods Back to XML-RPC Methods AddGlobalAdmin(string User) This function assigns global administrator rights to the user. Parameters User - the user that will become a global administrator Return values Requires global administrator rights. This function returns success if the user was given global administration rights or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.AddGlobalAdmin</methodName> <params> <param> <value><string>admin@dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods RemoveGlobalAdmin(string User) This function removes global administrator rights from the user. Parameters User - the user that will be removed as a domain administrator Return values Requires global administrator rights. This function returns success if the global administration rights were removed or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.RemoveGlobalAdmin</methodName> <params> <param> <value><string>admin@dom.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods ListGlobalAdmins(string LocalOrExternal) This function lists users that have global administrator rights. Parameters LocalOrExternal - (optional) limits administrators listed, 'local' or 'external' defaults to all global administrators if not included Return values Requires global administrator rights. This function returns an array of global administrator objects or a fault otherwise. Remarks None. Example Request <methodCall> <methodName>securityGateway.ListGlobalAdmins</methodName> </methodCall> Example Response <methodResponse> <params><param><value> <array><data> <value><struct> <member> <name>Id</name> <value><string>1</string></value> </member> <member> <name>Email</name> <value><string>gadmin@host.com</string></value> </member> <member> <name>Name</name> <value><string>Troy Aikman</string></value> </member> <member> <name>Enabled</name> <value><string>1</string></value> </member> </struct></value> <value><struct> <member> <name>Id</name> <value><string>12</string></value> </member> <member> <name>Email</name> <value><string>gadmin@freedom.com</string></value> </member> <member> <name>Name</name> <value><string>Bart Starr</string></value> </member> <member> <name>Enabled</name> <value><string>1</string></value> </member> </struct></value> </data></array> </value></param></params> </methodResponse> Back to XML-RPC Methods ------------------------------------------ EXTERNAL ADMINISTRATOR FUNCTIONS ------------------------------------------ These methods allow for creating, editing and deleting of external administrators. The caller must be a global administrator to use these functions. Back to Table of Contents CreateExternalAdmin(string Email, ...) This function creates an external administrator. Parameters Email - this is the mailbox and domain of the external administrator. Enabled|Disabled - (optional) to enable/disable the account Name - (optional) real name of the user Comment - (optional) text based information about the administrator Password - (optional) the new administrator's password Return values This function returns success if the administrator was created or a fault otherwise. Remarks Requires global administrator rights. Name, Comment and Password are stored in the XML as a pair of strings, the first being a label and the second being a value. The labels are 'name', 'comment' and 'password'. See the example XML below. Example Request <methodCall> <methodName>securityGateway.CreateExternalAdmin</methodName> <params> <param> <value><string>newuser@domain.com</string></value> </param> <param> <value><string>enabled</string></value> </param> <param> <value><string>name</string></value> </param> <param> <value><string>John Smith</string></value> </param> <param> <value><string>comment</string></value> </param> <param> <value><string>Traveling Salesman</string></value> </param> <param> <value><string>password</string></value> </param> <param> <value><string>testing123</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods EditExternalAdmin(string Email, ...) This function edits an existing external administrator. Parameters Email - this is the mailbox and domain of the administrator. Enabled|Disabled - (optional) to enable/disable the account NewMailbox - (optional) new email of the administrator Name - (optional) new real name of the administrator Comment - (optional) new text based information about the administrator Password - (optional) the administrator's new password Return values This function returns success if the account was edited or a fault otherwise. Remarks Requires global administrator rights. NewMailbox, Name, Comment and Password are stored in the XML as a pair of strings, the first being a label and the second being a value. The labels for this method are 'newmailbox', 'name', 'comment' and 'password'. See the example XML below. Example Request <methodCall> <methodName>securityGateway.EditExternalAdmin</methodName> <params> <param> <value><string>user@domain.com</string></value> </param> <param> <value><string>enabled</string></value> </param> <param> <value><string>newmailbox</string></value> </param> <param> <value><string>johns@domain.com</string></value> </param> <param> <value><string>name</string></value> </param> <param> <value><string>John Smith</string></value> </param> <param> <value><string>comment</string></value> </param> <param> <value><string>Traveling Salesman</string></value> </param> <param> <value><string>password</string></value> </param> <param> <value><string>testing123</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods DeleteExternalAdmin(string Email) This function deletes an existing external administrator. Parameters Email - this is the mailbox being deleted. Return values This function returns success if the administrator was deleted or a fault otherwise. Remarks Requires global administrator rights. The caller can not delete their own account. Example Request <methodCall> <methodName>securityGateway.DeleteExternalAdmin</methodName> <params> <param> <value><string>user@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param><value> </value></param></params> </methodResponse> Back to XML-RPC Methods -------------------------------- XML-RPC VBSCRIPT SAMPLES -------------------------------- The following samples demonstrate the API provided by SecurityGateway for Exchange/SMTP. All of the sample scripts use the PocketXML-RPC client COM component. More detailed information about PocketXML-RPC can be found here, including the binary and source. Before using the samples, this component needs to be downloaded and installed. Sample scripts by method: Proxy Initialization ListMethods/MethodSignature/MethodHelp Logon/Logout Create/Edit/Delete/List VBScript to initialize the PocketXML-RPC proxy Dim uData(9) 'string endpointURL uData(0) = "http://127.0.0.1:4000/SecurityGateway.dll?view=xmlrpc" 'string methodNamePrefix uData(1) = "securityGateway." 'string serverUsername uData(2) = "" 'string serverPassword uData(3) = "" 'string httpProxyServer uData(4) = "" 'long httpProxyPort uData(5) = 0 'string proxyUsername uData(6) = "" 'string proxyPassword uData(7) = "" 'long timeoutInSeconds uData(8) = 60 '--Initialize the Proxy COM object Set p = f.Proxy(uData(0), uData(1), uData(2), uData(3), uData(4), uData(5), uData(6), uData(7), uData(8)) Back to XML-RPC VBScript Samples VBScript for ListMethods/MethodSignature/MethodHelp Dim f, p, r, q Set f = CreateObject("pocketXMLRPC.Factory") '--Alternate method for initializing the Proxy COM object Set p = f.Proxy("http://127.0.0.1:4000/SecurityGateway.dll?view=xmlrpc", "securityGateway.","","","",0,"","",30) '--Reflection functions - ListMethods, MethodSignature, MethodHelp r = p.ListMethods() q = "ListMethods" & vbCrLf If (IsEmpty(r)) Then MsgBox "ListMethods - error" Else For Each x in r q = q & x & vbCrLf Next MsgBox q End If r = p.MethodSignature("CreateUser") q = "MethodSignature" & vbCrLf If (IsEmpty(r)) Then MsgBox "MethodSignature - error" Else For Each x in r q = q & x & " " Next q = q & vbCrLf MsgBox q End If r = p.MethodHelp("CreateUser") q = "MethodHelp" & vbCrLf If (IsEmpty(r)) Then MsgBox "MethodSignature - error" Else For Each x in r q = q & x & " " Next q = q & vbCrLf MsgBox q End If Back to XML-RPC VBScript Samples VBScript for Logon/Logout Dim f, p Set f = CreateObject("pocketXMLRPC.Factory") '--Change the address and port below to match your system Set p = f.Proxy("http://127.0.0.1:4000/SecurityGateway.dll?view=xmlrpc", "securityGateway.", "", "", "", 0, "", "", 30) '--Change the user and password below to match a global admin on your system p.Logon "admin@company.mail", "testing123" '--Call some methods that require logon p.Logout Back to XML-RPC VBScript Samples VBScript for Create/Edit/Delete/List Dim f, p, r, q Set f = CreateObject("pocketXMLRPC.Factory") '--Change the address and port below to match your system Set p = f.Proxy("http://127.0.0.1:4000/SecurityGateway.dll?view=xmlrpc", "securityGateway.","","","",0,"","",30) '--Change the user and password below to match a global admin on your system p.Logon "admin@company.mail", "testing123" '--Create a domain, add 5 mailboxes, list the mailboxes and delete 1 mailbox p.CreateDomain "test2.com", "limitusers", "150", "password", "rockit" p.CreateUser "joen@test2.com", "enabled", "name", "Joe Namath", "password", "racecar", "comment", "3x League MVP and hall of famer" p.CreateUser "terryb@test2.com", "enabled", "name", "Terry Bradshaw", "password", "racecar", "comment", "Great guy and hall of famer" p.CreateUser "Joem@test2.com", "enabled", "name", "Joe Montana", "password", "racecar", "comment", "Nice guy and hall of famer" p.CreateUser "troya@test2.com", "disabled", "name", "Troy Aikman", "password", "racecar", "comment", "Good ole boy and hall of famer" p.CreateUser "tomb@test2.com", "disabled", "name", "Tom Brady", "password", "racecar", "comment", "Cheater" q = "Domain test2.com created with 5 users" & vbCrLf r = p.ListUsers("test2.com") q = q & "ListUsers test2.com" & vbCrLf If IsEmpty(r) Then MsgBox "empty" Else For Each y in r If IsObject(y) Then q = q & "ID: " & y.Id & " Enabled: " & y.IsEnabled & " MailBox: " & y.MailBox & " Domain: " & y.Domain q = q & " RealName: " & y.RealName & " Comment: " & y.Comment & vbCrLf Else MsgBox "not object" End If Next End If p.DeleteUser "tomb@test2.com" q = q & "User tomb@test2.com deleted" MsgBox q '--Create another domain and list all of the domains p.CreateDomain "test3.com", "limitusers", "250", "password", "rockme", "nouvs" r = p.ListDomains() q = "ListDomains" & vbCrLf If IsEmpty(r) Then MsgBox "empty" Else For Each y in r If IsObject(y) Then q = q & "ID: " & y.Id & " Name: " & y.Name & " Users: " & y.NumberOfUsers & " MaxUsers: " & y.MaxUsers q = q & " NoUvs: " & y.NoUvs & vbCrLf s = y.ID Else MsgBox "not object" End If Next MsgBox q End If Back to XML-RPC VBScript Samples Back to Table of Contents