An application programming interface that allows the automated direct upload of documents to Bing's communication services.

The EasyPost Web API establishes an authenticated session allowing upload of a document or set of documents and associated metadata. After completing the session the Bing backend systems will validate, process, print and lodge your mail.

Addressing information is provided to the API via a metadata file or alternatively, the auto processor can extract address and other metadata from within the documents.

Capabilities

All existing EasyPost Mailroom client functionality, postal, email, SMS and fax delivery, including:

  • Single addressed letter
  • Single unaddressed letter, single recipient
  • Single unaddressed letter, multiple recipients
  • Multiple addressed letters (fixed or varying length, e.g. statements)
  • Colour & duplex options
  • Attachment and background template (letterhead) capability
  • Reference ID
  • Department/Cost centre specification

See the reference section for a complete list of available attributes.

Terminology

Mailing - a set of letters sharing common attributes, uploaded in a single session.

Pack - an alternate name for a mailing.

Session - a sequence of http events that provide an instance of the Bing API.

Prerequisites

All documents submitted to Bing require destination addresses. Destination addresses can be explicitly provided by accompanying the documents with "metadata", or in many cases the address data can be extracted from within the document itself.

To use the EasyPost Web API you will need:

  • A Bing customer account.
  • A Bing portal user account and password.

File Formats

Letter metadata  - JSON and XML
Document resources – PDF, Postscript and XPS

The metadata file can be presented to the EasyPost Web API in either JSON (Java Script Object Notation), or XML (eXtensible Markup Language) format. JSON is the preferred format with examples provided in this document. Click here for XML examples.  (For the full JSON specification see RFC 7159.  Note that Bing supports only UTF-8 encoded JSON).

Any (or all) of the files to be uploaded may be contained in a ZIP archive.  This can significantly reduce the upload time if a large number of resource files are to be included in a mailing.  (Note that some ZIP formats and options are incompatible with Bing's processes - notably files created using the "7-Zip" tool).

Each session may contain a metadata file along with document files to be uploaded and processed.  If no metadata is provided or the metadata provided does not include letter information, the uploaded files will be processed through the auto processor which extracts address and other metadata from within the documents.

Documents may be pre-uploaded via the Bing Customer Portal’s Upload Documents menu and referenced by the metadata, or uploaded with associated metadata in the API session. If documents are pre-uploaded, their filename MUST be referenced in the metadata.  Where a single resource document is uploaded with its associated metadata file, the filename reference may be omitted.

Metadata files must use a file extension that reflects format i.e. ".json" or ".xml".

Documents pre-uploaded to the Bing customer portal remain available for subsequent (re)use whereas documents uploaded during the API session are not retained after the end of the session.

Document files referenced within metadata must not contain file paths.

Using the API

After preparing the file(s) to upload, the API is accessed through a 3 step HTTP or HTTPS sequence:

Obtain the session ID (EPID)

Using the Bing account code, the portal username and upload password, a session ID is requested.  This uses the HTTP GET verb with "Digest AUTH" authentication to the "publicinterface/get_session_id" URI.
e.g. https://www.easymail.com/publicinterface/get_session_id.text?account=TES00584
This will return a session ID in text format. By changing the "text" suffix to "json" or "xml", the session ID can be returned in alternative formats.

Upload metadata and document(s)

Using the supplied session ID, a URL is constructed for uploading the file(s) using the HTTP PUT verb.  Multiple files can be uploaded in the session. As with the metadata document file references, file paths are not permitted.
These must also include "Digest AUTH" authentication using the same username and password as for step 1.

Terminate the session

End the session with another HTTP GET verb, with the same username and password, to the publicinterface/end_session endpoint with the session ID appended.
e.g. https://www.easymail.com/publicinterface/end_session.text?session_id=JC8J9MDC3TBHF2973GPYYC3D7YJ
This will return a status and list of the files that were successfully received. It will then trigger the back-end processing of the uploaded resources.
Submitted letter(s) will appear in the Bing customer portal, identifiable by their EPID.

The key elements of any EasyPost API script are:

HTTP GET - https://www.easymail.com/publicinterface/get_session_id.<fmt>?account=<account>
for getting the EPID.

HTTP PUT - https://www.easymail.com/direct_upload/<EPID>/<filename>
for uploading metadata and PDF files.

HTTP GET - https://www.easymail.com/publicinterface/end_session.<fmt>?session_id=<EPID>
to end the session and trigger processing of the mailing.

The unix bourne shell API script example below provides a basic working example of a session that will upload all the files given as command line arguments. It uses the widely available "cURL" program to do the HTTP work.

The examples provide samples of minimum data (i.e. recipient address) required to send a single letter. Uploading this with a PDF or postscript file is all that is required to post a single document using default settings.
Adding additional letter segments enables sending of the same document to multiple addresses see example 3 below.

A zip archive containing the following example Unix shell script, MS Powershell scripts and .NET C# sample code can be downloaded here.

Unix bourne shell script example.

#!/bin/sh
 
#
# Demo script for direct pdf upload.  This script will upload all
# files provided as arguments on the command line
#
 
# host and port for the web service
URL="https://easymail.com"
 
# authentication (username:password)
AUTH="tst_bing:ABC123"
ACC=ABC12345
 
# session control endpoints
SESS_ID_NAME="publicinterface/get_session_id"
SESS_END_NAME="publicinterface/end_session"
 
# upload endpoint prefix
UPLOAD_PREFIX=direct_upload
 
# format of the webservice output - values can be text, json or xml
# this script needs text format.
FMT=text
 
if [ $# -lt 1 ] ; then
         echo no files, aborting...
         exit 1
fi
 
# build a list of files from the command line args
files=$1
while [ $# -gt 1 ] ; do
         shift
         files="$files,$1"
done
 
# construct the session request URI
# example:
# https://www.easymail.com/publicinterface/get_session_id.text?account=ABC12345
 
GET_SESSION_URI="$URL/$SESS_ID_NAME.$FMT?account=$ACC"
 
# get the session_id/epid - uses http GET method
session_id=`curl -s -f --anyauth -u $AUTH $GET_SESSION_URI`
 
if [ "$session_id" != "" ] ; then
 
         # use the session ID from the previous call to build the upload uri 
         # NB: it must have a trailing "/"
         # example:
         # https://easymail.com/direct_upload/JC8J9MDC3TBHF2973GPYYC3D7YJK/<filename>
 
         UPLOAD_URI="$URL/$UPLOAD_PREFIX/$session_id/"
else
         echo "get_session failed ($?)"
         exit 1
fi
 
# upload the resource and meta files - uses http PUT method
curl -s -f --anyauth -u $AUTH -T "{$files}" $UPLOAD_URI
 
if [ $? != 0 ] ; then
         echo "file upload failed ($?)"
fi
 
# end the session - this starts the processing and returns upload confirmation
# uses http GET method
# example:
# https://easymail.com/publicinterface/end_session.text?session_id=JC8J9MDC3TBHF2973GPYYC3D7YJK
 
res=`curl -s -S --anyauth -u $AUTH \
         $URL/$SESS_END_NAME.$FMT?session_id=$session_id`
 
curl_ret=$?
echo $res
exit $curl_ret
# -- end --

Metadata Structure

The uploaded metadata file can be in either JSON or XML formats. The element names in both are mostly the same and primitive data types in JSON format are strings in XML (Boolean values are ‘true’ and ‘false’). Lists of values in XML and arrays in JSON are indexed in order of appearance.

The metadata must have one root element containing all the information.

XML root element (for complete XML examples click here).

<?xml version="1.0" encoding="utf-8"?>
<pack>
…
</pack>

The JSON file must simply have one root object.

{
...
}

The root element contains several optional entries which are useful for defining attributes applicable to all letters such as colour model and department (see Mailing Attributes). The list of elements supplied may include a letters element which is used to define a list of letters. If the letters element is not present, the auto processor will extract address and other metadata from within the documents.

JSON:

{
	"letters": [{
		…
	},
	…,
	{
		…
	}]
}

Each letter element defines attributes specific for a particular letter including address and pages (see Letter Metadata).

Letter metadata without any documents is useful when a letter consists of a single document. For example this is the metadata for a postal letter which includes all the pages of singe uploaded document:

"letters": [{
	"postal": ["Mr A B Sample",
	"123 Sample Street",
	"SUBURB NSW 2999"]

To include only part of the document use the ‘page_start’ and/or ‘page_end’ elements (see Letter Metadata).

It is possible to include several documents in the letter. In such case the element ‘files’ must exist. This element defines the array of documents used for constructing the letter. Here is a definition of a letter composed of two parts: the first part is the first 4 pages of letters.pdf and the second is a whole document from the file named attachment.pdf.

{
	"letters": [{
		"postal": ["Mr A B Sample",
		"123 Sample Street",
		"SUBURB NSW 2999"],
		"files": [{
			"file_name": "letters.pdf",
			"page_start": 0,
			"page_end": 3
		},
		{
			"file_name": "attachment.pdf"
		}]
	}]
}

 

Examples

In the case where a single document is uploaded with its associated metadata file, no filename reference is required. If more than 1 document is uploaded then each document should either be marked as attachments, to go to all recipients, or referenced as a file within a letter.  If neither is done then only the 1st uploaded document will be used.

Simple JSON Examples

1. Single letter referencing the document "test2.pdf", duplex, colour model, confirmation email and department fields are optional.

{
	"duplex": true,
	"colour_model": 1,
	"department": "Department1",
	"customer_email": "somebody@example.com",
	"letters": [{
		"postal": ["Mr A B Sample",
		"123 Sample Street",
		"SUBURB NSW 2999"],
		"file_name": "test2.pdf"
	}]
}

2. This example contains address components only, for a single letter uploaded with its associated document. It demonstrates address elements as separate fields.
In the case where a single document is uploaded with its associated metadata file, no filename reference is required.

"postal": ["Mr A B Sample",
"123 Sample Street",
{
	"suburb": "SUBURB",
	"region": "NSW",
	"postcode": "1234"
},
{
	"country": "AUS"
}]

3. In this example a document is sent to multiple recipients.

{
	"duplex": true,
	"colour_model": 1,
	"department": "Department1",
	"customer_email": "somebody@example.com",
	"letters": [{
		"postal": ["Mr A B Sample",
		"123 Sample Street",
		"SUBURB NSW 2999"],
		"reference": "123abc"
	},
	{
		"postal": ["Mrs B C Sample",
		"456 Sample Street",
		"SUBURB NSW 2999"],
		"reference": "456def"
	}]
}

Full JSON Example

{
	"duplex": true,
	"colour_model": 1,
	"title": "Example JSON",
	"customer_email": "z@b.com.au",
	"confirmation_email": true,
	"profile": "Invoices",
	"department": "Invoices",
	"purchase_order": "PO_1234",
	"terminal": "host_007",
	"cust_hold": true,
	"orientation": 1,
	"attachments": ["attachment.pdf"],
	"production_options": {
		"aup_dlvtyp": 0,
		"c4_staple": false,
		"force_c4": false,
		"archive": false
	},
	"letters": [{
		"postal": ["John Smith",
		"3 Gold Rd",
		{
			"locality": "WESTLEIGH",
			"state": "NSW",
			"postcode": "2102"
		},
		{
			"country": "AUS"
		}],
		"primary": "postal",
		"reference": "REF1",
		"custom_data": {
			"CustomField1": "CustomVal1",
			"Custom2": "CustomVal2"
		},
		"files": [{
			"file_name": "letters.pdf",
			"page_start": 0,
			"page_end": 0
		}]
	},
	{
		"fax": "012345678",
		"postal": "Smith Jones\n33 Gold Rd\nWESTLEIGH NSW 2102",
		"primary": "fax",
		"files": [{
			"file_name": "letters.pdf",
			"page_start": 1,
			"page_end": 1
		},
		{
			"file_name": "attachment.pdf"
		}]
	}]
}

JSON Example - SMS text only (no document)

{
	"title": "SMS Mailout",
	"department": "Marketing",
	"profile": "Marketing",
	"template": "{custom_data.msg}",
	"email_from": "marketing@b.com.au",
	"email_subj": "Changes to your account",
	"letters": [{
		"sms": "0123456789",
		"custom_data": {
			"msg": "This is the variable message"
		}
	},
	{
		"sms": "inbox@example.com",
		"custom_data": {
			"msg": "This is the next variable message"
		}
	}]
}

JSON Example – SMS with linked document

{
	"title": "SMS Mailout",
	"department": "Marketing",
	"profile": "Marketing",
	"template": "See document for details {HYPERLINK}",
	"email_from": "marketing@b.com.au",
	"email_subj": "Changes to your account",
	"letters": [{
		"sms": "0123456789",
		
	},
	{
		"sms": "inbox@example.com"
	}]
}

Reference

Mailing Attributes

Mailing Attributes apply to all letters within a mailing. If an attribute is not specified its value is set from pre-configured or default profiles.

Name Type Required Notes
duplex boolean n Set to true for duplex (double sided) printing
colour_model integer or string n 0 - mono, 1 - full colour, 2 - first page colour, 3 - first page colour with colour attachments, 4 - mono with colour attachments, 5 - colour with mono attachments. String values supported are: "mono" (=0) and "colour" (=1). Eg. "colour_model":"colour"
title string n User-friendly name identifying the mailing
customer_email string n Email address of the recipient of confirmation emails
confirmation_email boolean n If set to true a confirmation email will be sent to the address specified in customer_email
department string n Department name.
purchase_order string n Purchase order to be added to your Bing invoice. Each unique purchase order will create a separate invoice.
profile string n Profile name for selecting preset mailing attributes.
terminal string n Computer name from which the mailing was sent.
cust_hold boolean n When set to true the pack will remain on hold until customer releases from the Bing Customer Portal.
orientation integer or string n Orientation of the document pages. Possible values are 0 - orientation will be calculated from page dimensions; 1 – set portrait orientation for all pages; 2 – set landscape orientation for all pages. String values portrait (=1) or landscape (=2) are also supported.
attachments array n List of document names to be used as attachments. All other documents uploaded in the current session are considered letters. If this field is not provided and multiple files are specified for particular letter, the first document is marked as letters and the remainder as attachments. If attachment is not explicitly referenced in any letter it is appended to all letters.
production_options object n Defines production options that can be applied to a mailing. See details below.
template string n SMS or email body text. Templates may contain special markers for interpolation from letter data, or http hyperlink references to letter pdf documents. Contact Bing Customer Service for details.
sms_from string max 10 chars n Set to a mobile number (replies to this number).
Blank or unset (replies to bing).
Arbitrary string (no replies).
email_from string n Email "From" address.
email_subj string n Email subject.
letters array n Defines the letter object(s) within the mailing. See details below.

Mailing Production Options

aup_dlvtyp integer n Australia Post delivery service type - 0 for priority (default) or 1 for regular.
force_c4 boolean n Set to true to use c4 envelope stock.
c4_staple boolean n Set to true to always staple c4 letters.
archive boolean n Set to true to use account archive rules.

Letter Metadata

Data applying to a letter within a Mailing.  All elements are optional, however at least one of ‘postal’, ‘email’, ‘fax’ or ‘sms’ must be specified.

Name Type Required Default Notes
postal string or array for postal delivery   Text string containing the postal address (newline separated) or array of strings of postal address lines. For an array, each line is either a string value or contains sub-elements explicitly specifying postal address parts. In JSON format this element is an array of objects. If the line contains sub-elements the ‘country’ element can only be specified alone in one line (usually last) and the rest must be specified together in one line (last or previous). See Postal Address Example.
email string n   Recipient email address
fax string n   Recipient fax number
sms string n   Short message recipient address can be either a mobile number or email address.
primary string n see notes postal, email, sms or fax.
If not specified the primary address is chosen between the addresses provided, in order of sms, fax, email, postal.
reference string n   Add a searchable customer reference to each letter
custom_data variable n   List of elements used to control special features of Bing backend process (consult Customer Service for details)
file_name string n document name Specify the document’s filename.
Used when a single document is specified in a letter.
page_start integer n 0 Specify the first page of the letter. It is a 0 based index of a page in the document.
page_end integer n no. of pages - 1 Specify the last page of the letter. It is a 0 based index of a page in the document.
files array n   List of elements where each element specifies options for 1 or more documents included in the letter. In JSON format this element is an array of objects. (See below).

Files sub elements

file_name string n document name Specify the document’s filename.
page_start integer n 0 Specify the first page of the letter. It is a 0 based index of a page in the document.
page_end integer n no. of pages - 1 Specify the last page of the letter. It is a 0 based index of a page in the document.

Postal object sub elements

locality or suburb string n   Suburb
region or state string n   State
postcode string n   Postcode
country string n   Country