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:

Parameter	Description
documentName	A human-meaningful name to identify the document. This is the name that will appear in the dashboard
documentFormat	The file format of the document being uploaded. `PDF` is most common, but numerous others are supported as well
documentClass	The 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`
file	The 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.