How to Mail Documents (PDF) via OCW API

How to Mail Documents (PDF) via OCW API

Guide: How to Mail Documents (PDF)

Welcome! This comprehensive guide will walk you through mailing PDF documents physically to any destination address. With a single API request, you can upload your document, specify sender and recipient details, and trigger physical mailing—all in one step!

Important: About Sandbox vs Production

This article uses Sandbox environment for all examples and testing. The Sandbox allows you to test the complete workflow without processing real payments or mailing actual documents.

Ready for Production? When you're ready to go live, simply switch to the production environment. The production Developer Panel is located at: https://live.onlinecheckwriter.com/manage/developer/index and use base URL https://app.onlinecheckwriter.com/api/v3

Prerequisites: Developer Panel Setup

Before making any API requests, you need to complete two essential setup tasks in the Developer Panel.

Task 1: Get Your API Key

Navigate to the Developer Panel and locate your API Key:

  1. Go to Sandbox Developer Panel
  2. Click on the "API Settings" tab
  3. Your API Key will be displayed (hidden with dots for security)
  4. Click the eye icon to reveal it, or click the copy icon to copy it directly
  5. Save this key securely - you'll need it for every API request
Security Warning: Keep your API key secure and never share it publicly. If you generate a new API key, your current key will be automatically revoked.

Task 2: Set Your Connection Headers

Before making any request, you must add these 3 headers in your API tool (like Postman). Without these, our system cannot verify your account:

  • Content-Type: application/json
  • Accept: application/json
  • Authorization: Bearer YOUR_API_TOKEN_HERE (Use the API Key from Task 1)

Step 1: Get Available Shipping Options (Optional)

Before sending your document, you can retrieve the list of available shipping methods and their costs. This helps you choose the appropriate shipping type ID.

Note: We are using the mail checks shipping endpoint. This may be subject to change for document mailing.
ENDPOINT (GET)
AVAILABLE SHIPPING OPTIONS (RESPONSE DATA)
{ "success": true, "data": { "shippingTypes": [ { "shippingTypeId": 1, "name": "First Class", "amount": "1.25" }, { "shippingTypeId": 3, "name": "First Class with Tracking 7.50", "amount": "7.50" }, { "shippingTypeId": 14, "name": "First Class USPS", "amount": "1.99" }, { "shippingTypeId": 16, "name": "FedEx Overnight (Canada) 24.99", "amount": "24.99" }, { "shippingTypeId": 17, "name": "First Class With Tracking (international) 4.99", "amount": "4.99" }, { "shippingTypeId": 4, "name": "Priority Mail USPS 12.99", "amount": "12.99" }, { "shippingTypeId": 5, "name": "Express Mail USPS", "amount": "33.00" } ] } }

Action: Note down the shippingTypeId you want to use (e.g., 3 for First Class with Tracking).

Step 2: Send Document for Mailing

Now you can send your document with all details in a single request! This endpoint handles document upload, sender/recipient creation, and triggers physical mailing—all at once.

Important PDF Page Limits:
  • First Class Shipping (IDs: 1, 14, 17): Maximum 7 pages per PDF
  • All Other Shipping Methods: Maximum 40 pages per PDF

If your PDF exceeds these limits, you'll receive an error message. For larger documents, contact customer support for assistance.

How to structure your request:
  1. In your API tool, change the Body format to form-data
  2. Add all required fields as shown below
  3. For the file field, change type from Text to File and select your PDF
ENDPOINT (POST)
REQUEST BODY (FORM-DATA)
Field Name Type Example Value Required
DOCUMENT DETAILS
document_details[title] Text Invoice Document ✅
document_details[file] File [Select your PDF file] ✅
document_details[memo] Text Q1 Invoice - Payment Due ❌
FROM ADDRESS (SENDER)
from_address[name] Text Peter Parker ✅
from_address[company] Text Peter Co. ❌
from_address[address1] Text 123 Wall St ✅
from_address[address2] Text Suite 150 ❌
from_address[city] Text Queens ✅
from_address[state] Text NY ✅
from_address[zip] Text 12345 ✅
from_address[phone] Text 123456789 ❌
from_address[email] Text peter@gmail.com ✅
DESTINATION (RECIPIENT)
destination[name] Text Harry Potter ✅
destination[company] Text (Leave empty if none) ❌
destination[address1] Text 789 Irving St ✅
destination[address2] Text (Leave empty if none) ❌
destination[city] Text Irving ✅
destination[state] Text TX ✅
destination[zip] Text 78903 ✅
destination[phone] Text (Leave empty if none) ❌
destination[email] Text harry@gmail.com ✅
SHIPPING
shipping[shippingTypeId] Text 3 ✅
RESPONSE EXAMPLE
{ "success": true, "data": { "ids": "EJy7VeBwQjzn1m3" } }
Critical Address Requirements:
  • Ensure both sender (from_address) and recipient (destination) addresses are complete and accurate
  • The document will be physically mailed to the destination address
  • Incorrect or incomplete addresses may result in delivery failures or lost mail
  • State field must be 2 letters only (e.g., "TX" not "Texas", "NY" not "New York")

Action: After successful submission, save the ids value returned in the response. This is your document mailing ID for tracking.

Step 3: Track Your Mailed Document (Optional)

Monitor the status of your mailed document using the tracking endpoint. You can check printing, envelope status, and delivery progress.

ENDPOINT (GET)
RESPONSE EXAMPLE
{ "success": true, "data": { "id": "EJy7VeBwQjzn1m3", "document_title": "Invoice Document", "document_url": "https://ocw-local-s3.s3.amazonaws.com/...", "status": 4, "count_page": 2, "tracking": { "tracking_code": "9400116901496737856821", "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?...", "postage_label_url": "https://...", "mail_type": 3, "mail_type_name": "First Class with Tracking", "status": 4, "status_name": "Mail Sent", "payee_name": "Harry Potter", "payee_address_line_1": "789 Irving St", "payee_city": "Irving", "payee_state": "TX", "payee_zip": "78903", "shipping_cost": "7.50", "total_fee": "9.50" } } }

Step 4: Enable Webhook for Real-Time Updates (Optional)

To receive automatic notifications about your document's mailing status changes, enable the document.mailing.tracking webhook in your Developer Panel.

How to Enable Webhooks:
  1. Go to your account dashboard and navigate to Developer Panel → Webhooks
  2. Enter your webhook URL (where you want to receive notifications)
  3. Check the box for document.mailing.tracking
  4. Click Update to save your settings

Developer Panel URL: https://sandbox.onlinecheckwriter.com/manage/developer/index

Document Mailing Status Codes

Here are the status codes you'll see when tracking your document:

Status Code Status Name Description
0 New Document mail request created
1 Pending Processing and preparing for printing
2 Printed Document has been printed
3 Envelope Printed Envelope has been printed and prepared
4 Mail Sent Document has been mailed and is in transit
8 Refunded Mailing cancelled and refunded
Done! Your document has been submitted for physical mailing. Our facility will process the document, print it, envelope it, and mail it to the destination address. You can track progress using the tracking endpoint or webhook notifications.