Knowledge Base

Create Mailing (MD1)

  • Updated

This document creates a new outbound email in Informz using Mailing Designer 1 (MD1).

Typically, several stories comprise a mailing. When the mailing is published, each story can be associated with a particular target group to facilitate dynamic content for subscribers. After the mailing has been created, it can be published to email recipients using the ScheduleMailing action.

Case sensitivity and order

The document tags are case sensitive. Make sure that the case sensitivity is respected between the calling application and API. For example, <BulkUpload> is correct but <bulkupload> is not.

However, the comparison of string values in a grid request is not case sensitive.

The order that nodes are presented within an XML document are determined by the XSD. Use the example messages provided and the graphical depiction of the XSD to ensure that the node order in the documents being submitted to the Informz API matches the order as found in the XSD.

CreateMailing

The example below illustrates a mailing comprising three stories. There can be an HTML version and a Text version of each story. Include all relevant HTML for the HTML version, including external links to URLs and images.

Request

<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="9999">Test Brand</Brand>
 <User></User>
 <Password></Password>
 <Actions>
  <CreateMailing>
   <Name>New Fall Course Offerings</Name>
   <FriendlyFrom>Office of the Registrar</FriendlyFrom>
   <EmailFrom>registrar@test.edu</EmailFrom>
   <ReplyTo>registrar@test.edu</ReplyTo>
   <Subject>Exciting new fall courses</Subject>
   <TemplateID>1</TemplateID>
   <FolderName>FolderName1</FolderName>
   <Stories>
    <Story>
     <StoryID>1</StoryID>
     <Title>Title1</Title>
     <Rank>1</Rank>
     <HtmlContent>HtmlContent1</HtmlContent>
     <TextOnlyContent>TextOnlyContent1</TextOnlyContent>
    </Story>
    <Story>
     <StoryID>2</StoryID>
     <Title>Title2</Title>
     <Rank>2</Rank>
     <HtmlContent>HtmlContent2</HtmlContent>
     <TextOnlyContent>TextOnlyContent2</TextOnlyContent>
    </Story>
    <Story>
     <StoryID>3</StoryID>
     <Title>Title3</Title>
     <Rank>3</Rank>
     <HtmlContent>HtmlContent3</HtmlContent>
     <TextOnlyContent>TextOnlyContent3</TextOnlyContent>
    </Story>
   </Stories>
  </CreateMailing>
 </Actions>
</ActionRequest>

Details

Node Type Req'd Unique Description
<EmailFrom> String False False The sender’s email address.
<FolderName> String False False The folder in which the mailing will be created.
<FriendlyFrom> String False False The display name associated with the sender’s email address.
<HTMLContent> String True False The mailing content to be sent to the recipients.
<Name> String True False Descriptive name for the mailing.
<Rank> Int False False The order of the stories within the collection. This is the order in which they will display in the mailing.
<ReplyTo> String False False The email address to send replies to.
StoryID Int True True The ID of the story.
<Subject> String True False Mailing’s subject line seen by the recipient.
<TemplateID> Int False False The template to use for this mailing.
<TextOnlyContent> String False False The text version of the mailing content. If this is not provided, Informz will generate a text version from the provided HTML content.
<Title> String True False A single story’s title.

Notes

  • A CreateMailing document will yield a Mailing type of mailing in the Informz UI.
  • HTML formatting characters (like '<') have to be replaced with XML encoded equivalents (like '&lt;').
  • Personalization (i.e., "mail merge") field names can be embedded in <HTMLContent> and <TextContent>. These fields must have '%%' on either side of the name. These personalization field names will subsequently be used in the Headers section of the SubscriberData portion of the corresponding PublishMailing ActionRequest document. The matching data for each subscriber also appears in SubscriberData. (See below for an example).
  • Any hyperlinks must be validated by the user.
  • Any images must be validated by the user. (Images are not hosted by Informz.)
  • If no <FolderName> is supplied, the mailing will be created in the main folder for the brand.
  • If the supplied <FolderName> has been deleted, an exception will be raised.
  • If no <TemplateID> is supplied, the mailing will use the default template for the brand.
  • If one of <EmailFrom>, <FriendlyFrom> and <ReplyTo> is supplied, they all must be supplied. If they are omitted, that envelope information will be taken from the template associated with the mailing.
  • If the template used is an advanced template, for each <Story>, you must supply the name of a Location in a <Location> tag.

Response

<?xml version="1.0" encoding="utf-16"?>
<ActionResponse 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></User>
 <Responses>
  <CreateMailing>
   <ActionStatus>
    <Status>success</Status>
    <Message xsi:type="xsd:string">Mailing created.</Message>
   </ActionStatus>
   <MailingID>134322</MailingID>
  </CreateMailing>
 </Responses>
</ActionResponse>

 

Node Type Description
<MailingID> Int The unique mailing ID in Informz. Use this to retrieve the mailing for editing, deleting, and scheduling the mailing for publishing.
<Message> String Further description.
<Status> Enumerated String Type What occurred in Informz for the action; valid values are success and failure.

ScheduleMailing

Schedules a new outbound email in Informz for publishing. This step occurs after a successful CreateMailing has occurred.

Request

<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
 <Brand id="9999">Test Brand</Brand>
 <User></User>
 <Password></Password>
 <Actions>
  <ScheduleMailing>
   <MailingID>408</MailingID>
   <PublishDateTime>2009-10-15T19:30:00</PublishDateTime>
   <AccountingCode>GeneralFund</AccountingCode>
   <IsTest>0</IsTest>
   <ReturnInvalidSubscribers>0</ReturnInvalidSubscribers>
   <TargetGroupAssignment>
    <DefaultTargetGroup>
     <TargetGroup>
      <Interest>
       <ReturnInvalidSubscribers>1</ReturnInvalidSubscribers>
       <TargetGroupName>New Interest</TargetGroupName>
       <SubscriberData>
        <FieldDefinitions>
         <FieldDefinition>
          <Name>First_Name</Name>
          <DataType>String</DataType>
          <DefaultValue>Customer</DefaultValue>
         </FieldDefinition>
         <FieldDefinition>
          <Name>Last_Name</Name>
          <DataType>String</DataType>
          <DefaultValue>McCustomer</DefaultValue>
         </FieldDefinition>
        </FieldDefinitions>
        <Subscribers>
         <Subscriber>
          <Email>bose@example.com</Email>
          <ID>7003</ID>
          <Fields>
           <Field element="First_Name">Satyendra</Field>
           <Field element="Last_Name">Bose</Field>
          </Fields>
         </Subscriber>
        </Subscribers>
       </SubscriberData>
      </Interest>
     </TargetGroup>
    </DefaultTargetGroup>
   </TargetGroupAssignment>
  </ScheduleMailing>
 </Actions>
</ActionRequest>

Details

Node Type Req'd Unique Description
<AccountingCode> String False False Used for internal "bill back" in a shared services model. If the accounting code does not exist, it will be created. However, if the "Accounting Codes" extension is not enabled, these will not be available through the Informz UI.
<DataType>   True False DataType of the supplied personalization field’s data.
<DefaultValue>   True False The value to be used if no value is supplied in the data.
<EmailAddress> String True False Email address.
<Fields> String False False This section, if used, contains the personalization data to satisfy the personalization (embedded) fields. If none is supplied the <DefaultValue> will be used.
<Field element=
"xxx">value</Field>		 ? False False The personalization field name followed by the value to be used.
<Header>   False False Used when Personalization is desired within the content for this mailing.
<IsTest> Int True True Values: 0=False, 1=True Indicates if this is a test version (pre-publishing) to see how the mailing looks when it reaches an inbox.
<MailingID> Int True True The unique mailing ID in Informz. Use this to retrieve the mailing for editing and deleting, and for scheduling the mailing for publishing.
<Name>   True   The name of a supplied personalization field.
<PublishDateTime> DateTime True False When the mailing is published. If no time zone is listed, it will be interpreted as GMT.
<Record>   True   The subscriber (aka emails or recipients) information.
<RemoteID> Int True True Unique ID from the partner application for this email address.
<ReturnInvalidSubscribers> Int True True Values: 0=False, 1=True Indicates if Informz is to pass back malformed email addresses in the Response document. These could subsequently be researched in the partner application.
<Status> String False False  
<SubscriberData Story ID="###"> Int False False The unique story ID for the story supplied. If none supplied, Informz will assume the HTMLContent provided is the story.
<SubscriberID> Int False False The Informz unique ID associated with this email address.
TargetGroupName String True False A descriptive name of the list of email recipients (and their personalization information if included) to be used for the publishing of this mailing.

Notes

  • After a mailing is published, a mailing instance is created. The mailing instance is where all reporting comes from.
  • If <PublishDateTime> is blank, it is presumed that the mailing is to be published "Now."
  • If <PublishDateTime> is within 7 days in the past, the mailing will be published "Now" + 1 minute.
  • <PublishDateTime> cannot be more than 7 days ago.
  • If <PublishDateTime> is passed missing either the date or the time, an exception will be raised.
  • If the mailing can't be published due to billing rules (an overdue invoice), an exception will be raised.

Response

Scheduling response example without invalid subscribers. <ReturnInvalidSubscribers> = 1 in the request.

<?xml version="1.0" encoding="utf-16"?>

<ActionResponse 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></User>
 <Responses>
  <ScheduleMailing>
   <ActionStatus>
    <Status>success</Status>
    <Message xsi:type="xsd:string"> Mailing scheduled to go out at 10/15/2009 7:30 PM</Message>
   </ActionStatus>
   <MailingID>408</MailingID>
  </ScheduleMailing>
 </Responses>
</ActionResponse>>

Details

Node Type Description
<MailingID> Int The unique mailing ID in Informz. Use this to retrieve the mailing for editing, deleting, and scheduling the mailing for publishing.
<Message> String Further description.
<Status> Enumerated String Type What occurred in Informz for the action; valid values are success and failure.

Set Mailing On Hold

Returns mailings count and request status with message.

Details

Node Type Req'd Unique Description
<ID> Int True N/A The mailing's unique ID.

Request

<?xml version="1.0" encoding="utf-8"?>
<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">  
 <Brand id="9999">Test Brand</Brand>
 <User></User>
 <Password></Password>
 <Actions>
   <SetMailingOnHold>
     <Mailings>
       <ID>1</ID>
       <ID>2</ID>
       <ID>3</ID>
       <ID>4</ID>
     </Mailings>
   </SetMailingOnHold>
 </Actions>
</ActionRequest>

Response

<?xml version="1.0" encoding="utf-16"?>
<ActionResponse 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></User>
 <Responses>
  <SetMailingOnHold>
   <Count>3</Count>
   <ActionStatus>
    <Status>success</Status>
    <Message>Set 4 mailings on hold</Message>
   </ActionStatus>
  </SetMailingOnHold>
 </Responses>
</ActionResponse>

Notes

The maximum ID Node is 1000.

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