Lucee Developer

For all of you who have Smartermail as their mailserver software, I just made your life a bit easier!
You probably already know that it is not possible inside of smartermail, to change user settings for all existing customers in one time? You can change the Defaults for new users, but existing, nehh.
Since I needed to do some global changes for a few hundred accounts, I decided to check out the Smartermail API. And what began as a simple task, turned into my newest opensource Coldfusion project: the Smartermail API wrapper for coldfusion, complete with a UI for everyone!

The main file that cfml developers will use is smartermail.cfc , which does the actuall call to the webservice.
All other people (also non-coldfusion-people) can use the API wrapper UI which I also built.

Versions

17 june 2011: Version 1.3.1
Fixes a bug which made some API calls fail: all arguments were xmlFormatted, while some of these arguments needed to actually be shown as xml (i.e. <string>email@domain.com</string>).

26 february 2011: Version 1.3.0
Added extra no-compression headers to the http api call, to fix an Adobe CF bug. Updated the UI to allow domain admins to login and use the functionality.

01 december 2010: Version 1.2

Added debugging options in the Smartermail.cfc file; added optional extra debugging in the UI files; enhanced the UI a bit.

28 march 2010: Version 1.1

Changes in the smartermail API wrapper code, to make it CF7/8 compatible. (it used to be Railo + CF9 only)

9 may 2010: Version 1.1.1

The api wrapper now uses the xmlFormat() function for all values in the soap call. The smartermail api wrapper UI now shows a textarea when the field for an api function has 'description' in it's name. Also, all form values are now escaped with htmleditformat() when the form is shown again after submit. Also, some minor text/layout change.

Download the code

• You can download the whole package here (.zip, 456KB)
• View the source of smartermail.cfc or all other files

WSDL? No, just cfhttp ;-)

One of the biggest irritations with webservices is the wsdl itself, and the flunky way some versions of coldfusion handle it. For me, the simpler you can do it, the better. Web services are just a way of communication: I send an xml package with a question inside, and I get an xml package returned with the answer. That's it.
So, I decided to not use <cfinvoke>, but just <cfhttp>:

<cfhttp method="post" url="#this.serverURL#/Services/#arguments.page#.asmx" throwonerror="yes" result="cfhttpReturn_struct">
    <cfhttpparam type="header" name="Content-Type" value="application/soap+xml" />
    <cfhttpparam type="body" value="#soapBody#" />
</cfhttp>

The UI

As you can see in the example pages, all the methods are there, complete with the documentation and an example of the soap xml which is used. If you just want to use the UI, then just don't care about the xml; it's all done for you. Just fill in the displayed form, and you're fine!

For starters, you have to login with your server credentials. After that, a check is done to see if the credentials are correct.
Then, you are ready to go!

All of the options can also be done in your smartermail administrator, but I've made a few extras...
You can manage the settings for multiple email addresses in one time, and even for multiple domains in one time. If, for example, you want to change the mailbox size of 200 users, you only have to do one call! (hmm, wasn't that the thing I originally just needed to do?)

How to use the API wrapper yourself.

First, create the smartermail-object with the admin details:

<cfset variables.smartermail_obj = createObject("component", "Smartermail").init(serverURL="http://webmail.yourserver.com", wsUsername="your admin username", wsPassword="your admin password") />

Then, you can call any function you like, like this:

<cfset return_xml = variables.smartermail_obj.callWs(page='svcDomainAdmin', method='GetAllDomains') />

In case you need to give extra arguments to the page you are calling, you supply the extra argument 'args', like this:

<cfset extraArguments_struct = structNew() />
<cfset extraArguments_struct['DomainName'] = "somedomain.com" />
<cfset return_xml = variables.smartermail_obj.callWs(page='svcUserAdmin', method='GetUsers', args=extraArguments_struct) />

If you want to find out which arguments you need, then just check the UI test pages!

In the example pages I created an option to manage the settings for multiple domains and email addresses in one time. This is actually pretty simple to do, since you only have to loop over a list, like this:

<cfset emailList = "email1@domain.com,email2@domain.com,email9@otherdomain.com" />
<cfloop list="#emailList#" index="email">
	<cfset form.EmailAddress = email />
	<cfset extraArguments_struct = structNew() />
	<cfset extraArguments_struct['EmailAddress'] = email />
	<cfset return_xml = variables.smartermail_obj.callWs(page="svcUserAdmin", method="GetUser", args=extraArguments_struct) />
	<!--- you might want to do something with the xml you retrieved here --->
</cfloop>

When one of the parameters has multiple values (i.e. 3 mail addresses for 1 alias), then you need to send the 3 mailaddresses as an CRLF-delimited list, like this:

<cfset extraArguments_struct = structNew() />
<cfset extraArguments_struct['DomainName'] = "domain.com" />
<cfset extraArguments_struct['AliasName'] = "allclients" />
<cfset extraArguments_struct['Addresses'] = "info@client1.com
info@client2.com
peter@client3.com" />
<cfset return_xml = variables.smartermail_obj.callWs(page="svcAliasAdmin", method="AddAlias", args=extraArguments_struct) />

Debugging (new since version 1.2.0)

In case you need to debug the API calls, you can now simply save all request and response data to any scope you want.
To start, you need to add 2 arguments to the init function like this:

<cfset variables.smartermail_obj = createObject("component", "Smartermail").init(
      serverURL="http://webmail.yourserver.com"
    , wsUsername="your admin username"
    , wsPassword="your admin password"
    , debugMode=true
    , debugDataScopeName="request / application / this / server") />

By default, debugMode is off. The default for the debugDataScopeName is "this", which means that the debug data will be stored inside the cfc.

The debug data will be stored as "SMDebugData", so for example application.SMDebugData. It is an array with structs, containing the keys Date, Title, and Data. But you can access this debug data even more easily, by calling

<cfset myDebugData = variables.smartermail_obj.getDebugData() />

Usefull?

I hope you like and use the code! If so, leave me a comment; I'd like it!

Better yet, if you need a coldfusion (or Railo!) developer, hire me!