Send Postcard API
Overview
Discover how to use the Send Postcard API to programmatically send postcards via U.S. mail. Ensure your account balance is adequate and remember to cancel test postcards to avoid extra charges.
Step-by-Step Tutorial
Get your DocuPost API token from the API settings page.
Prepare the front and back images for your postcard. Make sure they are 1875 x 1275 pixels and in PNG format.
Collect your recipient's and your own addresses. Include names, street addresses, cities, state abbreviations, and ZIP codes.
Create a POST request to https://app.docupost.com/api/1.1/wf/sendpostcard with your API token and all relevant parameters.
Send the POST request.
Check the status of your sent postcard on the DocuPost Dashboard.
Using the Send Postcard API
API Endpoint and Authentication
To send a postcard using the DocuPost API, you need to make a POST request to the endpoint URL: https://app.docupost.com/api/1.1/wf/sendpostcard.
Validate Your Data
Ensure all query string parameters are correct. For example, use valid character limits and 2-letter state abbreviations.
Authentication is done via an API token, which must be included in the query string of your request. Your DocuPost account API token is used to authenticate all API requests. Make sure not to share your API token with untrusted applications or users, as it grants access to your account.
Put together, your POST request URL would look something like this:
https://app.docupost.com/api/1.1/wf/sendpostcard?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&front_image={YOUR_FRONT_IMAGE_URL}&back_image={YOUR_BACK_IMAGE_URL}
Send Postcard API Parameters (Query String)
Query String Parameter | Description | Requirements | Optional | Mandatory |
|---|---|---|---|---|
api_token | Your DocuPost account API token. | String, generate here. | No | Yes |
front_image | Image URL for the front of the postcard. Recommended PNG. | 1875 x 1275 pixels | No | Yes |
back_image | Image URL for the back of the postcard. Recommended PNG. | 1875 x 1275 pixels | No | Yes |
to_name | Name of the recipient. | String, less than 40 characters | No | Yes |
to_address1 | Address line 1 of the recipient. | String | No | Yes |
to_address2 | Address line 2 of the recipient. | String | Yes | No |
to_city | City of the recipient. | String | No | Yes |
to_state | 2-letter U.S. state code of the recipient. | 2-letter abbreviation | No | Yes |
to_zip | 5-digit postal code of the recipient. | Numeric | No | Yes |
from_name | Name of the sender/return address. | String, less than 40 characters | No | Yes |
from_address1 | Address line 1 of the sender/return address. | String | No | Yes |
from_address2 | Address line 2 of the sender/return address. | String | Yes | No |
from_city | City of the sender/return address. | String | No | Yes |
from_state | 2-letter U.S. state code of the sender/return address. | 2-letter abbreviation | No | Yes |
from_zip | 5-digit postal code of the sender/return address. | Numeric | No | Yes |
description | An optional internal note. Visible in subsequent CSV exports and in dashboard. | Optional | None | Max 40 characters |
Errors and Troubleshooting
When using the Send Postcard API, you might encounter some common errors. Here's how to handle them.
One frequent issue is an incorrect image size. The front and back images of your postcard must be 1875 x 1275 pixels. If the images are not the correct size, the mailing will fail. Double-check your image dimensions and format before making the API call.
Check Your Image Size
Make sure your front and back images are 1875 x 1275 pixels. Incorrect sizes will cause mailing failures even if the API request succeeds.
You might also face errors due to invalid query string parameters. Ensure that all parameters match the required formats, such as the 2-letter state abbreviation code and character limits for names and addresses. Accurate data entry is essential for a successful API request.
Another common problem is having an insufficient account balance. Verify your account balance before sending postcards to prevent any interruptions. You can review your balance and add funds if necessary.
If you continue to experience issues after troubleshooting, please reach out to us for additional help. Our support team can assist you with more specific problems.
Frequently Asked Questions
PNG is recommended for the front and back images of your postcard. The images should be 1875 x 1275 pixels.
Go to the detail page for your mail in DocuPost by clicking Postcards from the left sidebar. If you are within the cancellation window, a Cancel send button will appear in the upper right corner. Click this button to cancel the postcard.
If the address is invalid, your mail will fail to send. Ensure all required address fields are correctly filled, including the correct 2-letter U.S. state abbreviation.
You can check your account balance by logging into your DocuPost account and navigating to the Funds section. Here, you will see your current balance and available funding options.