Upload a Document

The first step in mailing a document is to upload the document to be mailed! This is done using a POST to the /documents endpoint. The /documents endpoint takes four parameters:

ParameterDescription
documentNameA human-meaningful name to identify the document. This is the name that will appear in the dashboard
documentFormatThe file format of the document being uploaded. PDF is most common, but numerous others are supported as well
documentClassThe physical type of document being sent. In this example, we are sending a standard letter-sized document using the class Letter 8.5 x 11
fileThe actual binary file to uploaded

The Python sample below demonstrates uploading a letter-sized file named TestLetter.pdf to the awesomeuser account in the staging environment.

# Load the HTTP requests and encoder modules
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

# Define the endpoint to use (STAGE in this case)
url = "https://stage-rest.click2mail.com/molpro/documents"

# Define credentials
myusername = 'awesomeuser'
mypassword = 'gReAt/PaSsWoRd123'

# Define the local file to upload
fileName = '\local_path\TestLetter.pdf'

# Set up parameters for calling the endpoint
# The API enforces strict HTTPS, so the payload
# needs to be encoded
# The 'file.pdf' value in the 'file' value tuple 
# is a placeholder whose file extension must 
# match the document type, but whose name does not matter
mp_encoder = MultipartEncoder(
    fields={
        'documentFormat': 'PDF',
        'documentName': 'Test Letter PDF',
        'documentClass': 'Letter 8.5 x 11',
        'file': ('file.pdf', open(fileName,'rb'), 'application/pdf')
    }
)
headers = {'user-agent': 'my-app/0.0.1','Content-Type': mp_encoder.content_type}

# Make the POST call
r = requests.post(url, auth=(myusername, mypassword), headers=headers, data=mp_encoder)

# Display the result - a success should return status_code 201
print(r.status_code)

# Display the full XML returned. The new document_id will be in 
# <document>
#   <id>document_id</id>
# <document>
print(r.text)

A successful call should return an HTTP 201 status and the XML similar to the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document>
    <id>12902503</id>
    <status>0</status>
    <description>Success</description>
    <pages>1</pages>
</document>

HTTP Return Codes And Possible Statuses

Response

Status

Description

200

0

Success

400

9

One of the required parameters is missing.

400

9

Parameter 'file' is must.

400

9

Only pdf, doc, docx, pub, ppt, pptx, png, jpeg, and odt formats are allowed.

400

1

Duplicate Document

400

2

Document Dimensions outside of range

400

3

custom error message related to PageCountException

400

4

Could not render document

400

5

custom error message related to PreflightException

HTTP Response 500. If you get a 500 response please contact Click2Mail customer support.