Knowledge Base

GridRequests - Message Categories

  • Updated

Message Categories for a Subscriber

Use this request to retrieve Message Category preference information for an individual contact.

The request returns one row for each Message Category in the authenticated brand, including active and archived categories.

Contacts are available for a Message Category by default unless an active category-level opt-out exists.

Notes

  • At least one contact identifier is required with an EQ comparator: subscriber_id, email, user_id, or imis_name_id.
  • Maximum of 1,000 rows can be returned in one request.
  • Default sort is message_category_id.

Element list

Data Element Type Conditional Description
subscriber_id Int True Informz subscriber ID
email String True Contact email address
user_id String True Remote ID (remote_key_ident)
user_id_source String True Remote key source (remote_key_source)
imis_name_id String True iMIS Name ID, when applicable
message_category_id Int True Message Category ID
message_category_name String True Message Category name
message_category_description String True Message Category description
is_message_category_active Bit True 1 = Active; 0 = Archived
is_opted_out Bit True 1 = OptedOut; 0 = Available
last_modified_date Datetime True Opt-out row modification date when a row exists (active or inactive); empty when no row exists
count Int False Number of matches based on the specified criteria

Request

<GridRequest xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="2001">Example Brand</Brand>
 <User>apiuser</User>
 <Password>password</Password>
 <Grids>
  <Grid type="subscriber_message_categories">
   <Conditions>
    <SingleCondition>
     <DataElement>email</DataElement>
     <Comparator>EQ</Comparator>
     <DataValue>user@example.com</DataValue>
    </SingleCondition>
   </Conditions>
   <ReturnFields>
    <DataElement>subscriber_id</DataElement>
    <DataElement>email</DataElement>
    <DataElement>user_id</DataElement>
    <DataElement>user_id_source</DataElement>
    <DataElement>imis_name_id</DataElement>
    <DataElement>message_category_id</DataElement>
    <DataElement>message_category_name</DataElement>
    <DataElement>message_category_description</DataElement>
    <DataElement>is_message_category_active</DataElement>
    <DataElement>is_opted_out</DataElement>
    <DataElement>last_modified_date</DataElement>
   </ReturnFields>
   <StartRow>0</StartRow>
   <NumberOfRows>1000</NumberOfRows>
  </Grid>
 </Grids>
</GridRequest>

Filter examples

Available categories only:

<SingleCondition>
 <DataElement>is_opted_out</DataElement>
 <Comparator>EQ</Comparator>
 <DataValue>0</DataValue>
</SingleCondition>

Opted-out categories only:

<SingleCondition>
 <DataElement>is_opted_out</DataElement>
 <Comparator>EQ</Comparator>
 <DataValue>1</DataValue>
</SingleCondition>

Active Message Categories only:

<SingleCondition>
 <DataElement>is_message_category_active</DataElement>
 <Comparator>EQ</Comparator>
 <DataValue>1</DataValue>
</SingleCondition>

Response

<GridResponse xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="2001">Example Brand</Brand>
 <User>apiuser</User>
 <Grids>
  <Grid type="subscriber_message_categories">
   <Record row="0">
    <Fields>
     <Field element="subscriber_id">10001</Field>
     <Field element="email">user@example.com</Field>
     <Field element="user_id">REMOTE-42</Field>
     <Field element="user_id_source">PartnerSystem</Field>
     <Field element="imis_name_id">12345</Field>
     <Field element="message_category_id">10</Field>
     <Field element="message_category_name">Newsletter</Field>
     <Field element="message_category_description">Monthly member newsletter</Field>
     <Field element="is_message_category_active">1</Field>
     <Field element="is_opted_out">0</Field>
     <Field element="last_modified_date"/>
    </Fields>
   </Record>
   <Record row="1">
    <Fields>
     <Field element="subscriber_id">10001</Field>
     <Field element="email">user@example.com</Field>
     <Field element="user_id">REMOTE-42</Field>
     <Field element="user_id_source">PartnerSystem</Field>
     <Field element="imis_name_id">12345</Field>
     <Field element="message_category_id">11</Field>
     <Field element="message_category_name">Promotions</Field>
     <Field element="message_category_description">Product and event promotions</Field>
     <Field element="is_message_category_active">1</Field>
     <Field element="is_opted_out">1</Field>
     <Field element="last_modified_date" type="Date">2026-06-15T18:30:00.0000000Z</Field>
    </Fields>
   </Record>
  </Grid>
 </Grids>
</GridResponse>

Notes

  • Each Message Category is returned in its own row.
  • Use is_opted_out to determine availability. After OptIn, is_opted_out is 0, but last_modified_date may still be populated from an inactive opt-out row.
  • If no supported contact identifier with EQ is supplied, the request returns MissingData.

Subscribers for a Message Category

Use this request to retrieve contacts and their preference status for a specific Message Category.

The request returns one row for each active contact in the authenticated brand for the selected Message Category.

Notes

  • message_category_id with an EQ comparator is required.
  • Maximum of 10,000 rows can be returned in one request
  • Default sort is subscriber_id.
  • Brand scope is determined by the authenticated brand. If the Message Category ID does not exist or belongs to another brand, an empty Grid is returned.

Element list

Data Element Type Conditional Description
message_category_id Int True Message Category ID
message_category_name String True Message Category name
message_category_description String True Message Category description
is_message_category_active Bit True 1 = Active; 0 = Archived
subscriber_id Int True Informz subscriber ID
email String True Contact email address
user_id String True Remote ID (remote_key_ident)
user_id_source String True Remote key source (remote_key_source)
imis_name_id String True iMIS Name ID, when applicable
is_opted_out Bit True 1 = OptedOut; 0 = Available
last_modified_date Datetime True Opt-out row modification date when a row exists (active or inactive); empty when no row exists
count Int False Number of matches based on the specified criteria

Request

<GridRequest xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="2001">Example Brand</Brand>
 <User>apiuser</User>
 <Password>password</Password>
 <Grids>
  <Grid type="message_category_subscribers">
   <Conditions>
    <SingleCondition>
     <DataElement>message_category_id</DataElement>
     <Comparator>EQ</Comparator>
     <DataValue>10</DataValue>
    </SingleCondition>
   </Conditions>
   <ReturnFields>
    <DataElement>message_category_id</DataElement>
    <DataElement>message_category_name</DataElement>
    <DataElement>message_category_description</DataElement>
    <DataElement>is_message_category_active</DataElement>
    <DataElement>subscriber_id</DataElement>
    <DataElement>email</DataElement>
    <DataElement>user_id</DataElement>
    <DataElement>user_id_source</DataElement>
    <DataElement>imis_name_id</DataElement>
    <DataElement>is_opted_out</DataElement>
    <DataElement>last_modified_date</DataElement>
   </ReturnFields>
   <StartRow>0</StartRow>
   <NumberOfRows>10000</NumberOfRows>
  </Grid>
 </Grids>
</GridRequest>

Filter examples

Available contacts only:

<SingleCondition>
 <DataElement>is_opted_out</DataElement>
 <Comparator>EQ</Comparator>
 <DataValue>0</DataValue>
</SingleCondition>

Opted-out contacts only:

<SingleCondition>
 <DataElement>is_opted_out</DataElement>
 <Comparator>EQ</Comparator>
 <DataValue>1</DataValue>
</SingleCondition>

Response

<GridResponse xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="2001">Example Brand</Brand>
 <User>apiuser</User>
 <Grids>
  <Grid type="message_category_subscribers">
   <Record row="0">
    <Fields>
     <Field element="message_category_id">10</Field>
     <Field element="message_category_name">Newsletter</Field>
     <Field element="message_category_description">Monthly member newsletter</Field>
     <Field element="is_message_category_active">1</Field>
     <Field element="subscriber_id">10001</Field>
     <Field element="email">user@example.com</Field>
     <Field element="user_id">REMOTE-42</Field>
     <Field element="user_id_source">PartnerSystem</Field>
     <Field element="imis_name_id">12345</Field>
     <Field element="is_opted_out">0</Field>
     <Field element="last_modified_date"/>
    </Fields>
   </Record>
   <Record row="1">
    <Fields>
     <Field element="message_category_id">10</Field>
     <Field element="message_category_name">Newsletter</Field>
     <Field element="message_category_description">Monthly member newsletter</Field>
     <Field element="is_message_category_active">1</Field>
     <Field element="subscriber_id">10002</Field>
     <Field element="email">optedout@example.com</Field>
     <Field element="user_id">REMOTE-99</Field>
     <Field element="user_id_source">PartnerSystem</Field>
     <Field element="imis_name_id">67890</Field>
     <Field element="is_opted_out">1</Field>
     <Field element="last_modified_date" type="Date">2026-06-15T18:30:00.0000000Z</Field>
    </Fields>
   </Record>
  </Grid>
 </Grids>
</GridResponse>

Notes

  • Each contact is returned in its own row.
  • Use is_opted_out to determine availability. last_modified_date may still be populated after OptIn if an inactive opt-out remains.
  • If message_category_id with EQ is omitted, the request returns MissingData.
Was this article helpful?
0 out of 0 found this helpful
Return to top

Can’t find what you’re looking for?

Create a Case Call US Support