How to Mail HTML Document Templates via OCW API

How to Mail HTML Document Templates via OCW API

Guide: How to Mail Documents via HTML Templates

Welcome! This comprehensive guide will walk you through the complete workflow of mailing HTML documents physically to any destination address. You'll learn how to configure your Developer Panel, upload HTML templates with dynamic variables, select shipping options, and mail personalized documents from start to finish.

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 Your Payee ID

You need a unique code for the recipient (payee) who will receive the mailed document. This identifies the destination address.

ENDPOINT (GET)
RESPONSE EXAMPLE
{ "success": true, "data": { "payees": [{ "payeeId": "bz3Aj3ZyJ9eVw6E", "name": "Jane Doe", "address": "123 Main Street", "city": "New York", "state": "NY", "zipCode": "10001" }] } }

Action: Copy the payeeId value for Step 5.

Step 2: Get Your Reply-to Address ID (Sender Information)

This is your return address - where the document appears to be coming from. If the mailing cannot be delivered, it will be returned to this address.

ENDPOINT (GET)
RESPONSE EXAMPLE
{ "success": true, "data": { "meta": { "total": 3, "currentPage": 1, "perPage": 10 }, "relyToAddress": [ { "id": "knv1byeV2eOQgrB", "name": "Zilmoney", "company": "", "email": "support@onlinecheckwriter.com", "phone": "", "address1": "1234 richmond ln", "address2": "", "city": "Tyler", "state": "TX", "zip": "75701", "country": "US" }, { "id": "OYxZqXGKdeRzVvJ", "name": "Test Sender", "company": "", "email": "test@example.com", "phone": "1234567890", "address1": "123 Test Street", "address2": "", "city": "New York", "state": "NY", "zip": "10001", "country": "" } ] } }

Action: Copy the id value from your desired sender address for Step 5.

Step 3: Get Shipping Options

Use this request to see every available mailing option. You must pick one shipping type ID for the final step.

ENDPOINT (GET)
FULL LIST OF 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": 18, "name": "FedEx Overnight (International) 60", "amount": "60.00" }, { "shippingTypeId": 20, "name": "Fedex Saturday 59.99", "amount": "59.99" }, { "shippingTypeId": 4, "name": "Priority Mail USPS 12.99", "amount": "12.99" }, { "shippingTypeId": 12, "name": "Fedex Overnight 03.30 PM Standard", "amount": "31.99" }, { "shippingTypeId": 5, "name": "Express Mail USPS", "amount": "33.00" } ] } }

Action: Choose and copy the shippingTypeId for your preferred shipping method for Step 5.

Step 4: Upload Your HTML Template

Upload your HTML template file with dynamic variables (like {{name}} or {{company_name}}) that will be replaced with actual values when mailing.

Important Limitations:
  • Maximum 30 templates per account
  • Maximum file size: 10 MB
  • Accepted file types: HTML, TXT, or PDF
How to upload your HTML file:
  1. In your API tool, change the Body format to form-data.
  2. Add three fields with these exact KEY names:
    • file - Change type to File, then select your HTML file
    • idempotency_key - Enter a unique random string (prevents duplicate uploads)
    • document_title - Enter a descriptive name for your template
ENDPOINT (POST)
REQUEST BODY (form-data)
Key: file Type: File Value: [Select your HTML file - e.g., Dashboard.html] Key: idempotency_key Type: Text Value: 83d8a876-2b39-42d1-a1ac-9d8646e2a8e7 Key: document_title Type: Text Value: Dashboard 1
RESPONSE EXAMPLE
{ "success": true, "data": { "id": "VRdJM5Gb3eY329A", "document_title": "Dashboard 1", "document_name": "document_mailing_templates/127205/1769124609-mailtest.html" } }

Action: Copy the id value. This is your template_id needed for the final step.

Understanding Dynamic Variables:

Your HTML template can include variables in double curly braces (e.g., {{name}}, {{company_name}}). These will be replaced with actual values when you mail the document in Step 5.

Example: If your HTML contains "Dear {{name}}", and you provide {"name": "John Doe"} when mailing, it will print as "Dear John Doe".

Step 5: Mail the Document with Dynamic Content

The final step! This tells our facility to process your HTML template, replace the dynamic variables with actual values, and physically mail the document to your payee.

How to set up the request:
  1. In your API tool, change the Body format to form-data.
  2. Add five fields with these exact KEY names:
    • template_id - The ID from Step 4
    • reply_id - The sender ID from Step 2
    • payee_id - The recipient ID from Step 1
    • shipping_type - The shipping type ID from Step 3
    • json_content - JSON object with values for your template variables
Critical: JSON Content Format

The json_content field must be valid JSON. Common mistake: Missing colons between keys and values.

Wrong: {"name""John"} ❌

Correct: {"name":"John"} ✓

ENDPOINT (POST)
REQUEST BODY (form-data)
Key: template_id Type: Text Value: y0bL3YGdLG1X7wA Key: reply_id Type: Text Value: qx5NrWjymj2n3l6 Key: payee_id Type: Text Value: bz3Aj3ZyJ9eVw6E Key: shipping_type Type: Text Value: 1 Key: json_content Type: Text Value: {"name":"ZilMoney","Company_name":"ZilMoneyLLC"}
RESPONSE EXAMPLE
{ "success": true, "message": "Successfully Completed" }
Done! Our facility has received your order and will begin processing the physical delivery. The HTML template variables will be replaced with your JSON values before printing and mailing.

Understanding Variable Replacement

When you mail the document, the system automatically replaces template variables with the values you provide in json_content.

Example:

Your HTML Template contains:

Dear {{name}},

Thank you for your business with {{Company_name}}.

You provide this json_content:

{"name":"ZilMoney","Company_name":"ZilMoneyLLC"}

The printed document will show:

Dear ZilMoney,

Thank you for your business with ZilMoneyLLC.