EasyPost Direct Upload

The EasyPost Application Programming Interface provides automated direct upload of documents to Bing's communication services. The 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.

From October 2023 Bing's web servers no longer support TLSv1.0 or 1.1
Ensure your system and libraries are up-to-date

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 the list of standard attributes.
Our API is easily extensible, so if there is something you need that you can't see, call us!

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.
  • EPID - EasypostID - session identifier and mailing reference

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).

PDF documents submitted to Bing should be A4 in size,  with all non-standard fonts embedded and transparencies flattened. Documents conforming to these requirements ensure compatibility with Bing's digital and print processes. Tools such as Adobe Acrobat can preflight documents highlighting and fixing errors.  Talk to Bing Customer Service for assistance in ensuring documents meet the required standards. 
Standard fonts are as defined by Adobe. Refer ISO32000 Section 9.6.2.2. 

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 the documents can be uploaded with associated metadata in the API session. If documents are pre-uploaded, their filename(s) must be referenced in the metadata.  Where a single resource document is uploaded with its associated metadata file, the filename reference may be omitted from the metadata.

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.

A note about JSON. Bing highly recommends that a proper conformant JSON library or tool is used for constructing and encoding your JSON metadata. Although JSON is deceptively simple to read and produce, correctly escaping or encoding non-ascii characters in strings such as address data is very prone to errors if you are building the JSON "by hand".
There are many open-source free-to-use libraries and tools available. Bing uses and recommends the excellent Jansson library.

Authentication

Bing supports either HTTP Digest Access Authentication (preferred) or Basic Access Authentication. Only Digest Auth is offered in the normal 401 response challenge.
To use Basic Auth the HTTP request must include a valid HTTP Authorization: Basic <base 64 encoded user:password> header.

Using the API - standard method

The "standard" method is the recommended way of using the Bing API. It supports larger upload sizes and better error reporting than the alternative "multipart form" mechanism described below.

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

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 to the "publicinterface/get_session_id" URI. Digest Auth authentication will be requested by the server if not already supplied in the request's Authorisation header.
e.g. https://bingmail.com.au/publicinterface/get_session_id.text?account=TES00584
This will return a session ID (EPID) 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.
e.g. https://bingmail.com.au/direct_upload/HY76PPLBMKK8W5TXZS/myfile.pdf
(Note that PUT can not normally be generated from a web browser).  Multiple files can be uploaded in the session by using as many PUT transactions as necessary. As with the metadata document file references, file paths are not permitted.

Terminate the session

End the session with another HTTP GET verb to the "publicinterface/end_session" endpoint with the session ID appended. As for get_session, authentication is required.
e.g. https://bingmail.com.au/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 an EasyPost API session:

HTTP GET (once only) - https://bingmail.com.au/publicinterface/get_session_id.<fmt>?account=<account>
for getting the EPID.

HTTP PUT (one or more times) - https://bingmail.com.au/direct_upload/<EPID>/<filename>
for uploading metadata and PDF files.

HTTP GET  (once only) -  https://bingmail.com.au/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. Note that curl's -T option supports uploading multiple files by automatically creating multiple PUT transactions for you.

Using the API - Multipart Form method

Bing's API also supports  HTTP POST "multipart form" file upload (MPF), albeit with some restrictions: the maximum combined upload file size is 20Mbytes and limited error reporting.  The main advantage of MPF over the "standard" method is that the entire session is contained in a single step.  As with the standard multi-step process, multiple files may be uploaded in a single instance.  All parts (files) of the MPF are considered to be part of the mailing.  The methods for constructing the FORM data vary widely amongst different platforms. A sample command using "curl" (Windows/Unix/Linux/MacOS) that will upload 2 files, document.pdf and metadata.json, is:

       curl -v -F file=@document.pdf -F file=@metadata.json -u login_name:password https://bingmail.com.au/publicinterface/mpf_upload?account=ABC12345

The filenames, of course,  may be anything you choose, and the login name, password and account must be as supplied by Bing Customer Service.

 

The metadata  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 of standard 3-step method.

#!/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://bingmail.com.au"

# authentication
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://bingmail.com.au/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://bingmail.com.au/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 -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://bingmail.com.au/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": "SP12345",
	"purchase_order": "PO_1234",
	"terminal": "host_007",
	"cust_hold": true,
        "attachments": ["attachment.pdf"],
        "production_options": {
            "aup_dlvtyp": 0
        },
	"orientation": 1,
	"letters": [{
		"postal": ["John Smith",
		"3 Gold Rd",
		"WESTLEIGH NSW 2102"
		],
		"primary": "postal",
		"reference": "REF1",
		"custom_data": {
			"CustomField1": "CustomVal1",
			"Custom2": "CustomVal2"
		},
		"files": [{
			"file_name": "letters.pdf",
			"page_start": 0,
			"page_end": 0
		}]
	},
	{
		"email": "test@example.com",
		"postal": "Smith Jones\n33 Gold Rd\nWESTLEIGH NSW 2102",
		"primary": "email",
		"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 password protected 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",
		"custom_data": {
			"password": "sTRING_77-68" 
	},
	{
		"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 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
6 - mono with first page colour attachments
7 - colour with first page colour attachments
8 - first page colour with first page colour attachments
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 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.
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. For use with text only email. 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).
String (no replies). Must be pre-approved.
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 or 1 for regular (default).
force_c4 boolean n Set to true to use c4 envelope stock.

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).

Note. If the attachments field is not provided and multiple files are specified for a letter, the first document is marked as letters and the remainder as attachments.
A document cannot be both a letter and an attachment.

Custom Data sub elements
password string n   Add a password for protecting a PDF delivered by email or SMS.

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