Knowledge Base

BulkUpload

  • Updated

This document is used to transfer larger (>1,000) subscriber lists to Informz for processing. The processing options are:

  • AddOrUpdateSubscribers
  • ReplaceAllSubscribers
  • RemoveSubscribers
  • ​UnsubscribeSubscribers
  • ResubscribeSubscribers

Upon completion of the upload process, an email notification is sent to any email addresses listed in the StatusEmailRecipients node.

Request

<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
  <Password></Password>
  <Brand id="xxxx">\</Brand>
  <User></User>
  <Actions>
    <BulkUpload>
      <UploadDetails>
        <InterestDetails>
          <InterestAction>ResubscribeSubscribers</InterestAction>
        </InterestDetails>
        <StatusEmailRecipients>
          <Email>yournamehere@informz.com</Email>
        </StatusEmailRecipients>
      </UploadDetails>
      <FieldDefinitions>
        <FieldDefinition>
          <Name>Email</Name>
          <DataType>string</DataType>
          <ColumnIndex>1</ColumnIndex>
          <FieldType>Email</FieldType>
        </FieldDefinition>
      </FieldDefinitions>
      <Data></Data>
    </BulkUpload>
  </Actions>
</ActionRequest>

Request with Demographic

<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
 <Password></Password>
 <Brand id="9999">Test Brand </Brand>
 <User></User>
 <Actions>
  <BulkUpload>
   <UploadDetails>
    <InterestDetails>
     <!-- 0 to n interest names -->
     <InterestNames>
      <InterestName>Test Interest</InterestName>
     </InterestNames>
     <!-- choices are AddOrUpdateSubscribers, ReplaceAllSubscribers or RemoveSubscribers-->
     <InterestAction>AddOrUpdateSubscribers</InterestAction>
    </InterestDetails>
    <StatusEmailRecipients>
     <Email>yournamehere@informz.com</Email>
    </StatusEmailRecipients>
    <ColumnDelimiter>,</ColumnDelimiter>
    <HasFieldsEnclosedInQuotes>1</HasFieldsEnclosedInQuotes>
    <!-- special column indexes that used to be here replaced with FieldDefinition FieldType-->
   </UploadDetails>
   <FieldDefinitions>
    <FieldDefinition>
     <Name>Email</Name>
     <DataType>string</DataType>
     <ColumnIndex>1</ColumnIndex>
     <!-- choices are PersonalInfo (default), Email, ID, Source, NewsFormat (maybe Interest and Demographics later?) -->
     <FieldType>Email</FieldType>
    </FieldDefinition>
    <FieldDefinition>
     <Name>FirstName</Name>
     <DefaultValue>Valued Customer</DefaultValue>
     <ColumnIndex>2</ColumnIndex>
     <FieldType>PersonalInfo</FieldType>
    </FieldDefinition>
    <FieldDefinition>
     <Name>API_States</Name>
     <DefaultValue>NY</DefaultValue>
     <ColumnIndex>3</ColumnIndex>
     <FieldType>Demographic</FieldType>
     <DemographicType>State</DemographicType>
    </FieldDefinition>
   </FieldDefinitions>
   <Data><![CDATA
   heck@informz.com,Tim,NY
   vincent@informz.com,Jason,NY
   shaw@informz.com,"Paul",NY
         ]]></Data>
  </BulkUpload>
 </Actions>
</ActionRequest>

Details

Node Type Req'd Unique Description

<UploadDetails>

 String True N/A Details of the file format used in the BulkUpload
<UploadDetails>
<InterestDetails>
<InterestNames>
<InterestName>		 String True   The interest(s) that all of these subscribers will be assigned to or removed from depending upon the UploadAction used. You can use multiple InterestNames
<UploadDetails>
<InterestDetails>
<InterestAction>		 String True N/A Choices: AddOrUpdateSubscribers, ReplaceAllSubscribers, RemoveSubscribers
<UploadDetails>
<StatusEmailRecipients>		 String True True The email(s) addresses to send the status message regarding the bulk upload once it is complete. Use <Email/> in the tag if you do not wish to include a value
<UploadDetails>
<ColumnDelimiter>		 String True N/A The column delimiter character used in the file.
<UploadDetails>
<HasFieldsEnclosedInQuotes>		 Bit True N/A Are values enclosed in quotation marks? This can be applied to any or all incoming columns. Even if this element is set to True, quotations are not required in the data itself.
<UploadDetails>
<RemovePersonalInfoIfBlank>		 Bit False N/A Should existing personalization values inside Informz be blanked out for personalization values included in this upload? Assumes False or NO will NOT
<UploadDetails>
<ColumnIndex>		 Integer False True

The column where the unique record identifier from the partner application resides.

<FieldDefinitions>

 N/A True N/A Details of each field in the incoming file. Not all columns in the incoming file have to be used by Informz. Columns are ignored if they are not identified in the FieldDefinitions.
<FieldDefinition>
<Name>		 String True True The corresponding personalization field in Informz. If the field does not exist it will be created. The name ‘Email’ is a reserved name to indicate the column that contains the email address. Only one column can be defined as ‘Email’.
<FieldDefinition>
<DataType>		 String True False Choices: String, Integer, Float, Date
<FieldDefinition>
<DefaultValue>		 String True False A default value to use if the column is blank.
<FieldDefinition>
<ColumnIndex>		 Integer True False Which column contains the defined value. First column is column 1.
<FieldDefinition>
<FieldType>		 String True N/A If left blank, the default value is PersonalInfo, other possible values are Email, ID, Source, NewsFormat and Demographic.

<FieldDefinition>
<DemographicType>

 String True N/A Available demographic types. Possible values: Standard, State and Country. Default is Standard type.
<FieldDefinition>
<IsMultiple>		 String True N/A For default is false. Possible values true and false.

 

Notes

  • Email address must be the first entry in the Data Record, ID is the second entry.
  • If when using ReplaceAll no "replacement" subscribers are included all subscribers are removed from the interest.
  • It is presumed that there will not be a header row in the file.
  • Data in the <Data> tag needs to be "XML-safe". This can be done either by using CDATA sections as shown in the example above or by HTML encoding the text.
  • Leading and trailing blanks will be trimmed from the field.
  • Field definitions are ignored when using the RemoveSubscribers Interest Action.
  • The only fields updated are those defined in FieldDefinitions.
  • If the ColumnDelimiter tag isn't included, the delimiter will default to a Tab.
  • Incoming email addresses are converted to all lowercase.
  • The BulkUpload request supports characters in the ANSI character set.
  • Do not use the same interest in both the <InterestDetails> and <Data> nodes, as this will produce duplicate interests in the Subscriber Details pop-up.
  • Demographic field:
  • When new demographic is created the proper target groups is created also.
  • Default demographic type is Standard.
  • When you choose State or Country type along with custom demographics, the set of available states or countries will be created.
  • Field name is responding to Demographic category name.
  • Setting the type is important only if you want to create new demographic category. If you want to extend existing one do NOT use State or Country types.
  • To explicitly include a Tab column delimiter use the format below:
        <ColumnDelimiter><![CDATA[      ]]></ColumnDelimiter>

Response

The response to a BulkUpload indicates the success or failure of the action:

<?xml version="1.0" encoding="utf-8"?>
<ActionResponse xmlns="http://partner.informz.net/aapi/2009/08/">
  <Brand id="xxxx"></Brand>
  <User></User>
  <Responses>
    <BulkUpload>
      <UploadID></UploadID>
      <ActionStatus>
        <Status>success</Status>
        <Message>Data submitted.</Message>
      </ActionStatus>
    </BulkUpload>
  </Responses>
</ActionResponse>

BulkUpload with Interests

The Informz BulkUpload message supports a list of interests that can be attached with an incoming subscriber. These interests can vary from record to record in the API message.

Comma Delimiters

This feature requires that interests be delimited with a comma. This is the only valid character for this interests. Because you must use a comma to delimit interests, you will need to choose a different character to delimit other fields. This is critical because the API will parse any comma-delimited information in the XML document as interests. The comma delimiter will need to be identified in the XML itself (see example below).

Interests are included on a per-subscriber basis. However, if you upload an interest name that does not currently exist in Informz, the upload will ignore it and continue. Every interest you attach in a comma-delimited string must already exist in Informz.

Here are the summary rules for BulkUpload XML:

  • Commas are the interest delimiters used.
  • Other characters, such as a tilde ( ~ ) must be used for other delimiters.
  • There can only be one FieldDefinition called “Interest.”
  • Interests must already exist in Informz or they will be ignored.

Example

Below is a sample XML message. The interests are provided in the comma delimited string:

<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
    <Password>apasswordgoeshere</Password>
    <Brand id="9999">Brand Name</Brand>
    <User>testuser</User>
    <Actions>
        <BulkUpload>
            <UploadDetails>
                <InterestDetails>
                    <InterestAction>AddOrUpdateSubscribers</InterestAction>
                </InterestDetails>
                <StatusEmailRecipients>
                    <Email>johndoe@informz.com</Email>
                </StatusEmailRecipients>
                <ColumnDelimiter>~</ColumnDelimiter>
                <HasFieldsEnclosedInQuotes>0</HasFieldsEnclosedInQuotes>
            </UploadDetails>
            <FieldDefinitions>
                <FieldDefinition>
                    <Name>Email</Name>
                    <DataType>string</DataType>
                    <ColumnIndex>1</ColumnIndex>
                    <FieldType>Email</FieldType>
                </FieldDefinition>
                <FieldDefinition>
                    <Name>Interest</Name>
                    <DataType>string</DataType>
                    <ColumnIndex>2</ColumnIndex>
                    <FieldType>Interest</FieldType>
                </FieldDefinition>
            </FieldDefinitions>
            <Data>
                <![CDATA[johndoe @informz.com~Test Interest,Opt-Ins interested@informz.com~Test Interest,My New Interest ]]>
            </Data>
        </BulkUpload>
    </Actions>
</ActionRequest>

If You Are Not Using the Interest Upload…

If no interests are incorporated within the XML, use commas as the standard field delimiter.

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