The conditions block is the way in which certain data can be specified for the Grid Request. Using the appropriate combination of comparators and operators, the conditions block can be tailored to meet specific data needs.

Grid Request conditions

Comparators and operators

The comparators listed below are used within any conditions statement in a Grid Request document.

Description	Code
Equal To	EQ
Not equal to	NEQ
Greater than	GT
Less than	LT
Less than or equal to	LTE
Greater than or equal to	GTE

Below is an example of searching for a specific mailing instance:

      <Conditions>
        <Condition>
          <Single>
            <DataElement>MailingInstanceID</DataElement>
            <Comparator>EQ</Comparator>
            <DataValue>478922</DataValue>
          </Single>
        </Condition>
        <Condition>
          <Single>
            <DataElement>EmailAddress</DataElement>
            <Comparator>EQ</Comparator>
            <DataValue>gulliver@yahoo.com</DataValue>
          </Single>
        </Condition>
      </Conditions>

The operators listed below are used within a Condition Collection in a Grid Request document.

Description	Code
Equal To	EQ
Not equal to	NEQ
In	IN
Not In	NOTIN

      <Conditions>
        <Condition>
          <Collection>
            <DataElement>MailingID</DataElement>
            <DataValue>51223</DataValue>
            <DataValue>51238</DataValue>
            <SetOperator>IN</SetOperator>
          </Collection>
        </Condition>
      </Conditions>

Between

The example below creates a range for a request:

<Condition>
  <Between>
    <DataElement>mailing_date</DataElement>
    <DataValue>2008-04-28T04:40:00</DataValue>
    <DataValue>2008-04-28T04:41:00</DataValue>
  </Between>
</Condition>

When creating a range for dates, make sure that the smaller (earlier) value is first (above) the larger (later) time.

DateTime with a comparator

Time is required when using EQ or IN. It is optional for all others.

If not specified, time defaults to 00:00:00 UTC.

Count

When requesting count, it can be the only DataElement ReturnField. This example shows how to retrieve a count of mailings in a specific folder.

Data Element	Type	Length	Conditional	Description
Count	Int	N/A	False	Matches found based upon the criteria.

Request

<Grid Request xmlns="http://partner.informz.net/aapi/2009/08/">
 <Password>password</Password>
 <Brand id="9999">Test Brand</Brand>
 <User>testuser</User>
 <Grids>
  <Grid type="mailing_folder">
   <ReturnFields>
    <DataElement>count</DataElement>
   </ReturnFields>
  </Grid>
 </Grids>
</Grid Request>

Notes

When Count is requested that is the only ReturnFields that can be requested.
The <Count /> must include the slash.

Response

<?xml version="1.0" encoding="utf-16"?>
<GridResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="9999">Test Brand</Brand>
 <User>testuser</User>
 <Grids>
  <Grid type="mailing_folder">
   <Record row="0">
    <Fields>
     <Field element="count">17</Field>
    </Fields>
   </Record>
  </Grid>
 </Grids>
</GridResponse>

Paging

Depending upon the amount of data being retrieved, it may be appropriate to use paging within the document to manage the data. The management of the pages would occur in the client application.

This is only applicable for Grid Request documents. If order is not specified, ascending will be used. Use "desc" for descending.

The grid request would implement paging using SortField, StartRow, and NumberOfRows like this:

<SortField order="asc">Mailing_Date</SortField>
<StartRow>200</StartRow>
<NumberOfRows>50</NumberOfRows>

Grid Requests with multiple conditions

You can use multiple conditions to form more complex requests with the Informz API. Before you do, review the following points to ensure that your request will work.

Each condition’s <DataElement> can appear only once in the grid request; otherwise, they will be in conflicts and no fields will be returned.
Be sure that each condition gets its own <Condition> parent tag.
It is best to work “large to small," having the expectation that fewer records return as more conditions are added to the grid request.

Below are three examples of these complex conditions working together:

Example 1: Inclusive Conditions

The below example is a Grid Request that is trying to pull tabular data from subscriber_personal_information using “inclusive conditions,” or conditions that work to get information based on the conditions being supplied appearing in the response.

In this request, we are looking for all personal information for three separate Subscriber_IDs, including three Personal_Information_IDs that we want to include, and then including an additional condition to return data related to items where the personal_information_name is equal to “First Name.”
This is not the most useful grid request (since the third condition basically makes the second condition useless), but it does illustrate how conditions can work together to narrow down on what is important:

<Grid Request xmlns="http://partner.informz.net/aapi/2009/08/">
 <Password>password</Password>
 <Brand id="9999">Brand Name</Brand>
 <User>test_user</User>
 <Grids>
  <Grid type="subscriber_personal_information">
   <Conditions>
    <Condition>
     <Collection>
      <DataElement>Subscriber_ID</DataElement>
      <DataValue>521698050</DataValue>
      <DataValue>522355847</DataValue>
      <DataValue>522355874</DataValue>
      <SetOperator>IN</SetOperator>
     </Collection>
    </Condition>
    <Condition>
     <Collection>
      <DataElement>Personal_Information_ID</DataElement>
      <DataValue>1057</DataValue>
      <DataValue>1058</DataValue>
      <DataValue>1049</DataValue>
      <SetOperator>IN</SetOperator>
     </Collection>
    </Condition>
    <Condition>
     <Collection>
      <DataElement>Personal_Information_name</DataElement>
      <DataValue>First</DataValue>
      <SetOperator>IN</SetOperator>
     </Collection>
    </Condition>
   </Conditions>
   <ReturnFields>
    <DataElement>subscriber_id</DataElement>
    <DataElement>Email</DataElement>
    <DataElement>personal_information_id</DataElement>
    <DataElement>personal_information_name</DataElement>
    <DataElement>personal_information_value</DataElement>
   </ReturnFields>
  </Grid>
 </Grids>
</Grid Request>

Example 2: Subscriber Interests

The following request seeks data contingent upon both “inclusive conditions” and “non-inclusive/negative” conditions. The idea is to request data that has some given criteria, while removing items from that data that are not important to what we’re hoping to see in the response. In the below request, we want to:

request all subscribers who were brought into Informz after December 31, 2015,
omit two Informz users who were added after that date that would otherwise appear as subscribers in the response,
omit unsubscribers.

<Grid Request xmlns="http://partner.informz.net/aapi/2009/08/">

 <Password>password</Password>
 <Brand id="9999">Brand Name</Brand>
 <User>test_user</User>
  <Grids>
  <Grid type="subscriber">
   <Conditions>
    <Condition>
     <Single>
      <DataElement>service_since_date</DataElement>
      <DataValue>2015-12-31</DataValue>
      <Comparator>GT</Comparator>
     </Single>
    </Condition>
    <Condition>
     <Collection>
      <DataElement>email</DataElement>
      <DataValue>new_admin_user1@example.com</DataValue>
      <DataValue>new_admin_user2@example.com </DataValue>
      <SetOperator>NOTIN</SetOperator>
     </Collection>
    </Condition>
    <Condition>
     <Single>
      <DataElement>is_unsubscriber</DataElement>
      <DataValue>1</DataValue>
      <Comparator>NEQ</Comparator>
     </Single>
    </Condition>
   </Conditions>
   <ReturnFields>
    <DataElement>email</DataElement>
    <DataElement>is_unsubscriber</DataElement>
   </ReturnFields>
  </Grid>
 </Grids>
</Grid Request>

Example 3: Mailing

The following requests data that should include mailings that were sent between two dates. In addition, the request omits any mailings that contain the specified Subject line.

<Grid Request xmlns="http://partner.informz.net/aapi/2009/08/">
 <Password>password</Password>
 <Brand id="9999">Brand Name</Brand>
 <User>test_user</User>
  <Grids>
  <Grid type="mailing">
   <Conditions>
    <Condition>
     <Between>
      <DataElement>create_date</DataElement>
      <DataValue>2014-12-31</DataValue>
      <DataValue>2016-04-25</DataValue>
     </Between>
    </Condition>
    <Condition>
     <Single>
      <DataElement>subject</DataElement>
      <DataValue>This is my test email</DataValue>
      <Comparator>NEQ</Comparator>
     </Single>
    </Condition>
   </Conditions>
   <ReturnFields>
    <DataElement>create_date</DataElement>
    <DataElement>folder_id</DataElement>
    <DataElement>friendly_from</DataElement>
    <DataElement>mailing_id</DataElement>
    <DataElement>name</DataElement>
    <DataElement>reply_to</DataElement>
    <DataElement>subject</DataElement>
    <DataElement>template_name</DataElement>
   </ReturnFields>
  </Grid>
 </Grids>
</Grid Request>

Grid Requests with multiple grids

The example below returns the individual email addresses corresponding to an open action taken by the recipients of a published mailing. This document would be used after having requested and then receiving a response for MailingInstance. This example also shows how two requests can be made in a single document.

Request

<Grid Request xmlns="http://partner.informz.net/aapi/2009/08/">
 <Password>password</Password>
 <Brand id="9999">Test Brand</Brand>
 <User>testuser</User>
 <Grids>
  <Grid type="mailing_activity_opens">
   <Conditions>
    <Condition>
     <Single>
      <DataElement>Mailing_Instance_ID</DataElement>
      <DataValue>478922</DataValue>
      <Comparator>EQ</Comparator>
     </Single>
    </Condition>
    <Condition>
     <Single>
      <DataElement>Email</DataElement>
      <DataValue>gulliver@yahoo.com</DataValue>
      <Comparator>EQ</Comparator>
     </Single>
    </Condition>
   </Conditions>
   <ReturnFields>
    <DataElement>Open_Date</DataElement>
   </ReturnFields>
   <SortField order="asc">Open_Date</SortField>
   <StartRow>1</StartRow>
   <NumberOfRows>50</NumberOfRows>
  </Grid>
  <Grid type="mailing_activity_clicks">
   <Conditions>
    <Condition>
     <Single>
      <DataElement>Mailing_Instance_ID</DataElement>
      <DataValue>478922</DataValue>
      <Comparator>EQ</Comparator>
     </Single>
    </Condition>
    <Condition>
     <Single>
      <DataElement>Email</DataElement>
      <DataValue>gulliver@yahoo.com</DataValue>
      <Comparator>EQ</Comparator>
     </Single>
    </Condition>
   </Conditions>
   <ReturnFields>
    <DataElement>Link_Name</DataElement>
    <DataElement>Link</DataElement>
    <DataElement>link_date</DataElement>
   </ReturnFields>
   <SortField order="asc">link_date</SortField>
   <StartRow>1</StartRow>
   <NumberOfRows>50</NumberOfRows>
  </Grid>
 </Grids>
</Grid Request>

Conditions and Multiplicity

Grid Request conditions

Comparators and operators

Between

DateTime with a comparator

Count

Request

Notes

Response

Paging

Grid Requests with multiple conditions

Example 1: Inclusive Conditions

Example 2: Subscriber Interests

Example 3: Mailing

Grid Requests with multiple grids

Request

Can’t find what you’re looking for?