EasyPost Direct Upload

The EasyPost Application Programming Interface (API) enables automated direct uploads of documents to Bing’s communication services. Once an authenticated session is established, you can upload one or more documents and accompanying metadata. After the session ends, Bing’s backend systems validate, process, print, and lodge your mail.

Address information can be passed to the API via a metadata file. Alternatively, the auto processor can extract addresses and other metadata from within the documents themselves.

Capabilities

The EasyPost API supports a range of delivery methods, including postal, email, SMS, and fax. Examples include:

• Single addressed letter
• Single unaddressed letter (single recipient)
• Single unaddressed letter (multiple recipients)
• Multiple addressed letters (fixed or varying lengths, such as statements)
• Colour and duplex printing options
• Attachments and background templates (letterheads)
• Reference ID
• Department or cost centre specification

For a list of standard attributes, see the Reference section. Our API is easily extensible—if you need a feature that isn’t listed, contact us!

Terminology

• Mailing – A set of letters sharing common attributes, uploaded in a single session.
• Pack – An alternative name for a mailing.
• Session – A series of HTTP requests that create an instance of the Bing API.
• EPID (EasyPostID) – A session identifier that also references a mailing.

Prerequisites

All documents uploaded to Bing require destination addresses. These can be explicitly provided in a metadata file or, in many cases, extracted directly 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 or XML
Document resources: PDF, PostScript, or XPS

The metadata file can be in JSON or XML format. JSON is preferred, with examples provided in this document. For XML examples, click here. (For the full JSON specification, see RFC 7159. Note that Bing supports only UTF-8 encoded JSON.)

PDF documents should be A4 in size with all non-standard fonts embedded and transparencies flattened to ensure compatibility with Bing’s digital and print processes. Tools such as Adobe Acrobat can help preflight your documents for issues. Contact Bing Customer Service if you need assistance ensuring your files meet the required standards. (Standard fonts are defined by Adobe; see ISO 32000 Section 9.6.2.2.)

You may upload any or all files in a ZIP archive to reduce upload times if you have a large number of resource files. Be aware that some ZIP formats and options (particularly those used by "7-Zip") may be incompatible with Bing’s processes.

Each session can include both a metadata file and document files. If no metadata is provided or if the metadata lacks letter information, the files will be handled by the auto processor, which attempts to extract addresses and other metadata from within the documents.

You can also pre-upload documents via the Bing Customer Portal (Upload Documents menu) and then reference them in your metadata. If a single resource document is uploaded with its metadata, you may omit the filename from the metadata. Ensure metadata files use .json or .xml extensions.

Documents uploaded to the customer portal remain available for subsequent mailings, whereas those uploaded in the API session are only retained until the session ends. Document file references in metadata must not include file paths.

A Note About JSON: Use a proper JSON library or tool to construct and encode your metadata. Although JSON is easy to read and write, correct escaping of non-ASCII characters is error-prone if done manually. Many free and open-source libraries are available; Bing recommends the Jansson library.

Authentication

Bing supports HTTP Digest Access Authentication (preferred) or Basic Access Authentication. Only Digest Auth is offered in the usual 401 response challenge. To use Basic Auth, include a valid Authorization: Basic <base64-encoded user:password> header in your HTTP request.

Using the API – Standard Method

The recommended approach is the standard method, which supports larger upload sizes and more detailed error reporting than the multipart form mechanism. It involves three steps, using either HTTP or HTTPS:

1. get_session
2. upload
3. end_session

1. Obtain the Session ID (EPID)

Send an HTTP GET request to publicinterface/get_session_id, including your Bing account code. If Digest Auth is not already included in the request, the server will issue a 401 challenge. For example:

GET https://bingmail.com.au/publicinterface/get_session_id.text?account=TES00584

This returns a session ID (EPID) in text format. You can replace text with json or xml in the URL if you prefer a different response format.

2. Upload Metadata and Document(s)

Use the returned session ID (EPID) in an HTTP PUT request to upload your files. For example:

PUT https://bingmail.com.au/direct_upload/HY76PPLBMKK8W5TXZS/myfile.pdf

Multiple PUT transactions can be made during the same session to upload more than one file. As with metadata document references, file paths are not permitted.

3. Terminate the Session

Send an HTTP GET request to publicinterface/end_session with your session ID to conclude the process. For example:

GET https://bingmail.com.au/publicinterface/end_session.text?session_id=JC8J9MDC3TBHF2973GPYYC3D7YJ

This returns a status and a list of successfully received files, then triggers Bing’s backend processing. Your submitted letters will appear in the Bing Customer Portal, identified by their EPID.

Key steps of an EasyPost API session:

• HTTP GET (once): https://bingmail.com.au/publicinterface/get_session_id.<fmt>?account=<account>
• HTTP PUT (one or more times): https://bingmail.com.au/direct_upload/<EPID>/<filename>
• HTTP GET (once): https://bingmail.com.au/publicinterface/end_session.<fmt>?session_id=<EPID>

The following examples demonstrate how to perform these steps in various programming languages.

Example - Standard Method in Different Languages

Click to expand:

#!/bin/sh

# Host and account details
URL="https://bingmail.com.au"
AUTH="tst_bing:ABC123"
ACC=ABC12345

# Session endpoints
SESS_ID_NAME="publicinterface/get_session_id"
SESS_END_NAME="publicinterface/end_session"
UPLOAD_PREFIX="direct_upload"
FMT="text"

# Check for at least one file argument
if [ $# -lt 1 ]; then
    echo "No files provided, aborting..."
    exit 1
fi

# Build a comma-separated list of files
files=$1
while [ $# -gt 1 ]; do
    shift
    files="$files,$1"
done

# Construct the session request URI
GET_SESSION_URI="$URL/$SESS_ID_NAME.$FMT?account=$ACC"

# Obtain the session ID
session_id=$(curl -s -f --anyauth -u "$AUTH" "$GET_SESSION_URI")

if [ -n "$session_id" ]; then
    UPLOAD_URI="$URL/$UPLOAD_PREFIX/$session_id/"
else
    echo "get_session failed ($?)"
    exit 1
fi

# Upload the files
curl -s -f -T "{$files}" "$UPLOAD_URI"

if [ $? -ne 0 ]; then
    echo "File upload failed ($?)"
    exit 1
fi

# End the session
res=$(curl -s -S --anyauth -u "$AUTH" "$URL/$SESS_END_NAME.$FMT?session_id=$session_id")
curl_ret=$?

echo "$res"
exit "$curl_ret"
# -- end --

#import requests

# Configuration
account = 'ABC12345'
username = 'tst_bing'
password = 'ABC123'
url = 'https://bingmail.com.au'

# Authentication
auth = requests.auth.HTTPDigestAuth(username, password)

# Step 1: Obtain session ID
get_session_url = f"{url}/publicinterface/get_session_id.text?account={account}"
response = requests.get(get_session_url, auth=auth)
response.raise_for_status()
session_id = response.text.strip()
print(f"Session ID: {session_id}")

# Step 2: Upload files
upload_url = f"{url}/direct_upload/{session_id}/myfile.pdf"
with open('myfile.pdf', 'rb') as f:
    upload_response = requests.put(upload_url, auth=auth, data=f)
    upload_response.raise_for_status()
    print("File uploaded successfully.")

# Step 3: End session
end_session_url = f"{url}/publicinterface/end_session.text?session_id={session_id}"
end_response = requests.get(end_session_url, auth=auth)
end_response.raise_for_status()
print("Session ended. Response:")
print(end_response.text)

const axios = require('axios');
const fs = require('fs');

// Configuration
const account = 'ABC12345';
const username = 'tst_bing';
const password = 'ABC123';
const url = 'https://bingmail.com.au';

// Basic Auth Header
const auth = Buffer.from(`${username}:${password}`).toString('base64');

// Step 1: Obtain session ID
async function getSessionId() {
    const getSessionUrl = `${url}/publicinterface/get_session_id.text?account=${account}`;
    try {
        const response = await axios.get(getSessionUrl, {
            headers: {
                'Authorization': `Basic ${auth}`
            }
        });
        return response.data.trim();
    } catch (error) {
        console.error('Error obtaining session ID:', error);
        throw error;
    }
}

// Step 2: Upload files
async function uploadFile(sessionId, filePath) {
    const uploadUrl = `${url}/direct_upload/${sessionId}/${filePath.split('/').pop()}`;
    try {
        const fileStream = fs.createReadStream(filePath);
        const response = await axios.put(uploadUrl, fileStream, {
            headers: {
                'Authorization': `Basic ${auth}`,
                'Content-Type': 'application/pdf'
            }
        });
        console.log(`Uploaded ${filePath} successfully.`);
    } catch (error) {
        console.error(`Error uploading ${filePath}:`, error);
        throw error;
    }
}

// Step 3: End session
async function endSession(sessionId) {
    const endSessionUrl = `${url}/publicinterface/end_session.text?session_id=${sessionId}`;
    try {
        const response = await axios.get(endSessionUrl, {
            headers: {
                'Authorization': `Basic ${auth}`
            }
        });
        console.log('Session ended. Response:', response.data);
    } catch (error) {
        console.error('Error ending session:', error);
        throw error;
    }
}

// Full workflow
(async () => {
    try {
        const sessionId = await getSessionId();
        await uploadFile(sessionId, 'myfile.pdf');
        await endSession(sessionId);
    } catch (error) {
        console.error('API workflow failed:', error);
    }
})();

# Configuration
$account = 'ABC12345'
$username = 'tst_bing'
$password = 'ABC123'
$url = 'https://bingmail.com.au'

# Encode credentials for Basic Auth
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username,$password)))

# Step 1: Obtain session ID
$getSessionUri = "$url/publicinterface/get_session_id.text?account=$account"
$response = Invoke-RestMethod -Uri $getSessionUri -Method Get -Headers @{Authorization=("Basic $base64AuthInfo")}

$sessionId = $response.Trim()
Write-Output "Session ID: $sessionId"

# Step 2: Upload file
$uploadUri = "$url/direct_upload/$sessionId/myfile.pdf"
Invoke-RestMethod -Uri $uploadUri -Method Put -InFile "myfile.pdf" -Headers @{Authorization=("Basic $base64AuthInfo")}
Write-Output "File uploaded successfully."

# Step 3: End session
$endSessionUri = "$url/publicinterface/end_session.text?session_id=$sessionId"
$endResponse = Invoke-RestMethod -Uri $endSessionUri -Method Get -Headers @{Authorization=("Basic $base64AuthInfo")}
Write-Output "Session ended. Response:"
Write-Output $endResponse

using System.Net.Http.Headers;
using System.Text;

var account = "ABC12345";
var username = "tst_bing";
var password = "ABC123";
var url = "https://bingmail.com.au";

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic"
	, Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{password}")));

// Step 1: Obtain session ID
var sessionId = await client.GetStringAsync($"{url}/publicinterface/get_session_id.text?account={account}");
Console.WriteLine($"Session ID: {sessionId}");

// Step 2: Upload file
var fileContent = new ByteArrayContent(await System.IO.File.ReadAllBytesAsync("myfile.pdf"));
fileContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/pdf");
var uploadResponse = await client.PutAsync($"{url}/direct_upload/{sessionId}/myfile.pdf", fileContent);
uploadResponse.EnsureSuccessStatusCode();
Console.WriteLine("File uploaded successfully.");

// Step 3: End session
var endResponse = await client.GetStringAsync($"{url}/publicinterface/end_session.text?session_id={sessionId}");
Console.WriteLine($"Session ended. Response:\n{endResponse}");

Using the API - Multipart Form method

Bing’s API also supports an HTTP POST multipart form (MPF) upload, with a maximum combined file size of 20MB and limited error reporting. The advantage of MPF is that the entire session is contained in a single request. Multiple files can be included, and each file in the form is treated as part of the mailing. Methods for constructing multipart form data vary by platform.

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 more examples in Unix shell script, MS Powershell scripts and .NET C# sample code can be downloaded here.

Example - Multipart Form Method in Different Languages

Click to expand:

#!/bin/sh

# cURL example for MPF upload
# Replace login_name, password, and account with actual values
curl -v \
  -F file=@document.pdf \
  -F file=@metadata.json \
  -u login_name:password \
  "https://bingmail.com.au/publicinterface/mpf_upload?account=ABC12345"

import requests

# Python example for MPF upload using requests
account = 'ABC12345'
username = 'login_name'
password = 'password'
url = 'https://bingmail.com.au/publicinterface/mpf_upload'
files = {
    'document.pdf': open('document.pdf','rb'),
    'metadata.json': open('metadata.json','rb')
}
params = {
    'account': account
}

# Authentication - Basic or Digest
auth = (username, password)  # Basic example

response = requests.post(url, auth=auth, files=files, params=params)
print(response.status_code, response.text)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

// Node.js example for MPF upload using axios
async function mpfUpload() {
  const account = 'ABC12345';
  const username = 'login_name';
  const password = 'password';
  const url = `https://bingmail.com.au/publicinterface/mpf_upload?account=${account}`;

  const formData = new FormData();
  formData.append('file', fs.createReadStream('document.pdf'));
  formData.append('file', fs.createReadStream('metadata.json'));

  try {
    const response = await axios.post(url, formData, {
      auth: {
        username: username,
        password: password
      },
      headers: {
        ...formData.getHeaders()
      }
    });
    console.log(response.status, response.data);
  } catch (error) {
    console.error(error.response ? error.response.data : error.message);
  }
}

mpfUpload();

# PowerShell example for MPF upload
# Note this may be simplified if using Invoke-RestMethod's '-Form' parameter available on newer versions of PowerShell
$account = 'ABC12345'
$username = 'login_name'
$password = 'password'
$url = "https://bingmail.com.au/publicinterface/mpf_upload?account=$account"

# Prepare the files to upload
$files = @(
    "./file.pdf",
    "./metadata.json"
    )

# Set up the credentials
$credential = New-Object System.Management.Automation.PSCredential($username, (ConvertTo-SecureString $password -AsPlainText -Force))

# Create a form data body
$boundary = [System.Guid]::NewGuid().ToString()
$headers = @{
    "Content-Type" = "multipart/form-data; boundary=$boundary"
}

# Build the multipart form data content
$body = ""
for ($i = 0; $i -lt $files.Length; $i++) {
    $body += "--$boundary`r`n"
    $body += "Content-Disposition: form-data; name=`"file`"; filename=`"$(Split-Path $files[$i] -Leaf)`"`r`n"
    $body += "Content-Type: application/octet-stream`r`n`r`n"
    $body += [System.IO.File]::ReadAllText($files[$i]) + "`r`n"
}
$body += "--$boundary--`r`n"

# Perform the HTTP POST request with authentication
try {
    $response = Invoke-RestMethod -Uri $url -Method Post -Headers $headers -Body $body -Credential $credential -ContentType "multipart/form-data; boundary=$boundary"
    Write-Host $response
} catch {
    Write-Error "Error: $_"
}

using System.Net.Http.Headers;
using System.Text;

var account = "ABC12345";
var username = "tst_bing";
var password = "ABC123";
var url = "https://bingmail.com.au";

using (var client = new HttpClient())
{
  // Basic Auth
	client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic"
		, Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{password}")));

  // Build multipart form data
	using (var formContent = new MultipartFormDataContent())
	{
		var fileContent1 = new ByteArrayContent(File.ReadAllBytes("doc.pdf"));
		fileContent1.Headers.ContentType = MediaTypeHeaderValue.Parse("application/pdf");
		formContent.Add(fileContent1, "file", "doc.pdf");

		var fileContent2 = new ByteArrayContent(File.ReadAllBytes("metadata.json"));
		fileContent2.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json");
		formContent.Add(fileContent2, "file", "metadata.json");

		var response = await client.PostAsync(url, formContent);
		var responseBody = await response.Content.ReadAsStringAsync();
		Console.WriteLine($"Status: {response.StatusCode}, Body: {responseBody}");
	}
}

Metadata Structure

The metadata file can be JSON or XML, sharing similar element names. In JSON, primitive data types are maintained as strings in XML (Boolean values are “true” or “false”). Lists in XML and arrays in JSON are ordered by their appearance.

Both formats require a single root element:

XML

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

JSON

{
    ...
}

The root element can define mailing-wide attributes (e.g., colour model, department). It may also include a letters array to define each letter. If the letters element is omitted, the auto processor will attempt to extract addresses and other metadata from the uploaded documents themselves.

Each letter element can define address data and pages. A letter can consist of a single document or multiple documents, which you specify using the files array.

Examples

If you upload a single document alongside its metadata file, you do not need to reference the filename in the metadata. However, if multiple documents are uploaded, each document should be explicitly referenced as an attachment or as a file within a letter. If neither step is taken, only the first document will be used.

Simple JSON Examples

1. Single Letter: referencing the document "test2.pdf", with optional duplex, colour model, confirmation email, and department attributes.

{
    "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. Single Letter with Address Components: Demonstrates address elements as separate fields.

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

3. Multiple Recipients: A document 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 a 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.

Mailing Production Options

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.

Custom Data Sub Elements

Files Sub Elements

Postal Object Sub Elements

Error Handling and Troubleshooting

Understanding API responses and errors is crucial for successful integration. Below are common HTTP status codes and error messages you might encounter:

If you encounter an error, ensure your request adheres to the API specifications and your system meets all prerequisites. For persistent issues, contact support.