Using Documents, Images, Pre-Uploaded Files And Templates

There are three options for handling files when sending letters and postcards using the PostalMethods Web Services: uploading documents and images per request; pre-uploading file and using them by a reference and templates with placeholders for merging data.


OPTION 1: Upload A Document or Image Per Request

With each Web Service request, send a file as binary data. The file is converted to a PDF format and used to create your letter or postcard. See either one of the "Send" methods for specific details.

This option is the most resources consuming and should be used when sending letters or postcards that are completely different from one another.


OPTION 2: Use Pre-Uploaded Files

You may pre-upload documents and images for future use by using the UploadFile method. Provide the uploaded file a name so you could refer to it when you want to use that file for sending.

When sending a letter or a postcard, refer to the pre-uploaded file by the name you provided. Your file is converted to a PDF format and used to create your letter or postcard. See either one of the "Send" methods for specific details.

This option is most useful when sending multiple letters containing the exact same content to multiple recipients. This option is especially efficient when using postcard images. The relatively large image is uploaded once and is referred to for each postcard sent.


OPTION 3: Use A Pre-Uploaded Template To Merge Data

Use the UploadFile method to pre-upload an HTML or MIME HTML (MHT) file to be used as a template. When sending a letter or postcard, refer to this template and send only the data fields to be merged into this template. The data is merged into the template and converted to a PDF format.
See "SendLetterAndAddress" and "SendPostcardAndAddress" for specific details.

  • How To Design Your HTML or MIME HTML (MHT)

    Your HTML or MHT files must be designed according to the page size or postcard size used (see available templates). To indicate a placeholder where data is to be merged, use this format: {|field name|}

    Example: "Please reconcile your debt of ${|Amount|} no later than {|PayDay|}."
    Possible merge result: "Please reconcile your debt of $10,442.99 no later than May 11th."

    Use the MHT format to include images, such as your logo.

  • How To Construct Your XML

    • XML must be encoded as UTF8
    • XML special characters cannot be included in the content itself. Replace Less-than(<) with &lt;, Greater-than (>) with &gt;, Ampersand (&) with &amp;, Double-quote (") with &quot; and Single-quote (') with &apos;
  • How To Design Your Merge Data (XML)

    Provide an XML file containing the data to be merged into the referred template.

    XML Scheme Example
    <MergeData>
     <Field(n)>string</Field(n)>
    </MergeData>
    <MergeData>
     <CustomerName>Roy</CustomerName>
     <Amount>10,442.99</Amount>
     <PayDay>May 11th</PayDay>
    </MergeData>



    Test and make sure that the merged data does not alter your template design and does not cause adding additional pages.

    In case the XML contains data for a merge field that does not exist in the template, the request is failed. However not all merge fields in the template must be referred to in the XML.
    Example:

    Fields in HTML Fields in XML Result
    <HTML><BODY>
    Dear {|Value1|},<br>
    Your company, {|Value2|}, was 
    nominated for the {|Value3|} 
    award!
    </BODY></HTML>
    <MergeData>
     <Value1>string</Value1>
     <Value2>string</Value2>
    </MergeData>
    Not a problem. The missing "Value3" merge field is ignored and nothing is merged into that placeholder.
    <HTML><BODY>
    Dear {|Value1|},<br>
    Your company, {|Value2|}, 
    is just awesome!
    </BODY></HTML>
    <MergeData>
     <Value1>string</Value1>
     <Value2>string</Value2>
     <Value3>string</Value3>
    </MergeData>
    The merge fails since the merge data XML contains a field ("Value3") that does not exist in the HTML.