Among the various Interfaces to the eC-messenger Direct Marketing System, the Synchronous RPC-like SOAP API
is the preferred way for real time integrations with other systems.
Quick Access to the WSDL's: ecm.wsdl + WSDL for SSL Access

Why synchronous SOAP?#

The SOAP/RPC interface is the best suitable interface if you are looking for a realtime integration of eC-messenger into your systems. Closest to the synchronous SOAP API is the HTTP REST-API. We encourage you to prefer SOAP over REST whenever possible. Why?

• SOAP is strongly typed interface defined via language-independend WSDL-Files.
• For every major programming language there are librarys which make using SOAP-Services easy like calling local functions/methods.
• REST-Calls consist more or less of weakly defined HTTP-Calls, no type-safety or error-handling is built in.

Now you know why you should use the synchronous SOAP-API. But what are the differences between the synchronous and asynchronous SOAP API?

	Synchronous	Asynchronous
Operation types	single user/group	mass operations
Response	immediate	later by email
Execution time	short	long running

Sample Protocol excerpt#

The synchronous SOAP-API consists of granular RPC-Methods. A common behavior of all methods is that they need a authentication-token. A typical synchronous SOAP request cycle contains three RPC-calls:

1. Retrieve a authentication token through the logon(String realm, String user, String password)-method
2. Execute the method itself. For example query user-data with the lookupUserByEmail(String sessionToken, String email) method. Therefore you have to pass the authentication token from step 1 to the lookupUserByEmail method along with the parameters needed by the method. Generally, the authentication token is always the first parameter of a method.
3. Log out. To finish the session call the method logout(String token) with the token from step 1. This will invalidate the token to prevent misuse by others. Security tokens will automatically invalidated after 10 minutes without submitting a request to the system .

Sample Java-code:

EcMSoapBridge ecm = new EcMSoapBridgeServiceLocator().getrpc();

// logon to system
String sessionToken = ecm.logon("http://testdomain.de", "user@email.in", "password");

// retrieve user data by passing a email address
String userXML = ecm.lookupUserByEmail(sessionToken, "user@search.for");

// close session token
ecm.logout(sessionToken);

More Samples can be found in the Ressources section.

Methods and Objects#

The synchronous SOAP API mainly consist of methods to read and manipulate user- and group-object. The complete list of available methods can be found either directly in the wdsl-file, or as documentation in javadoc or soapdoc formatting.

Complex values#

Most of the methods accept and return simple datatypes, like a number or a string. Some of the methods, like updateUser or getMember need complex data. To maintain compatibility between SOAP-Protocol implementations, complex data is generally transmitted as xml.

The following data types are used xml encoded: User-Object, Member-Object and Group-Object. XML-Schema definitions can be found in ecm-types.xsd, as <user>, <member> and <group> elements (based on apiUserType).

The user-Type used here, is not derived from the xml user type used in the asynchronous API. Altough very similiar, differences exist, namely in the readmode-Setting, which is not supported here. Date of Birth: The date of birth has to be transferred as a named attribute (<namedattr name="dob">YYYY-MM-DD</namedattr>). The format is YYYY-MM-DD, whereas the month is from 01 (January) to 12 (December). See the examples below.

User-Object example#

<?xml version="1.0" ?>
<user  id="1234567">


    <email>test-soap@ecircle-ag.com</email>
    <mobilenumber>1234-222-444-555</mobilenumber>
    <title>1</title>
    <firstname>Paul</firstname>
    <lastname>Mc Soap</lastname>
    <partnerid>4096</partnerid>
    <countrycode>DE</countrycode>
    <languagecode>de</languagecode>
    <zipcode>12999</zipcode>
    <namedattr name="userid">q11234</namedattr>
    <namedattr name="buyer">true</namedattr>
    <namedattr name="reader">false</namedattr>
    <namedattr name="dob">2008-12-24</namedattr>
</user>

Member-Object example#

<?xml version="1.0" ?>
<member  id="1234567g7654321">
    <email>test-soap@ecircle-ag.com</email>
    <mobilenumber>1234-222-444-555</mobilenumber>
    <title>1</title>
    <firstname>Paul</firstname>
    <lastname>Mc Soap</lastname>
    <partnerid>4096</partnerid>
    <countrycode>DE</countrycode>
    <languagecode>de</languagecode>
    <zipcode>12999</zipcode>
    <namedattr name="userid">q11234</namedattr>
    <namedattr name="buyer">true</namedattr>
    <namedattr name="reader">false</namedattr>
    <namedattr name="dob">2008-12-24</namedattr>
    <memberattr name="coupon-id">aws334dfr</memberattr>
    <memberattr name="came-from">my best partner</memberattr>
</member>

Group-Object Example#

<?xml version="1.0" ?>
<group  group-id="1234567">
    <name>My Group</name>
    <tracking>
        <html reader="true" />
    </tracking>
</group>

Most of the elements on this object are optional, that means that a setting which is not present in the XML will not change.

Creating a new group:

<?xml version="1.0" ?>
<group group-id="new" preferred-channel="email">
    <name>My Group</name>
    <description>Description of the group</description> 
    <email-channel>
        <email>test12345@email.in</email>
    </email-channel>
</group>

More details can be found under XMLGroupType.

Performance, Limits and special considerations#

Limitations#

There are a few things for which you can not or should not use the synchronous SOAP API:

• You cannot create new messages. Use the asynchronous SOAP API for this kind of task. But it is possible to clone existing messages or to trigger the sendout of messages.
• Mass import or updates of users/members: This should not be done due to the fact, that you have to make one soap request for every single user/member. SOAP-Calls are quite expensive in performance, as there is a significant overhead for every request. Whenever you have multiple users/groups at once, consider using the asynchronous SOAP API, since this is suited for mass operations.

Backwards Compatibility#

While the general configuration of this API and its access points will not change often, the set of methods offered is increasing over time. Whenever a method would need a change in its signature, a new method will be created instead, having a increased name postfix, e.g. like lookupMemberByUserId_v2_0. This shall make sure, that existing clients continue to work.

Security / SSL#

To secure your requests, we recommend to use the SSL-SOAP-Endpoint instead of the unencrypted endpoint. The unencrypted endpoint should only be used for testing/debugging purposes.

Our Certificates come from http://trustcenter.de, which offers its root certificates here. You may download our public certificates from trustcenters .

You may have to install the public part of the certificate of the signer of our certificate into your Application Server. Unlike Webbrowsers, middleware is often not up-to-date in this regard. Here more information.

Using asynchronous mode#

This mode was removed from the synchronous API

Sample clients#

To try out our SOAP Webservice easily through several generic SOAP-Clients like:

• soapclient.com is a generic soapclient that can be used from your browser! use eC-M (Example Screenshots)!
• Xmethods is similiar to soapclient.com, not particular fast but they have a very appealing web interface. Try it with our WSDL: https://webservices.ecircle-ag.com/rpc?wsdl.

Please remember that Online-SOAP clients might be dangerous since your password is transmitted through a third party server.

To call our SOAP service directly out of your code in your preferred programming language you can take a look at these tutorials:

• PHP or [below]
• Perl
• Ruby
• Javascript
• Microsoft Excel/VB
• Java

Java Webservice Client#

See how easy it is, to create a Java client with modern IDE's.

PHP Sample#

This is the core of SOAP call using PHP5's built-in SOAP functinality:

   ...
   $client = new soapclient('http://webservices.ecircle-ag.com/soap/ecm.wsdl');
   ...
   // ask for the api version
   $result = $client->getVersion();
   // check if there was an error calling the API function
   if (is_soap_fault($rssult)) {
       echo '<span class=\"err\">error while api function calling</span><pre>';
       print_r($result);
       echo '</pre>';
       return;						}			
   ...
   echo "The Version Number is :<pre>".$result['getVersionReturn']."</pre>"; 
   ...
   // logon 
   $logonparams = array('realm' => 
      $_POST['realm'], 'user' =>   $_POST['username'], 'passwd' => $_POST['pass']);
   $result = $client->logon($logonparams);
   // get session id
   $sessionid = $result->logonReturn;
   .....

   // font forget to log out later !

This examples should work on any PHP5 with build-in SOAP. We have also somesample code using nusoap.

Thanks to Kai for these Examples.

Utility Code#

Java#

For Java Programmers we can offer some utilities that simplify the usage of the api. Download the jar here.

These classes need additional libraries and can unfortunately not be used as they are. We work on a solution.

User/Member Processing These Objects are transfered using their XML representation. Here are Helper Classes to read and write them.

    // writing out a user
    User u = new User();
    u.setEmail("some_mail@ecircle-ag.com").setFirstName("Paul").setLastName("Spom");
    u.setAttribute("user-Attribute", "no 1");
    System.out.println("In XML: " + u.toXML());
    // reading a user
    User u1 = User.fromXML(u.toXML()); // you may get a user String also from API methods
    if (u1.getEmail().equals(u.getEmail())) {
        System.out.println("Reading and Writing worked!");
    }

A counterpart class exists for the member object.

Unique User/Member/Group-Id's Some API methods deal with unique identifiers of the entities. Since they are also part of the entity objects, they can be processed with some utility methods

    ...
    Member m = ecm.lookupMember(...);
    String groupid = m.getGroupId();
    // alternativly, some static Helpers
    String groupid1 = Member.extractGroupId(m.getId());
    ...

---

See also AddressingOptions - AsynchronousAPI - EcircleDeveloper - InterfaceOptionsComparison - LeftMenu - Ressources - SoapWithAttachments - XMLMessageType - XMLUserType