📮Postal Dispatch

Learn how to send physical mail through Docs-Dispatcher with MySendingBox and other postal providers.

Overview

This recipe covers:

1. Sending physical letters via postal mail

2. Address formatting and validation

3. Letter specifications (color, duplex, etc.)

4. Tracking and delivery status

5. International mail

6. Complete examples in 4 languages

What You'll Learn

• Structure postal dispatch requests

• Format addresses correctly

• Configure letter options

• Track delivery status

• Handle postal webhooks

• Complete working examples

Prerequisites

• Docs-Dispatcher account with JWT

• Postal provider configured (MySendingBox)

• Template created

• Basic REST API knowledge

Postal Service Overview

Supported providers:

Provider	Regions	Tracking	Color	Duplex
MySendingBox	USA, International	✅	✅	✅
Lob	USA only	✅	✅	✅

Typical use cases:

• Customer invoices and statements

• Legal notices and documents

• Marketing campaigns

• Government correspondence

• Contract delivery

Step 1: Authentication

Dispatcher API uses HTTP Basic Authentication. You'll need your Dispatcher account email and password for all API calls.

Setup Credentials

# Store credentials as environment variables
export EMAIL="[email protected]"
export PASSWORD="your-password"

No token management needed! Unlike JWT-based APIs, Basic Auth doesn't require separate authentication endpoints or token refresh. Your credentials are sent with each request.

Quick links:

• Full authentication guide

• Using Basic Auth with Dispatcher

Step 2: Prepare Postal Request

Basic Postal Structure

{
  "providerName": "mysendingbox",
  "template": {
    "id": 127,
    "data": {
      "invoiceNumber": "INV-2026-001",
      "customerName": "John Smith",
      "amount": 2400.00,
      "dueDate": "2026-03-13"
    }
  },
  "postal": {
    "to": {
      "name": "John Smith",
      "company": "Acme Corp",
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 456",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    },
    "from": {
      "name": "Your Company Inc.",
      "addressLine1": "789 Business Ave",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "options": {
      "color": true,
      "duplex": true,
      "returnEnvelope": false,
      "mailType": "usps_first_class"
    }
  },
  "metadata": {
    "invoiceId": "INV-2026-001",
    "customerId": "CUST-789"
  }
}

Required Fields

Field	Type	Description
providerName	string	Postal provider: mysendingbox, lob
template.id	number	Template ID for letter content
postal.to	object	Recipient address
postal.to.name	string	Recipient name
postal.to.addressLine1	string	Street address
postal.to.city	string	City
postal.to.postalCode	string	ZIP/Postal code
postal.to.country	string	Country code (ISO 3166-1 alpha-2)

Optional Fields

Field	Type	Description
postal.from	object	Return address
postal.options.color	boolean	Color printing (default: false)
postal.options.duplex	boolean	Double-sided (default: true)
postal.options.mailType	string	Mail class (first_class, standard, etc.)
postal.options.returnEnvelope	boolean	Include return envelope

Step 3: Send Postal Mail

Domestic US Letter

curl -X POST https://api.docs-dispatcher.io/api/postal \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "mysendingbox",
    "template": {
      "id": 127,
      "data": {
        "invoiceNumber": "INV-2026-001",
        "customerName": "John Smith",
        "amount": 2400.00
      }
    },
    "postal": {
      "to": {
        "name": "John Smith",
        "company": "Acme Corp",
        "addressLine1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102",
        "country": "US"
      },
      "from": {
        "name": "Your Company Inc.",
        "addressLine1": "789 Business Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "options": {
        "color": false,
        "duplex": true,
        "mailType": "usps_first_class"
      }
    }
  }'

Success Response:

{
  "success": true,
  "dispatchId": "disp_postal_abc123",
  "providerResponse": {
    "letterId": "ltr_xyz789abc",
    "status": "pending",
    "recipientAddress": {
      "name": "John Smith",
      "company": "Acme Corp",
      "addressLine1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US",
      "verified": true
    },
    "mailType": "usps_first_class",
    "expectedDelivery": "2026-02-18",
    "trackingNumber": "9400111899562645123456",
    "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899562645123456",
    "createdAt": "2026-02-13T12:30:00Z",
    "cost": {
      "amount": 1.24,
      "currency": "USD"
    }
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/postal/INV-2026-001.pdf",
    "size": 189456,
    "pages": 2
  },
  "executionTime": 3.5
}

International Letter

{
  "providerName": "mysendingbox",
  "template": {
    "id": 127,
    "data": {
      "invoiceNumber": "INV-2026-002",
      "customerName": "Marie Dubois"
    }
  },
  "postal": {
    "to": {
      "name": "Marie Dubois",
      "company": "Acme France SARL",
      "addressLine1": "15 Rue de la Paix",
      "city": "Paris",
      "postalCode": "75002",
      "country": "FR"
    },
    "from": {
      "name": "Your Company Inc.",
      "addressLine1": "789 Business Ave",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "options": {
      "color": false,
      "duplex": true,
      "mailType": "usps_first_class_international"
    }
  }
}

Step 4: Track Delivery Status

Tracking Events

Postal providers send webhook notifications for:

• letter_created - Letter queued for printing

• letter_in_transit - Letter shipped to recipient

• letter_delivered - Letter delivered successfully

• letter_returned - Letter returned to sender

• letter_failed - Delivery failed

Webhook Payload Example

{
  "event": "letter_delivered",
  "letterId": "ltr_xyz789abc",
  "dispatchId": "disp_postal_abc123",
  "status": "delivered",
  "timestamp": "2026-02-18T14:30:00Z",
  "tracking": {
    "trackingNumber": "9400111899562645123456",
    "deliveredAt": "2026-02-18T14:30:00Z",
    "deliveryConfirmation": true,
    "signedBy": "J. Smith"
  },
  "metadata": {
    "invoiceId": "INV-2026-001",
    "customerId": "CUST-789"
  }
}

Webhook Handler (Node.js)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/postal', async (req, res) => {
  const webhook = req.body;
  const { event, letterId, status } = webhook;

  console.log('Postal webhook:', event, letterId);

  // Return 200 OK
  res.status(200).json({ received: true });

  // Process async
  try {
    switch (event) {
      case 'letter_delivered':
        await handleLetterDelivered(webhook);
        break;

      case 'letter_in_transit':
        await handleLetterInTransit(webhook);
        break;

      case 'letter_returned':
        await handleLetterReturned(webhook);
        break;

      case 'letter_failed':
        await handleLetterFailed(webhook);
        break;
    }
  } catch (error) {
    console.error('Webhook processing error:', error);
  }
});

async function handleLetterDelivered(webhook) {
  const { letterId, tracking, metadata } = webhook;

  console.log('✓ Letter delivered:', letterId);
  console.log('Delivered at:', tracking.deliveredAt);
  console.log('Signed by:', tracking.signedBy);

  // Update invoice status
  await database.updateInvoice(metadata.invoiceId, {
    deliveryStatus: 'delivered',
    deliveredAt: tracking.deliveredAt,
    deliveryConfirmation: tracking.signedBy
  });

  // Notify accounting team
  await notificationService.send({
    type: 'invoice_delivered',
    invoiceId: metadata.invoiceId,
    deliveryDate: tracking.deliveredAt
  });
}

async function handleLetterReturned(webhook) {
  const { letterId, reason, metadata } = webhook;

  console.warn('Letter returned:', letterId, reason);

  // Update status
  await database.updateInvoice(metadata.invoiceId, {
    deliveryStatus: 'returned',
    returnReason: reason
  });

  // Alert for address correction
  await alertService.notify({
    level: 'warning',
    message: `Letter ${letterId} returned: ${reason}`,
    action: 'Verify customer address'
  });
}

app.listen(3000);

Complete Examples

curl (Complete Flow)

#!/bin/bash

# Authenticate
AUTH_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }')

JWT_TOKEN=$(echo $AUTH_RESPONSE | jq -r '.token')

# Send postal letter
POSTAL_REQUEST='{
  "providerName": "mysendingbox",
  "template": {
    "id": 127,
    "data": {
      "invoiceNumber": "INV-2026-001",
      "customerName": "John Smith",
      "amount": 2400.00
    }
  },
  "postal": {
    "to": {
      "name": "John Smith",
      "addressLine1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    },
    "options": {
      "color": false,
      "duplex": true,
      "mailType": "usps_first_class"
    }
  }
}'

# Validate
VALIDATION=$(curl -s -X POST https://api.docs-dispatcher.io/api/postal/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d "$POSTAL_REQUEST")

if [ "$(echo $VALIDATION | jq -r '.valid')" = "true" ]; then
  # Send postal
  RESULT=$(curl -s -X POST https://api.docs-dispatcher.io/api/postal \
    -u "$EMAIL:$PASSWORD" \
    -H "Content-Type: application/json" \
    -d "$POSTAL_REQUEST")

  if [ "$(echo $RESULT | jq -r '.success')" = "true" ]; then
    echo "Postal letter sent!"
    echo "Letter ID: $(echo $RESULT | jq -r '.providerResponse.letterId')"
    echo "Tracking: $(echo $RESULT | jq -r '.providerResponse.trackingNumber')"
    echo "Expected Delivery: $(echo $RESULT | jq -r '.providerResponse.expectedDelivery')"
    echo "Cost: \$$(echo $RESULT | jq -r '.providerResponse.cost.amount')"
  else
    echo "Failed:"
    echo $RESULT | jq
  fi
else
  echo "Validation failed:"
  echo $VALIDATION | jq '.errors'
fi

Node.js (Complete Flow)

const fetch = require('node-fetch');

async function sendPostalLetter() {
  // Authenticate
  const authResponse = await fetch('https://api.docs-dispatcher.io/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: '[email protected]',
      password: 'your-secure-password'
    })
  });

  const { token } = await authResponse.json();

  // Send postal
  const postalData = {
    providerName: 'mysendingbox',
    template: {
      id: 127,
      data: {
        invoiceNumber: 'INV-2026-001',
        customerName: 'John Smith',
        amount: 2400.00
      }
    },
    postal: {
      to: {
        name: 'John Smith',
        addressLine1: '123 Main Street',
        city: 'San Francisco',
        state: 'CA',
        postalCode: '94102',
        country: 'US'
      },
      options: {
        color: false,
        duplex: true,
        mailType: 'usps_first_class'
      }
    }
  };

  const response = await fetch('https://api.docs-dispatcher.io/api/postal', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(postalData)
  });

  const result = await response.json();

  if (result.success) {
    console.log('Postal letter sent!');
    console.log('Letter ID:', result.providerResponse.letterId);
    console.log('Tracking:', result.providerResponse.trackingNumber);
    console.log('Expected Delivery:', result.providerResponse.expectedDelivery);
    console.log('Cost:', result.providerResponse.cost.amount, result.providerResponse.cost.currency);
    return result;
  } else {
    console.error('Failed:', result.message);
    throw new Error(result.message);
  }
}

sendPostalLetter().catch(console.error);

PHP (Complete Flow)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// Authenticate
$authResponse = $client->post('https://api.docs-dispatcher.io/auth', [
    'json' => [
        'email' => '[email protected]',
        'password' => 'your-secure-password'
    ]
]);

$authData = json_decode($authResponse->getBody(), true);
$jwtToken = $authData['token'];

// Send postal
$postalData = [
    'providerName' => 'mysendingbox',
    'template' => [
        'id' => 127,
        'data' => [
            'invoiceNumber' => 'INV-2026-001',
            'customerName' => 'John Smith',
            'amount' => 2400.00
        ]
    ],
    'postal' => [
        'to' => [
            'name' => 'John Smith',
            'addressLine1' => '123 Main Street',
            'city' => 'San Francisco',
            'state' => 'CA',
            'postalCode' => '94102',
            'country' => 'US'
        ],
        'options' => [
            'color' => false,
            'duplex' => true,
            'mailType' => 'usps_first_class'
        ]
    ]
];

$response = $client->post('https://api.docs-dispatcher.io/api/postal', [
    'headers' => [
        'auth' => [$email, $password],
        'Content-Type' => 'application/json'
    ],
    'json' => $postalData
]);

$result = json_decode($response->getBody(), true);

if ($result['success']) {
    echo "Postal letter sent!\n";
    echo "Letter ID: {$result['providerResponse']['letterId']}\n";
    echo "Tracking: {$result['providerResponse']['trackingNumber']}\n";
    echo "Expected Delivery: {$result['providerResponse']['expectedDelivery']}\n";
} else {
    echo "Failed: {$result['message']}\n";
}

Java (Complete Flow)

import java.net.URI;
import java.net.http.*;
import com.google.gson.Gson;
import java.util.*;

public class PostalDispatcher {
    private final HttpClient client;
    private final Gson gson;

    public PostalDispatcher() {
        this.client = HttpClient.newHttpClient();
        this.gson = new Gson();
    }

    public String authenticate(String email, String password) throws Exception {
        Map<String, String> auth = new HashMap<>();
        auth.put("email", email);
        auth.put("password", password);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/auth"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(auth)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        Map data = gson.fromJson(response.body(), Map.class);
        return (String) data.get("token");
    }

    public Map sendPostal(String jwtToken, Map<String, Object> postalData) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/api/postal"))
            .header("Authorization", authHeader)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(postalData)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        return gson.fromJson(response.body(), Map.class);
    }

    public static void main(String[] args) throws Exception {
        PostalDispatcher dispatcher = new PostalDispatcher();
        String jwtToken = dispatcher.authenticate("[email protected]", "password");

        Map<String, Object> postalData = new HashMap<>();
        // Build postal data...

        Map result = dispatcher.sendPostal(jwtToken, postalData);
        System.out.println("Postal sent: " + result.get("success"));
    }
}

Mail Type Options

USPS (United States)

Type	Cost	Speed	Tracking
usps_first_class	$$	2-5 days	✅
usps_standard	$	2-8 days	⚠️ Limited
usps_certified	$$$	2-5 days	✅ Full

International

Type	Regions	Speed
usps_first_class_international	Worldwide	7-21 days
usps_priority_international	Worldwide	6-10 days

Best Practices

1. Validate Addresses

Always validate addresses before sending:

function validateAddress(address) {
  // Check required fields
  if (!address.addressLine1 || !address.city || !address.postalCode) {
    return false;
  }

  // Validate postal code format
  if (address.country === 'US') {
    return /^\d{5}(-\d{4})?$/.test(address.postalCode);
  }

  return true;
}

2. Use Duplex Printing

Save costs with double-sided printing:

{
  "options": {
    "duplex": true
  }
}

3. Include Return Address

{
  "from": {
    "name": "Your Company",
    "addressLine1": "789 Business Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  }
}

Error Handling

Common Errors

Invalid Address

{
  "error": "invalid_address",
  "message": "Address validation failed: Invalid postal code",
  "details": {
    "field": "postal.to.postalCode",
    "value": "invalid"
  }
}

Address Not Deliverable

{
  "error": "address_not_deliverable",
  "message": "Address is not deliverable according to USPS",
  "suggestion": "Verify address with recipient"
}

Cost Estimation

Typical costs (USD):

• Black & White, Single-sided: $0.75 - $1.25

• Black & White, Duplex: $0.60 - $1.00

• Color, Single-sided: $1.50 - $2.50

• Color, Duplex: $1.25 - $2.00

• International: $2.50 - $5.00

Next Steps

Related Recipes

• Invoice - Generate invoices to mail

• Async Flow - Track delivery via webhooks

Summary

You've learned:

• ✅ Send physical mail via postal providers

• ✅ Format addresses correctly

• ✅ Configure letter options

• ✅ Track delivery status

• ✅ Complete implementations in 4 languages

Postal dispatch bridges digital and physical document delivery!