How to use our SOAP interface

The mailworx interface is implemented as a SOAP web service, which can be accessed via the URL https://mailworx.marketingsuite.info/Services/ServiceAgent.asmx.

The interface definition can be found at https://mailworx.marketingsuite.info/Services/ServiceAgent.asmx?WSDL.

Call concept of the SOAP web service

The mailworx SOAP web service interface is based on a message-oriented architecture. All methods of the SOAP web service expect exactly one input parameter (RequestMessage) and return exactly one return value (ResponseMessage). The RequestMessage contains all the information required to execute the SOAP web service method. Following successful execution of the method, the ResponseMessage returns the relevant method-specific data via the SOAP web service.

The mailworx SOAP web service interface does not manage any status when in use. It is therefore necessary to include the login details with every method call via the SOAP web service. The login details for mailworx are provided in unencrypted form. For this reason, it is recommended that the SOAP web service interface be accessed exclusively via HTTPS. The login details are set in the SecurityContext property within a message.

This SecurityContext contains four properties: Account, Username, Password, Source. The Source property of the SecurityContext is the name of the application that calls the SOAP web service interface. The application or the name listed here must be approved by eworx Network & Internet GmbH for use of the SOAP web service interface. Furthermore, eworx Network & Internet GmbH determines which methods of the mailworx SOAP web service interface are available for this application. If a method of the SOAP web service is called by an application but has not been approved for that application, an exception is thrown and the execution of that method is prevented.

As mailworx can manage newsletters in different languages, every RequestMessage requires a “Language” property, which must be set to the relevant language code (e.g. de, en, …).

This means that every RequestMessage has at least two properties: Language and the SecurityContext containing the login details for mailworx. This is ensured by the fact that every RequestMessage in mailworx is derived from SecureRequestMessage.

To reduce the load on the system and ensure the highest possible reliability, the request limit is restricted to 300 calls per minute.

Securing the SOAP Web Service Interface

The SOAP Web Service can be used via SOAP over HTTP or SOAP over HTTPS. Using HTTPS encrypts communication between the client and server and secures data transmission via the SOAP Web Service.

Numerous concepts have been developed and implemented to protect your data and ensure the security and stability of the mailworx system.

The mailworx platform is operated from a central data centre in Linz and is directly connected to the high-availability internet backbone. State-of-the-art firewall technologies and constant monitoring guarantee the best possible protection.