-----------
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 XML-RPC White and Black List functions Sample VBScripts ------------------- REVISION HISTORY ------------------- v1.1.2 ------- Revisions, Deletions and Major Fixes. --------------------------------------------------------------- Functions to handle White and Black lists have been added to the API and descriptions of the functions have been added to this doc. v1.1.1 ------- Revisions, Deletions and Major Fixes. --------------------------------------------------------------- All UVS authentication types are now fully supported. Required and optional parameters for LDAP, AD, SMTP and Minger are handled in the same manner as the GUI. Creating an alias with a new domain name now results in the domain being created, if possible. This can also occur during editing of an alias. 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 libraries are 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> In general, the format of the messages can be left to an XML-RPC client or library. Examples using a client COM component are provide in the Sample VBScripts section. An example XML request and response is provided for all supported API methods. Fault responses will look like the example given above although the fault code and string may differ. 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 ListDomainsForDMS USER VERIFICATION SOURCE FUNCTIONS CreateUVS EditUVS DeleteUVS ListUVS AddUVSForDomain DeleteUVSForDomain ListUVSForDomain ListDomainsForUVS ADMINISTRATION RIGHTS FUNCTIONS AddDomainAdmin RemoveDomainAdmin ListDomainAdmins AddGlobalAdmin RemoveGlobalAdmin ListGlobalAdmins EXTERNAL ADMINISTRATOR FUNCTIONS CreateExternalAdmin EditExternalAdmin DeleteExternalAdmin WHITE AND BLACK LIST FUNCTIONS GetUserWhitelist GetDomainWhitelist GetGlobalWhitelist AddToUserWhitelist AddToDomainWhitelist AddToGlobalWhitelist DeleteFromUserWhitelist DeleteFromDomainWhitelist DeleteFromGlobalWhitelist GetUserBlacklist GetDomainBlacklist GetGlobalBlacklist AddToUserBlacklist AddToDomainBlacklist AddToGlobalBlacklist DeleteFromUserBlacklist DeleteFromDomainBlacklist DeleteFromGlobalBlacklist 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. . . the email address or alias of the user
Password. . . 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>0</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 log out 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>0</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 followed by 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. . . the domain to be created
LimitUsers <Max Users>. . . (optional) the number of users allowed to be created
Password <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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods EditDomain(string Name, ...) This function edits an existing domain. Parameters
Name. . . the domain being edited
NewDomain <new Domain>. . . (optional) the new domain name
LimitUsers <Max Users>. . . (optional) the number of users allowed to be created
Password <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 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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteDomain(string Name) This function deletes an existing domain. Parameters
Domain. . . 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>0</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. Domain objects contain the following:
IdThe internal ID of the Domain
NameThe domain name
NumberOfUsersThe number of users currently in the domain
MaxUsersThe maximum number of users allowed for the domain
NoUVS1 if no UVS is to be used for this domain, 0 otherwise
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. . . the email address of the new user
Enabled|Disabled. . . (optional) to enable/disable the account
Name <Real Name>. . . (optional) real name of the user
Comment <Comment>. . . (optional) text based information about the user
Password <Password>. . . (optional) the password for the new user
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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods EditUser(string Email, ...) This function edits an existing user. Parameters
Email. . . the email address of the user
Enabled|Disabled. . . (optional) to enable/disable the account
NewMailbox <new Mailbox>. . . (optional) the new email address of the user
Name <new Real Name>. . . (optional) the new real name
Comment <new Comment>. . . (optional) a new comment or note
Password <new Password>. . . (optional) the new password for the user
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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteUser(string Email) This function deletes an existing user. Parameters
Email. . . the email of the user 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>0</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 being queried
Return values If successful, returns an array of user objects. Otherwise, returns a fault. User objects contain the following:
IdThe internal ID of the User
IsEnabled1 if the mailbox is enabled, 0 otherwise
MailBoxThe mailbox portion of the email address
DomainThe domain portion of the email address
RealNameThe name of the user associated with this mailbox
CommentA description of the mailbox
IsGlobalAdmin1 if the user has global administrative rights, 0 otherwise
IsDomainAdmin1 if the user has domain administrative rigths, 0 otherwise
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. . . the email address of the user
Alias. . . 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. Requires global administrator rights if the domain of the alias does not exist. If the domain does not exist it will be created. 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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods EditAlias(string Alias, string NewAlias) This function edits an existing alias. Parameters
Alias. . . the alias to be replaced
NewAlias <new Alias>. . . the new alias
Return values This function returns success if the alias was edited or a fault otherwise. Remarks Requires domain administrator rights. Requires global administrator rights if the domain of the new alias does not exist. If the domain does not exist it will be created. 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>0</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>0</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 address being queried
Return values If successful, returns an array of alias objects. Otherwise, returns a fault. Alias objects contain the following:
IdThe internal ID of the User
AddressThe alias in email address format
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 <Port Number>. . . (optional) the port to use on the server (default is 25)
RequireSMTPAuth <Logon> <Password>. . . (optional) specifies a logon and password must be used
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>0</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 <new Name>. . . (optional) the new name of the Domain Mail Server
Host <new Host>. . . (optional) the new host name or IP address of the server
Default|NotDefault. . . (optional) enables|disables the DMS as a default server
Port <new Port>. . . (optional) the new port to use on the server
NoAuth. . . (optional) turns off authentication, clears any logon or password
RequireSMTPAuth <Logon> <Password>. . . (optional) specifies a logon and password must be used
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>0</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>0</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. DMS objects contain the following:
IdThe internal ID of the DMS
NameThe name of the DMS
HostThe IP address or URL of the DMS
PortThe port to use
RequireSMTPAuth1 if the DMS requires user authentication
LogonUserThe logon user name if RequireSMTPAuth is set
Default1 if the DMS is to be used as a default server, 0 otherwise
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>0</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>0</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. . . this is the domain being queried
Return values This function returns an array of DMS structures or a fault otherwise. DMS objects contain the following:
IdThe internal ID of the DMS
NameThe name of the DMS
HostThe IP address or URL of the DMS
PortThe port to use
RequireSMTPAuth1 if the DMS requires user authentication
LogonUserThe logon user name if RequireSMTPAuth is set
Default1 if the DMS is to be used as a default server, 0 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
ListDomainsForDMS(string Domain) This function lists the domains for a specific domain mail server. Parameters
ID. . . the ID of the Domain Mail Server
Return values This function returns an array of domain structures or a fault otherwise. Domain objects contain the following:
IdThe internal ID of the Domain
NameThe domain name
NumberOfUsersThe number of users currently in the domain
MaxUsersThe maximum number of users allowed for the domain
NoUVS1 if no UVS is to be used for this domain, 0 otherwise
Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.ListDomainsForDMS</methodName> <params> <param> <value><string>17</string></value> </param> </params> </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 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
Logon <New Logon>. . . (optional) specifies the logon name to use
Password <New Password>. . . (optional) specifies the password to use
SearchFilter <New Search Filter>. . . (optional, AD/Exchange and LDAP) specifies the search filter to use
BaseDN <New Base DN>. . . (optional, LDAP only) specifies the starting point in the Directory Information Tree
SearchScope <New Search Scope>. . . (optional, LDAP only) can be 'base', 'onelevel' or 'subtree'
Return values This function returns success if the UVS was created or a fault otherwise. Remarks Requires global administrator rights. UVS using the SMTP or AD/Exchange method can have an optional 'logon' and 'password'. The AD/Exchange method also accepts an optional 'search filter'. UVS using the Minger method accept an optional 'password' only. UVS using the LDAP method require a and accept an optional 'logon' (Distinguished Name), 'password', 'base entry DN', 'search filter' and 'search scope'. All authentication methods accept the 'default' parameters. The optional 'default' parameter is passed as a single value. Optional parameters are stored in the XML request as a pair of strings, a label and the value. Labels are 'logon', 'password', 'searchfilter', 'basedn' and 'searchscope'. Values for 'searchscope' are 'base', 'onelevel' and 'subtree'. See the example XML below. Example Request (SMTP) <methodCall> <methodName>securityGateway.CreateUVS</methodName> <params> <param><value>test8</value></param> <param><value>123.45.67.89</value></param> <param><value>666</value></param> <param><value>SMTP</value></param> <param><value>default</value></param> <param><value>logon</value></param> <param><value>someone</value></param> <param><value>password</value></param> <param><value>somepass</value></param> </params> </methodCall> (Minger) <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>Minger</value></param> <param><value>default</value></param> <param><value>password</value></param> <param><value>adm1npw0rd</value></param> </params> </methodCall> (AD) <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>AD</value></param> <param><value>logon</value></param> <param><value>CN=admin,OU=it,DC=dom,DC=com</value></param> <param><value>password</value></param> <param><value>adminPa55word</value></param> <param><value>searchfilter</value></param> <param><value>(&(|(objectclass=user)(objectclass=group)(objectclass=publicFolder))(|(mail=$EMAIL$)(proxyAddresses=SMTP:$EMAIL$)))</value></param> </params> </methodCall> (LDAP) <methodCall> <methodName>securityGateway.CreateUVS</methodName> <params> <param><value>test12</value></param> <param><value>1.234.56.78</value></param> <param><value>1111</value></param> <param><value>LDAP</value></param> <param><value>logon</value></param> <param><value>admin</value></param> <param><value>searchscope</value></param> <param><value>onelevel</value></param> <param><value>searchfilter</value></param> <param><value>ima search filter</value></param> <param><value>basedn</value></param> <param><value>oc=ima.base ic=dist uc=name</value></param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</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 <New Name>. . . (optional) the name of the UVS
Host <New Host>. . . (optional) the host name or IP address of the server
Port <New Port>. . . (optional) the port to use on the server
Method <New Method>. . . the verification method used (AD, LDAP, SMTP, or Minger)
Default|NotDefault. . . (optional) enables|disables the UVS as a default server
NoAuth. . . (optional) turns off authentication, clears any logon or password
Logon <New Logon>. . . (optional) specifies the logon name to use
Password <New Password>. . . (optional) specifies the password to use
SearchFilter <New Search Filter>. . . (optional, AD/Exchange and LDAP) specifies the search filter to use
BaseDN <New Base DN>. . . (optional, LDAP only) specifies the starting point in the Directory Information Tree
SearchScope <New Search Scope>. . . (optional, LDAP only) can be 'base', 'onelevel' or 'subtree'
Return values This function returns success if the UVS was edited or a fault otherwise. Remarks Requires global administrator rights. UVS using the SMTP or AD/Exchange method can have an optional 'logon' and 'password'. The AD/Exchange method also accepts an optional 'search filter'. UVS using the Minger method accept an optional 'password' only. UVS using the LDAP method require a and accept an optional 'logon' (Distinguished Name), 'password', 'base entry DN', 'search filter' and 'search scope'. All authentication methods accept the 'default' parameters. The optional 'default', 'notdefault' and 'noauth' parameters are passed as a single value. All other optional parameters are stored in the XML request as a pair of strings, a label and the value. Labels are 'logon', 'password', 'searchfilter', 'basedn' and 'searchscope'. Values for 'searchscope' are 'base', 'onelevel' and 'subtree'. See the example XML below. The NoAuth option will clear previously saved logon and password information. Example Request (SMTP) <methodCall> <methodName>securityGateway.CreateUVS</methodName> <params> <param><value>18</value></param> <param><value>name</value></param> <param><value>test8</value></param> <param><value>host</value></param> <param><value>123.45.67.89</value></param> <param><value>Port</value></param> <param><value>666</value></param> <param><value>Type</value></param> <param><value>SMTP</value></param> <param><value>default</value></param> <param><value>logon</value></param> <param><value>someone</value></param> <param><value>password</value></param> <param><value>somepass</value></param> </params> </methodCall> (Minger) <methodCall> <methodName>securityGateway.CreateDMS</methodName> <params> <param><value>18</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>method</value></param> <param><value>Minger</value></param> <param><value>default</value></param> <param><value>password</value></param> <param><value>adm1npw0rd</value></param> </params> </methodCall> (AD) <methodCall> <methodName>securityGateway.CreateDMS</methodName> <params> <param><value>18</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>method</value></param> <param><value>AD</value></param> <param><value>logon</value></param> <param><value>CN=admin,OU=it,DC=dom,DC=com</value></param> <param><value>password</value></param> <param><value>adminPa55word</value></param> <param><value>searchfilter</value></param> <param><value>(&(|(objectclass=user)(objectclass=group)(objectclass=publicFolder))(|(mail=$EMAIL$)(proxyAddresses=SMTP:$EMAIL$)))</value></param> </params> </methodCall> (LDAP) <methodCall> <methodName>securityGateway.CreateUVS</methodName> <params> <param><value>18</value></param> <param><value>name</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>method</value></param> <param><value>LDAP</value></param> <param><value>logon</value></param> <param><value>admin</value></param> <param><value>searchscope</value></param> <param><value>onelevel</value></param> <param><value>searchfilter</value></param> <param><value>ima search filter</value></param> <param><value>basedn</value></param> <param><value>oc=ima.base ic=dist uc=name</value></param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</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>0</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. UVS objects contain the following:
IdThe internal ID of the UVS
NameThe name of the UVS
HostThe IP address or URL of the UVS
PortThe port to use
TypeThe authentication method of the server, can be 'SMTP', 'AD', 'LDAP' or 'Minger'
Default1 if the UVS is to be used as a default server, 0 otherwise
RequireLogon1 if the UVS requires user authentication
LogonUser(optional) The logon user name
SearchFilter(optional AD and LDAP) The search filter to use with the UVS
RootDN(optional LDAP) The root distinguished name
BaseDN(optional LDAP) The base distinguished name when searching
SearchScope(optional LDAP) The scope to use when searching, can be 'base', 'onelevel' or 'subtree'
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>0</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 associate with 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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods ListUVSForDomain(string Domain) This function lists the user verification source for a domain. Parameters
Domain. . . this is the domain being queried
Return values This function returns an array of UVS structures or a fault otherwise. UVS objects contain the following:
IdThe internal ID of the UVS
NameThe name of the UVS
HostThe IP address or URL of the UVS
PortThe port to use
TypeThe authentication method of the server, can be 'SMTP', 'AD', 'LDAP' or 'Minger'
Default1 if the UVS is to be used as a default server, 0 otherwise
RequireLogon1 if the UVS requires user authentication
LogonUser(optional) The logon user name
SearchFilter(optional AD and LDAP) The search filter to use with the UVS
RootDN(optional LDAP) The root distinguished name
BaseDN(optional LDAP) The base distinguished name when searching
SearchScope(optional LDAP) The scope to use when searching, can be 'base', 'onelevel' or 'subtree'
Remarks Requires global administrator rights. 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
ListDomainsForUVS(string Domain) This function lists the domains for a specific user verification source. Parameters
ID. . . the ID of the User Verification Source
Return values This function returns an array of domain structures or a fault otherwise. Domain objects contain the following:
IdThe internal ID of the Domain
NameThe domain name
NumberOfUsersThe number of users currently in the domain
MaxUsersThe maximum number of users allowed for the domain
NoUVS1 if no UVS is to be used for this domain, 0 otherwise
Remarks Requires global administrator rights. Example Request <methodCall> <methodName>securityGateway.ListDomainsForUVS</methodName> <params> <param> <value><string>17</string></value> </param> </params> </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 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 This function returns success if the user was given domain administration rights or a fault otherwise. Remarks Requires global administrator rights. 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>0</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 This function returns success if the domain administration rights were removed or a fault otherwise. Remarks Requires global administrator rights. 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>0</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) value can be 'local' or 'external', defaults to both
Return values This function returns an array of domain administrator objects or a fault otherwise. Domain administrator objects contain the following:
IdThe internal ID of the Administrator
EmailThe mailbox of the Administrator
NameThe name of the Administrator associated with this mailbox
CommentA short description or note
Enabled1 if the mailbox is enabled, 0 otherwise
Remarks Requires domain administrator rights. 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 This function returns success if the user was given global administration rights or a fault otherwise. Remarks Requires global administrator rights. 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>0</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 This function returns success if the global administration rights were removed or a fault otherwise. Remarks Requires global administrator rights. 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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods ListGlobalAdmins(string LocalOrExternal) This function lists users that have global administrator rights. Parameters
LocalOrExternal. . . (optional) value can be 'local' or 'external', defaults to both
Return values This function returns an array of global administrator objects or a fault otherwise. Global administrator objects contain the following:
IdThe internal ID of the Administrator
EmailThe mailbox of the Administrator
NameThe name of the Administrator associated with this mailbox
CommentA short description or note
Enabled1 if the mailbox is enabled, 0 otherwise
Remarks Requires global administrator rights. 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. . . the email address of the external administrator
Enabled|Disabled. . . (optional) to enable/disable the account
Name <Real Name>. . . (optional) real name of the user
Comment <Comment>. . . (optional) text based information about the administrator
Password <Password>. . . (optional) the new administrator's password
Return values This function returns success if the external 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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods EditExternalAdmin(string Email, ...) This function edits an existing external administrator. Parameters
Email. . . the email address of the administrator
Enabled|Disabled. . . (optional) to enable/disable the account
NewEmail <new Mailbox>. . . (optional) the new email of the administrator
Name <new Real Name>. . . (optional) the new real name
Comment <new Comment>. . . (optional) a new comment or note
Password <new Password>. . . (optional) the new administrator password
Return values This function returns success if the account was edited or a fault otherwise. Remarks Requires global administrator rights. NewEmail, 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>newemail</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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteExternalAdmin(string Email) This function deletes an existing external administrator. Parameters
Email. . . 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>0</value> </param></params> </methodResponse> Back to XML-RPC Methods ------------------------------------------ WHITE AND BLACK LIST FUNCTIONS ------------------------------------------ These methods allow for listing, adding to and deleting from white and black lists. Back to Table of Contents GetUserWhitelist(string Email) This function returns the white list for a user. Parameters
Email. . . the email address of the user
Return values This function returns a list of email addresses on the users white list or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.GetUserWhitelist</methodName> <params> <param> <value><string>newuser@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <param><value><array> <data><value><struct> <member> <name>Id</name> <value><string>4</string></value> </member> <member> <name>Type</name> <value><string>20</string></value> </member> <member> <name>IP</name> <value><string/></value> </member> <member> <name>Val</name> <value><string>user@domain.com</string></value> </member> <member> <name>Comments</name> <value><string>Automatic - Recipient of outbound email</string></value> </member> </struct></value></data> </param></value></array> </methodResponse> Back to XML-RPC Methods GetDomainWhitelist(string Domain, ...) This function returns the white list for a domain. Parameters
Domain. . . the domain
Type. . . (optional) Only return this type: EMAIL, HOST or IP
Return values This function returns a list of email addresses, domains or ip addresses that are on the domain white list or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.GetDomainWhitelist</methodName> <params> <param> <value><string>domain.com</string></value> </param> <param> <value><string>EMAIL</string></value> </param> </params> </methodCall> Example Response <methodResponse> <param><value><array> <data><value><struct> <member> <name>Id</name> <value><string>4</string></value> </member> <member> <name>Type</name> <value><string>20</string></value> </member> <member> <name>IP</name> <value><string/></value> </member> <member> <name>Val</name> <value><string>user@external.com</string></value> </member> <member> <name>Comments</name> <value><string>Trusted user on the whitelist</string></value> </member> </struct></value></data> </param></value></array> </methodResponse> Back to XML-RPC Methods GetGlobalWhitelist() This function returns the global white list. Parameters
Type. . . (optional) Only return this type: EMAIL, HOST or IP
Return values This function returns a list of email addresses, domains or ip addresses that are on the global white list or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.GetGlobalWhitelist</methodName> <params> <param> <value><string>IP</string></value> </param> </params> </methodCall> Example Response <methodResponse> <param><value><array> <data><value><struct> <member> <name>Id</name> <value><string>4</string></value> </member> <member> <name>Type</name> <value><string>20</string></value> </member> <member> <name>IP</name> <value><string>120.20.20.134</string></value> </member> <member> <name>Val</name> <value><string/></value> </member> <member> <name>Comments</name> <value><string>Trusted IP address on the global whitelist</string></value> </member> </struct></value></data> </param></value></array> </methodResponse> Back to XML-RPC Methods AddToUserWhitelist(string Email, string Comment, string User) This function adds an email address to a users white list. Parameters
Email. . . the email address to be added
Comment. . . a comment about the entry User. . . the email address of the user Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.AddToUserWhitelist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>A comment</string></value> <value><string>user@local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods AddToDomainWhitelist(string Item, string Comment, string Domain) This function adds an email address, domain or IP to a domain white list. Parameters
Email. . . the email address, domain or IP to be added
Comment. . . a comment about the item User. . . the domain Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.AddToDomainWhitelist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>A comment</string></value> <value><string>local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods AddToGlobalWhitelist(string Item, string Comment) This function adds an email address, domain or IP to the global white list. Parameters
Email. . . the email address, domain or IP to be added
Comment. . . a comment about the item Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.AddToGlobalWhitelist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>A comment</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteFromUserWhitelist(string Email, string User) This function deletes an email address from a users white list. Parameters
Email. . . the email address to be added
User. . . the email address of the user Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.DeleteFromUserWhitelist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>user@local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteFromDomainWhitelist(string Item, string Domain) This function deletes an email address, domain or IP from a domain white list. Parameters
Email. . . the email address, domain or IP to be added
User. . . the domain Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.DeleteFromDomainWhitelist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteFromGlobalWhitelist(string Item) This function deletes an email address, domain or IP from the global white list. Parameters
Email. . . the email address, domain or IP to be added
Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.DeleteFromGlobalWhitelist</methodName> <params> <param> <value><string>user@external.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods GetUserBlacklist(string Email) This function returns the black list for a user. Parameters
Email. . . the email address of the user
Return values This function returns a list of email addresses on the users black list or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.GetUserBlacklist</methodName> <params> <param> <value><string>newuser@domain.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <param><value><array> <data><value><struct> <member> <name>Id</name> <value><string>4</string></value> </member> <member> <name>Type</name> <value><string>20</string></value> </member> <member> <name>IP</name> <value><string/></value> </member> <member> <name>Val</name> <value><string>user@domain.com</string></value> </member> <member> <name>Comments</name> <value><string>Automatic - Recipient of outbound email</string></value> </member> </struct></value></data> </param></value></array> </methodResponse> Back to XML-RPC Methods GetDomainBlacklist(string Domain, ...) This function returns the black list for a domain. Parameters
Domain. . . the domain
Type. . . (optional) Only return this type: EMAIL, HOST or IP
Return values This function returns a list of email addresses, domains or ip addresses that are on the domain black list or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.GetDomainBlacklist</methodName> <params> <param> <value><string>domain.com</string></value> </param> <param> <value><string>EMAIL</string></value> </param> </params> </methodCall> Example Response <methodResponse> <param><value><array> <data><value><struct> <member> <name>Id</name> <value><string>4</string></value> </member> <member> <name>Type</name> <value><string>20</string></value> </member> <member> <name>IP</name> <value><string/></value> </member> <member> <name>Val</name> <value><string>user@external.com</string></value> </member> <member> <name>Comments</name> <value><string>Trusted user on the Blacklist</string></value> </member> </struct></value></data> </param></value></array> </methodResponse> Back to XML-RPC Methods GetGlobalBlacklist() This function returns the global black list. Parameters
Type. . . (optional) Only return this type: EMAIL, HOST or IP
Return values This function returns a list of email addresses, domains or ip addresses that are on the global black list or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.GetGlobalBlacklist</methodName> <params> <param> <value><string>IP</string></value> </param> </params> </methodCall> Example Response <methodResponse> <param><value><array> <data><value><struct> <member> <name>Id</name> <value><string>4</string></value> </member> <member> <name>Type</name> <value><string>20</string></value> </member> <member> <name>IP</name> <value><string>120.20.20.134</string></value> </member> <member> <name>Val</name> <value><string/></value> </member> <member> <name>Comments</name> <value><string>Trusted IP address on the global Blacklist</string></value> </member> </struct></value></data> </param></value></array> </methodResponse> Back to XML-RPC Methods AddToUserBlacklist(string Email, string Comment, string User) This function adds an email address to a users black list. Parameters
Email. . . the email address to be added
Comment. . . a comment about the entry User. . . the email address of the user Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.AddToUserBlacklist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>A comment</string></value> <value><string>user@local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods AddToDomainBlacklist(string Item, string Comment, string Domain) This function adds an email address, domain or IP to a domain black list. Parameters
Email. . . the email address, domain or IP to be added
Comment. . . a comment about the item User. . . the domain Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.AddToDomainBlacklist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>A comment</string></value> <value><string>local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods AddToGlobalBlacklist(string Item, string Comment) This function adds an email address, domain or IP to the global black list. Parameters
Email. . . the email address, domain or IP to be added
Comment. . . a comment about the item Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.AddToGlobalBlacklist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>A comment</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteFromUserBlacklist(string Email, string User) This function deletes an email address from a users black list. Parameters
Email. . . the email address to be added
User. . . the email address of the user Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.DeleteFromUserBlacklist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>user@local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteFromDomainBlacklist(string Item, string Domain) This function deletes an email address, domain or IP from a domain black list. Parameters
Email. . . the email address, domain or IP to be added
User. . . the domain Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.DeleteFromDomainBlacklist</methodName> <params> <param> <value><string>user@external.com</string></value> <value><string>local.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</value> </param></params> </methodResponse> Back to XML-RPC Methods DeleteFromGlobalBlacklist(string Item) This function deletes an email address, domain or IP from the global black list. Parameters
Email. . . the email address, domain or IP to be added
Return values Returns success or a fault otherwise. Remarks None Example Request <methodCall> <methodName>securityGateway.DeleteFromGlobalBlacklist</methodName> <params> <param> <value><string>user@external.com</string></value> </param> </params> </methodCall> Example Response <methodResponse> <params><param> <value>0</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 and Reflection Methods Logon/Logout Methods Create/Edit/Delete/List User and Domain Methods Initialize the PocketXML-RPC proxy and call the XML-RPC reflection functions '-- Start of script (this is a comment) '-- declare the variables needed Dim uData(9) Dim f, p, r, q Set f = CreateObject("pocketXMLRPC.Factory") '-- URL of the Security Gateway including page and view (string) uData(0) = "http://127.0.0.1:4000/SecurityGateway.dll?view=xmlrpc" '-- method NamePrefix (string) uData(1) = "securityGateway." '-- server Username (string) uData(2) = "" '-- server Password (string) uData(3) = "" '-- HTTP Proxy Server (string) uData(4) = "" '-- HTTP Proxy Port (string) uData(5) = 0 '-- Proxy Username (string) uData(6) = "" '-- Proxy Password (string) uData(7) = "" '-- Timeout In Seconds (long) 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)) '-- 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, r Set f = CreateObject("pocketXMLRPC.Factory") '-- Alternate method for initializing the Proxy COM object '-- 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 r = p.Logon "admin@company.mail", "testing123" '-- Call some methods that require logon r = 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 6 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", "Come back king" p.CreateUser "troya@test2.com", "disabled", "name", "Troy Aikman", "password", "racecar", "comment", "Good ole boy and hall of famer" p.CreateUser "johne@test2.com", "disabled", "name", "John Elway", "password", "racecar", "comment", "Mile high hero" p.CreateUser "jimmcm@test2.com", "disabled", "name", "Jim McMahon", "password", "racecar", "comment", "Super Bowl ring wearer" 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 "jimmcm@test2.com" q = q & "User jimmcm@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