Introduction
Thank you for choosing to work with Informz on this integration project! We are looking forward to a successful technical relationship with you and your company.
This documentation helps you to get set up and to develop your web service client/consumer.
Suggested Uses
The main anticipated use of the Informz Web Service is to simplify the synchronization of data between Informz and another client application. This facilitates the easy transfer of email addresses captured in one environment and then being directed into Informz.
In addition to email address, other information about the email recipient can be transferred. For example, first name can be provided so that a mailing can be personalized using that data. Further segmentation of the subscriber base can also occur in Informz leveraging this personal information.
Equally important as getting information about those who wish to receive mailings from your organization is to know those people who do not wish to receive mailings from your organization. Lists of unsubscribers can also be sent to Informz so that these email addresses can be excluded from future mailings.
Aside from data synchronization, these lists can serve as a starting point for generating reports. There are many GridRequest actions that can be used to retrieve data from Informz. This included information about subscribers as well as the results of any mailing publishing.
Technology Overview
Informz has embraced a document-centric approach to SOAP-based web services. This is considered to be a "second generation" approach for web services. There are a number of benefits to this approach that we think will be helpful to you as you develop your integration. Please go to http://www.ibm.com/developerworks/webservices/library/ws-docstyle.html for more details.
These benefits include:
- Sending a single document (as opposed to making multiple iterative method calls)
- Listening for only the data that you want in a Response Document
- Avoiding RPC, which is more "fragile" with regard to versioning
Support
Understanding how Informz works will be helpful to you as you begin work on this project. The Informz Partner Relationship Manager will schedule a session, or sessions, for your team to learn about Informz and how it operates. Having a basic understanding of the Informz UI will help you to test your API.
If you have any questions about working with the Informz API please contact Informz. support@informz.com is monitored for any technical questions related to use of the web service. Please list your name and include any relevant uncompressed XML calls in your message.
Setup
Below, you'll learn about the steps and processes needed to set up API development with Informz.
Assumptions
Informz assumes our partner’s developers have: i) a working knowledge of web services and ii) a working knowledge of XML.
Setup
Below are the steps you’ll need to go through to set up your environment to work with Informz:
- Ensure that your firewall will allow a connection to Informz’s web service.
- You will need to provide us with a list or range of IP addresses that your API requests will originate from. We will add those to a list of allowed IP addresses during the brand creation process.
- Get your Informz brand ID and brand name from Informz.
- Decide if you will employ encryption.
- If no, then a user name and password will be established in the brand
- If yes, Informz will provide you with an encryption key
Test Environment
You will be able to test your work via our publicly available interface at https://partnertest.informz.net/aapi/InformzService.svc.
Moving to Production
After development and testing are complete, move the work to production. Here are the steps you will have to perform to do this:
- Change the endpoint url to point to
- For the US: https://partner.informz.net/aapi/InformzService.svc (rather than partnertest)
- For Canada: https://partner.informz.ca/aapi/InformzService.svc
- Create user account in Informz if this is different than what was used during development. This can be done either by a single Informz account used for all calls, or existing user credentials can be passed in to support auditing of the messages.
Schema and WSDL Locations
The Informz XSD can be found at http://partner.informz.net/aapi/schema/InformzService.xsd.
The WSDL can be found at https://partner.informz.net/aapi/InformzService.svc?WSDL.
API Method
There is a single method in the Informz API. This is:
PostInformzMessage (string)
The input string parameter should be a fully formed XML document.
Informz Documents
Informz provides two documents for your use:
ActionRequest - Use this when you want Informz to perform an action, such as CreateMailing or ScheduleMailing.
<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
<Brand id="9999">Test Brand</Brand>
<User>testuser</User>
<Actions>
[Action Details]
</Actions>
</ActionRequest>
GridRequest - Use this when you want to return tabular data from Informz. This could be a list of mailings in Informz or a list of who opened a particular mailing.
The GridRequest document retrieves information from Informz for use in the partner application. The <DataElement> node provides flexibility to request any available information using the same document format.
<GridRequest xmlns="http://partner.informz.net/aapi/2009/08/">
<Brand id="9999">Test Brand</Brand>
<User>testuser</User>
<Grids>
[Grid Details]
</Grids>
</GridRequest>
All documents need to include the Brand ID, Brand Name, and User. Brand ID and User will be validated when the document is received. The Brand ID will be validated against the IP address stored with this Brand to ensure that this is a valid origination point for the brand. User will be validated against a known user list in Informz.
Brand name is used for logging purposes only.
Case Sensitivity and Order
The document tags are case sensitive. Make sure that the case sensitivity is respected between the calling application and API. For example, <BulkUpload> would be correct but <bulkupload> would not be. However, the comparison of string values in a grid request is case insensitive.
The order that nodes are presented within an XML document are determined by the XSD. Use the example messages provided as well as the graphical depiction of the XSD to ensure that the node order in the documents being submitted to the Informz API match the order as found in the XSD.
Compression
All messages to and from the Informz Web Service are compressed to help speed transfer and to reduce the amount of bandwidth needed to handle requests. The service uses standard gzip libraries provided with .NET to compress the payload of the message. The payload nodes are the ActionRequest for action messages and the GridRequest node for grid messages (reports). For the response messages, the ActionResponse and the GridResponse nodes will be also be compressed. Only the payload is compressed because the remaining header nodes are used for validation of the incoming request before decompression and decryption.
Encryption/Authentication
The Informz web service can encrypt incoming and outgoing messages. Encryption is implemented using TripleDES encryption using 192 bit symmetric keys. Only the payload of the message is encrypted.
Using encryption for message security is strongly recommended. If implementing encryption is not an option, authentication must be implemented by including a Password node along with the User node. These values are passed "in the clear," so it is not secure.
The XML encryption technique is W3C compliant. Informz is capable of encrypting either an entire XML document or specific nodes within the XML Doc. Informz supports TripleDES (with 192 bit key).
If implementing encryption is not an option, authentication can be implemented using username and password.
Encoding
After compressing and or encrypting your payload, the data must be Base64 encoded. The example below shows the resulting message:
<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/"> <Brand id="9999">Test Brand</Brand> <User>testuser</User> <Password>password</Password> <Actions>+AUAAB+LCAAAAAAABADtvQdgH...T+oAkh/+AUAAA==</Actions> </ActionRequest>
Header Tags
Every action request contains this information. The Brand tag corresponds to an Informz brand. Within the tag there is an ID attribute that will need to match to the Informz brand’s ID to be permitted in through the web service. The User tag corresponds to a valid Informz user.
<Brand id="9999">Test Brand</Brand> <User>testuser</User> <Password>password</Password>