Send Letter API
Overview
Use the Send Letter API to programmatically send letters via U.S. mail through DocuPost.
Step-by-Step Tutorial
Generate and obtain your API token from your DocuPost account.
Open your preferred API client or tool.
Set the request method to POST and the endpoint to https://app.docupost.com/api/1.1/wf/sendletter
Include the API token as a query string parameter (api_token).
Prepare the query string parameters required for your letter, such as recipient and sender details and document URL. Make sure all fields meet the required format and character limits.
Send the API request with all the parameters.
Check the response status to verify whether the request was successful.
If any errors occur, review the error message for details and correct any issues without re-sending the letter.
Cancel any test letters within an hour to ensure they are not mailed
Using the Send Letter API
Endpoint and Method
To send a letter using the DocuPost API, use the following endpoint and HTTP method:
Endpoint: https://app.docupost.com/api/1.1/wf/sendletter
Method: POST
Here is an example of a complete API request with parameters:
https://app.docupost.com/api/1.1/wf/sendletter?api_token={YOUR_API_TOKEN}&to_name=John Doe&to_address1=123 Test Ln&to_city=Los Angeles&to_state=CA&to_zip=90210&from_name=Sender Corp&from_address1=123 Test Rd&from_city=Los Angeles&from_state=CA&from_zip=90210&pdf=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
API Authentication
To authenticate API requests with DocuPost, you need to use an API token. This token confirms your identity and grants access to the DocuPost services.
It is important to keep your API token secure. Do not share it with untrusted applications or users, as it can be used to access your account and send mail on your behalf.
You can generate your API token in your DocuPost account settings. Make sure to store it in a safe place and use it carefully to ensure the security of your communications.
Secure Your API Token
Keep your API token confidential. Do not share it with untrusted sources. Generate your secure token in the DocuPost dashboard under API settings.
Query String Parameters
Send Letter API Parameters
Query String Parameter | Description | Required/Optional | Default Value | Constraints |
|---|---|---|---|---|
api_token | Your DocuPost account API token. | Required | None | Do not share with untrusted entities. |
A valid PDF URL for the document. | Required unless html is sent via request body | None | Max 10MB, 8.5x11 size recommended. | |
color | Whether the document should be in color. | Optional | false | "true" or "false" |
doublesided | Whether the document should be printed double-sided. | Optional | true | "true" or "false" |
class | Type of mail class. | Optional | usps_first_class | "usps_first_class" or "usps_standard" |
servicelevel | Service level for first class mail. "class" must be set to "usps_first_class" | Optional | None | "certified", "certified_return_receipt" |
return_envelope | Include a return envelope. | Optional | false | "true" or "false" |
to_name | The recipient's name. | Required | None | Max 40 characters |
to_company | Additional company or attention line for the recipient. | Optional | None | Max 40 characters |
to_address1 | The recipient's address. | Required | None | None |
to_address2 | Second address line for the recipient. | Optional | None | None |
to_city | The recipient's city. | Required | None | None |
to_state | The recipient's U.S. state abbreviation. | Required | None | 2-letter code |
to_zip | The recipient's 5-digit ZIP code. | Required | None | None |
from_name | Your name or organization's name. | Required | None | Max 40 characters |
from_address1 | Your address. | Required | None | None |
from_address2 | Second address line for your address. | Optional | None | None |
from_city | Your city. | Required | None | None |
from_state | Your U.S. state abbreviation. | Required | None | 2-letter code |
from_zip | Your 5-digit ZIP code. | Required | None | None |
description | An optional internal note. Visible in subsequent CSV exports and in dashboard. | Optional | None | Max 40 characters |
Request Body Schema
The Send Letter API offers an advanced feature that allows you to send raw HTML content instead of a PDF URL. This can be useful when you need more flexibility in creating the layout and design of your letter directly within your application. When taking advantage of this, send an "html" field in the request body (not query string parameter)
Event body | Description | Required/Optional | Default Value | Constraints |
|---|---|---|---|---|
html | Raw HTML content in lieu of a "pdf" URL query string parameter. | Optional | None | Max 9000 characters |
Use raw HTML content when your letter requires dynamic content generation or specific formatting that is easier to achieve with HTML.
This feature is helpful if you need to integrate complex data from your system directly into the letter without converting it to a PDF first.
However, keep in mind that sending raw HTML comes with a character limit of up to 9,000 characters. Additionally, adapting HTML formatting for print can be challenging as the layout may not always translate perfectly from web to print.
If you choose this advanced option, make sure to thoroughly test your HTML content to ensure it prints as expected. Adjustments may be necessary to achieve the desired appearance in the final mailed letter.
Testing and Cancelling
When testing the Send Letter API, it's important to cancel test letters to ensure they are not mailed and your funds are refunded. This helps avoid unnecessary charges and ensures proper testing of the system without real-world consequences.
To cancel a letter, you must do it within an hour of sending. This will ensure that your test letter is not processed and mailed by DocuPost. If canceled on time, the amounts deducted from your account will be refunded automatically.
Frequently Asked Questions
If the API fails, check the error message displayed on your Dashboard. Ensure all query string parameters are correct, such as character limits and state abbreviations.
DocuPost displays a specific error or reason on your detail page if there are issues during the mailing process. You can make corrections without needing to re-send your letter.
Recipient and sender names must be less than 40 characters. Address lines must be in the correct format, and states should use 2-letter abbreviations.
Do not share your API token with untrusted applications or users. Keep it confidential to ensure the security of your account.