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.

 
 
 

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"></Field> </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.

 
 
 

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"></Field> </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