0 Comments

FastServices

1 Overview
2 Getting started
3 Implementation examples
4 Functions/Methods
5 WSDL
6 Protocol summary
- 6.1 Protocol changes
7 Protocol detail
8 External links
9 Comments

OverviewEdit

FastServices is the API that FastMail.FM provides, which allows programmers to access many aspects of FastMail.FM. It is the interface used by FastCheck, for instance (along with IMAP, which is still the preferred mechanism for accessing email programmatically). FastServices uses SOAP as the underlying protocol, but adds secure sessions using a one-time challenge based mechanism.

Getting startedEdit

If you just want to get going and use the FastServices API from your favourite programming language, look at the links in the Implementation examples section. This includes links to code that should get you up and running pretty quickly. Some of them include libraries that wrap up the session management work for you so you can just specify a username and password and start calling methods.

In the Functions/Methods section you can see a basic list of functions available to call.

If you need more detail, or need to dig into the guts some more, you can look at the Protocol summary and Protocol details sections.

Implementation examplesEdit

Here's some links to example implementations in various languages

Functions/MethodsEdit

The following is a list of commands currently available. This will be expanded based on demand and requirements

CommandEdit

Command_Echo(@params) - echo back the pass parameters, useful for testing
Command_Execute($cmd, $param) - execute a meta FastCommand
Command_Wiki2Html($txt) - convert $txt from wiki format to html format
Command_Html2Wiki($htl) - convert $html from html format to wiki format (PhpWiki dialect)
Command_Format($txt) - perform formatting of $text (text wrap and re-format)
Command_Imap($cmd, $params) - run IMAP command (list, create, search, fetch)
- Note that $params is a space delimited list of arguments. If a param is required that contains spaces, wrap it in double quotes (").

AccountInfoEdit

AccountInfo_GetFolderList() - return a list of mailbox folders
AccountInfo_GetAddressBook($format, $charset, $eol) - export address book in $format (VCARD3 (default), OL, OE, YAHOO, VCARD, LDIF), using character set $charset and with $eol as the end of line character
AccountInfo_GetSmsCredits() - return sms credits balance

URLEdit

URL_CreateURL($screen, $method, @params) - create a url to go to the particular screen $screen=Compose $method=Main $method=FromName, @params="fromname" $screen=Mailbox $method=Main $method=GotoFolder, @params=folderid (from GetFolderList)

DatabaseEdit

Database_Select($Table, $Fields, $Criteria) - retrieve user information from database
Database_Insert($Table, $FieldValues) - insert user information into database
Database_Update($Table, $FieldValues, $Criteria) - update user information in database
Database_Delete($Table, $Criteria) - delete user information from database

See FastServicesUserData for more information

WSDLEdit

A WSDL file for those languages that support/need it is available here: http://jhoward.fastmail.fm/programs/FastServices.wsdl

Protocol summaryEdit

The following are the main points of calling the API:

Call the CreateSession function passing the username and password as parameters which returns a session-id. We recommend you use https for security
Call any functions you want, passing the session-id as the first parameter

Protocol changesEdit

The protocol used to require the use of a "one-time" parameter that was calculated with each call. That system is no longer required or used and code should be changed to use the new CreateSession method that takes a username and password instead.

Protocol detailEdit

SOAP access pointEdit

The SOAP endpoint URL is http://www.fastmail.fm/SOAP/, while the URI is http://www.fastmail.fm/SOAP/MessagingEngine/. This might mean different things for different implementations, so it's probably best to look at the examples for each language below.

Because of the slightly different implementations of SOAP out there, it can actually end up being reasonably complex to get them to all work together (namespace issues, exact XML issues, etc). Below I've included some dumps of the XML SOAP packets sent and received so you can get an idea of what you should be seeing "on the wire". Again, probably best to look at the working examples in your programming language of choice.

CreateSession callEdit

When calling CreateSession, you pass one parameter, the fully qualified UserName (eg yourusername@yourdomain.tld). SOAP body wise, this ends up:

 
 POST http://www.fastmail.fm/SOAP/ HTTP/1.1
 Content-Type: text/xml; charset=utf-8
 SOAPAction: "http://www.fastmail.fm/SOAP/MessagingEngine#CreateSession"
 
 <?xml version="1.0" encoding="UTF-8"?>
 <SOAP-ENV:Envelope
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/1999/XMLSchema"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
     <namesp1:CreateSession xmlns:namesp1="http://www.fastmail.fm/SOAP/MessagingEngine">
       <UserName xsi:type="xsd:string">yourusername@yourdomain.tld</UserName>
/SOAP/MessagingEngine">
       <Password xsi:type="xsd:string">yourpassword</Password>
     </namesp1:CreateSession>
   </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

The return from this would be something like:

 
 HTTP/1.1 200 OK
 Content-Length: 756
 Content-Type: text/xml; charset=utf-8
 
 <?xml version="1.0" encoding="UTF-8"?>
 <SOAP-ENV:Envelope
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/1999/XMLSchema"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
     <namesp5:CreateSessionResponse xmlns:namesp5="http://www.fastmail.fm/SOAP/MessagingEngine">
       <SessionStr xsi:type="xsd:string">1c310f4d9f3ebd513e4e/a4ca6739/35a563ae</SessionStr>
       <Success xsi:type="xsd:int">1</Success>
     </namesp5:CreateSessionResponse>
   </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Note: In times past, the CreateSession call may have returned a SOAP fault, with details about a different endpoint URL to use. With our new balanced web-server setup, this is no longer required.

Making a call exampleEdit

Here's an example of making a call to the Command_Echo() function (more commands are listed below). Basically this command echos back a text string dump of the passed parameters using the perl Data::Dumper module. Here's what the SOAP call looks like:

 
 POST http://www.hpvm1.com/SOAP/ HTTP/1.1
 Content-Length: 757
 Content-Type: text/xml; charset=utf-8
 
 <?xml version="1.0" encoding="UTF-8"?>
 <SOAP-ENV:Envelope
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/1999/XMLSchema"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
     <namesp2:Command_Echo xmlns:namesp2="http://www.hpvm1.com/SOAP/MessagingEngine">
       <SessionStr xsi:type="xsd:string">670d7b3b31caf0337e1b/ec60752a/35a563ae</SessionStr>
       <Param xsi:type="xsd:string">some string</Param>
     </namesp2:Command_Echo>
   </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

And the result looks like this:

 
 HTTP/1.1 200 OK
 Content-Length: 691
 Content-Type: text/xml; charset=utf-8
 
 <?xml version="1.0" encoding="UTF-8"?>
 <SOAP-ENV:Envelope
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsd="http://www.w3.org/1999/XMLSchema"
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body>
     <namesp19:Command_EchoResponse xmlns:namesp19="http://www.hpvm1.com/SOAP/MessagingEngine">
       <ParamDump xsi:type="xsd:string">$VAR1 = [
   'some string'
 ];</ParamDump>
     </namesp19:Command_EchoResponse>
   </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

External linksEdit

If you have a moment, please help us document FastServices here. In the meantime, the best documentation is the code, and forum threads:

Retrieved from "http://fastmail.wikia.com/wiki/FastServices"

Showing 0 most recent

0 comments

Anonymous User
Log in?

Wikia