Setup

Below, you'll learn about the steps and processes needed to set up API development with Informz.

Assumptions

Informz has the following assumptions with regard to the skill set of our partner’s developers:

  1. Developers have a working knowledge of web services
  2. Developers have 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:

  1. Ensure that your firewall will allow a connection to Informz’s web service.
  2. 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.
  3. Get your Informz brand ID and brand name from your Informz Advisor.
  4. Decide if you will employ encryption.
    1. If no, then a user name and password will be established in the brand
    2. 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. This can be found at https://partnertest.informz.net/aapi/InformzService.svc

Moving to Production

Once development and testing are complete, the final step is to move the work to production. Here are the steps you will have to perform to do this:

  1. Change the endpoint url to point to
    1. For the US: https://partner.informz.net/aapi/InformzService.svc (rather than partnertest)
    2. For Canada: https://partner.informz.ca/aapi/InformzService.svc
  2. 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. Please 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>