31.2.9 Message Content Structure

Each option set has requirements and restrictions for the kind and number of applicable documents that must appear in the Contents section of a Message. The requirements and restrictions for each are described here. Note that not meeting these requirements may result in the message being rejected, either by the Cloud Fax and Notifications API or later during the message processing.

The applicability of a particular document to a particular optionset may be controlled by the AddrTypeUse element within the Part element.

It may not be possible to process jobs with a large number of attachments, so the API sets a general limit on the number of attachments in a JobSubmit request as an initial safeguard. This limit is currently 500.

31.2.9.1 VoiceOptions

Jobs with VoiceOptions (voiceREACH® jobs) may be submitted with one of two contents structures, described below. With either structure, there may or may not be additional Parts for whisper or call control.

31.2.9.1.1 voice_all option

For this pattern, the Contents must include one .WAV file (a Document where DocType is set to "WAV") or a reference to a VScript/TTS stored object (a Document with an SosObject element referencing a previously created stored object of the appropriate type - the DocType of the Document may be "unspec"). The Part containing this main document must have a Treatment with the value "voice_all".

A TTS stored object may require attachments, which will be referred to by their Filename. In this case, the Contents section must include Part elements for each such file, where Treatment is "attachment", and the documents have the correct filenames and also have DocType set to "WAV".

A VScript object may contain references to TTS templates, which in turn may require audio attachments which must be present in the message in the same way (i.e. Treatment is "attachment", DocType is "WAV", and with the correct filenames.)

31.2.9.1.2 voice_live / voice_voicemail option

For this pattern, Contents includes at least two Part elements, one with Treatment set to "voice_live", along with one (or two - see below) with Treatment set to "voice_voicemail".

The document with the voice_live treatment may be a WAV file (DocType set to .WAV.) or a reference to a VScript/TTS stored object (a Document with an SosObject element referencing a previously created stored object of the appropriate type - the DocType of the Document may be "unspec").

The document with the voice_voicemail treatment may be a WAV file or a reference to a TTS stored object (VScript is not allowed for the voice_voicemail document).

If the VoiceDeliveryMethod is set to "PAMD", then there may be an additional Part with Treatment set to "voice_voicemail". This second Part will be used as the "alternate" answering machine message, used on a second delivery attempt.

As for the "voice_all" option above, TTS scripts may require audio attachments which must be present in the message (Treatment is "attachment", DocType is "WAV", and with the correct filenames.)

31.2.9.2 EnhancedEmailOptions

Jobs with EnhancedEmailOptions (messageREACH® jobs) should have a least one body Part, and may have any number of attachments (up to the API limit).

The body of the message is specified using Part elements with the Treatment set as in this table:

There should not be more than one "body" Part with each type of document. The actual message sent will depend on the recipient's Eformat.

There may be any number of pull attachments (up to the API limit), where Treatment is set to "pullfile". Pull attachments are stored by EasyLink and accessed via links in the message.

There may also be any number of push attachments (up to the API limit), where Treatment is set to "attachment". Push attachments are delivered to the recipient as part of the email delivery.

31.2.9.3 FaxOptions

Jobs with FaxOptions (faxREACH® jobs) may actually contain a variety of destination types. There ought to always be a content Part with the Treatment set to "body" (the default Treatment.) Jobs without a body will encounter errors during processing after submission.

When FaxOptions is used to send to email addresses (ordinarily handled by EmailOptions or EnhancedEmailOptions the Contents may have a body and zero or more attachments (up to the API limit). If the body is not text (generally DocType of "text", "HTML", or "HTMLLITE"), then it will be delivered as an attachment to an automatically generated text message, and any "attachment" Parts in the JobSubmitRequest will be ignored. If the body is text, then any "attachment" documents will appear as attachments to the delivered message. The filename used for the attachments may be controlled using the Filename element (which is necessary to avoid job processing errors).

When non-email addresses are used, there may only be one content Part with the Treatment set to "body". The DocType of the document referred to in that part must be appropriate for the type of destination, or the delivery will be cancelled by the switch. Additional documents may be included with the Treatment "attachment". Not all combinations of document formats may be supported - testing intended combinations is advised.

31.2.9.4 EmailOptions

Jobs with EmailOptions (which are handled by faxREACH®, which offers less sophisticated features than messageREACH®) must contain one Part with the Treatment set to "body", and may contain any number of Parts with the Treatment set to "attachment" (up to the API limit).

31.2.9.5 SmsOptions

Jobs with SmsOptions (handled by messageREACH®) must contain exactly one Part with Treatment set to "body", and with a document (or reference to a document) with DocType set to "text". Note that there is a physical limitation on the size of the SMS message, which is currently 162 multibyte characters.

31.2.9.6 MailMergeFaxOptions

Jobs with MailMergeFaxOptions (handled by faxREACH®) must contain exactly one Part with Treatment set to "body", and with a document (or reference to a document) with DocType set to "MSW". There must be no other Part elements.

When using MailMergeFaxOptions, it is essential that all destinations have exactly the same set of data fields, so the use of a Table destination (which uses a columnar format, such as CSV) is strongly recommended. Note that the FieldMapping (either defined or default) associated with the Table destination applies to the conversion of the Table data to an internal data format which may use field names that differ from the column headings. When the data is internally prepared for the MailMerge process itself, a second FieldMapping (with a different default set) associated with the MailMergeFaxOptions element is used to map the internal field names to the column headings that the mailmerge document expects to find.

The default mapping used for Table (governing column-to-field name mapping) is described in Default Field Mapping. The default mapping used for the mail merge data is described in MailMergeFaxOptions. Note that the mapping in MailMergeFaxOptions must include a mapping to the internal field "TO".

Typically, the merge field names in the merge document are expected to be the same as the column headers in the input Table, but the default mappings may interfere with this if headers that actually appear in the default mapping are used. So with the exception of the "ADDR" column heading in the input Table, it might be simplest to avoid names in the default mappings, which would make any FieldMappings unnecessary, for example:

   ADDR,RECIPE,OVENTEMP,QTY1,INGREDIENT1,QTY2,INGREDIENT2,MINUTES
   7039944276,Cake,350,2,eggs,1.5 cup,milk,40 minutes

When merge fields are used that have names that are in the default mappings, it may be necessary to use explicit FieldMapping data to ensure that they get to the MailMerge process correctly. For example, if "INS_1" is used in the input Table, the Table default mapping would convert it to the internal "INSERTS:INSERT[1]", which is not in the MailMergeFaxOptions default mapping. So one way to ensure the correct name gets to the MailMerge process would be to include this mapping in the request:

     <MailMergeFaxOptions>
      <FieldMapping>
       <Map>
        <FieldName>TO</FieldName>
        <PropertyName>TO</PropertyName>
       </Map>
       <Map>
        <FieldName>INS_1</FieldName>
        <SegmentName>INSERTS</SegmentName>
        <PropertyName>INSERT[1]</PropertyName>
       </Map>
      </FieldMapping>
     </MailMergeFaxOptions>

Other combinations of mappings are possible that would make this work, but be careful to mention all fields used.