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

ResponseStatusDescription
2000Success
4009One of the required parameters is missing.
4009Parameter 'file' is must.
4009Only pdf, doc, docx, pub, ppt, pptx, png, jpeg, and odt formats are allowed.
4001Duplicate Document
4002Document Dimensions outside of range
4003custom error message related to PageCountException
4004Could not render document
4005custom error message related to PreflightException

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