Letter Template System - Automated Document Generation & Mail API

Overview

The Letter Template System is a powerful visual editor and API-driven solution for creating, managing, and sending personalized physical mail at scale. Design professional letter templates with your branding, embed dynamic variables, and generate thousands of customized letters through a simple REST API integration.

Key Features

Visual Template Editor

Create professional letter templates with an intuitive split-screen interface. Real-time preview shows exactly how your letters will look when printed and mailed. No coding required for template design.

Dynamic Variable System

Insert variables anywhere in your templates using simple {{variable_name}} syntax. Personalize each letter with recipient-specific data including names, addresses, amounts, dates, and custom fields. Variables are automatically populated when you submit orders through the API.

Logo & Branding Integration

Upload and embed your company logo directly into templates. Logos are stored as base64-encoded images within the template, ensuring consistent branding across all mailings. Build a reusable logo library for multi-brand organizations.

QR Code Generation

Embed QR codes in your letters for enhanced customer engagement. Two modes supported:

• Immediate Generation: Generate QR codes during template creation for static URLs
• Variable QR Codes: Pass unique QR code data per recipient via API for personalized tracking links

RESTful API Integration

Send letters programmatically through a simple multipart form data API. Submit recipient addresses, sender information, template GUID, and variable data in a single API call. Supports all major USPS mail classes including First Class, Certified, and Priority Mail.

Template Management

• Save and reuse templates across multiple campaigns
• Edit existing templates while preserving version history
• Duplicate templates to create variations quickly
• Delete outdated templates with confirmation safeguards
• Export API integration examples with working curl commands

Use Cases

Debt Collection & Legal Notices

Send personalized payment reminders, collection notices, and legal correspondence with proper formatting and tracking. Embed account balances, payment due dates, and case numbers as variables.

Healthcare & Medical Billing

Automate patient statements, appointment reminders, and explanation of benefits letters. Include personalized amounts due, service dates, and provider information.

Financial Services

Generate account statements, loan notifications, tax documents, and compliance mailings. Maintain regulatory compliance with consistent formatting and audit trails.

Government & Municipal Services

Send tax notices, permit approvals, violation notices, and public notifications. Scale from single letters to mass mailings with the same template.

E-Commerce & Retail

Create personalized thank you letters, promotional offers, and customer appreciation mailings. Drive online engagement with QR codes linking to exclusive offers.

Non-Profit & Fundraising

Send donation acknowledgments, event invitations, and impact reports with personalized donor information and contribution amounts.

Technical Capabilities

Supported Mail Services

• USPS First Class Mail
• USPS Certified Mail with Return Receipt
• USPS Priority Mail
• International Mail Services

Template Specifications

• Standard 8.5" x 11" letter format
• Full-color printing support
• PNG and JPEG logo formats
• Base64 image embedding
• HTML-based rendering engine
• Variable text formatting (size, alignment, bold)

API Features

• RESTful multipart form data submission
• Bearer token authentication
• JSON variable payloads
• Batch processing support
• Real-time order tracking
• Webhook notifications for delivery events

Data Security

• Secure template storage
• Encrypted API communications
• Role-based access controls
• Company-level data isolation
• Audit logging for compliance

Integration Workflow

1. Design Template: Use the visual editor to create your letter layout with logos, text blocks, and QR codes
2. Add Variables: Insert dynamic placeholders like {{first_name}}, {{balance_due}}, {{due_date}}
3. Save Template: Template is stored with a unique GUID for API reference
4. API Integration: Copy the auto-generated curl command and integrate into your application
5. Submit Orders: Send API requests with recipient data and variable values
6. Automated Fulfillment: Letters are printed, inserted into envelopes, and mailed via USPS

Benefits

Time Savings

Eliminate manual letter creation and mailing processes. What once took hours now takes seconds. Scale from 1 letter to 10,000 letters with the same effort.

Cost Efficiency

No need for in-house printing equipment, envelope stuffing, or postage management. Pay only for letters you send with transparent per-piece pricing.

Personalization at Scale

Send uniquely customized letters to every recipient while maintaining brand consistency. Increase engagement rates with personalized content.

Developer-Friendly API

Simple REST API integration works with any programming language. Comprehensive documentation, working examples, and curl commands included.

Brand Consistency

Centralized template management ensures every letter matches your brand guidelines. No more inconsistent formatting or outdated logos.

Compliance & Tracking

Built-in audit trails for regulatory compliance. Track every letter from creation to delivery with detailed status updates.

SEO Keywords

Letter template system, automated mail API, personalized letter printing, REST API mail service, USPS API integration, bulk mail automation, template-based document generation, variable data printing, QR code mail integration, programmatic mail sending, direct mail API, letter personalization software, automated document fulfillment, mail merge API, physical mail automation

Getting Started

Create your first template in minutes. The visual editor guides you through every step with helpful hints and real-time preview. Once your template is saved, copy the API integration example and start sending personalized letters immediately.

No special software required. No printing equipment needed. No postage management headaches. Just design, integrate, and send.

Customer Release Notes: Template Features

Overview

We've added powerful template capabilities to the Mailform API, allowing you to create reusable letter templates with dynamic variables. This enables mail merge functionality for personalized letters at scale.

What's New

1. Template Management

• Create and manage HTML letter templates via the web interface or API
• Use Mustache syntax ({{variable_name}}) for dynamic content
• Templates are associated with your account or company for team access

2. Bulk Import with Templates

• Upload CSV/Excel files with recipient data and variable values
• System automatically merges data with templates to generate PDFs
• Standard columns: name, company_name, address, city, state, zip, files, address2, country, ref1, ref2, address3
• Add custom columns matching your template variables

3. API Template Orders Create orders using templates via the /api/v1/orders endpoint:

curl -X POST https://api.mailform.io/app/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "template=YOUR_TEMPLATE_GUID" \
  -F "service=USPS_FIRST_CLASS" \
  -F "to.name=John Smith" \
  -F "to.address1=123 Main St" \
  -F "to.city=Boston" \
  -F "to.state=MA" \
  -F "to.postcode=02101" \
  -F "to.country=US" \
  --form-string 'variables={"first_name":"John","case_number":"2024-CV-1234"}'

4. PDF Preview Endpoint (NEW) Preview your rendered template without creating an order:

curl -X POST https://api.mailform.io/app/v1/documenttemplates/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "template=YOUR_TEMPLATE_GUID" \
  --form-string 'variables={"first_name":"John","venue":"Boston Court"}' \
  -o preview.pdf

Returns the rendered PDF binary. Use this to validate your templates and variables before submitting orders.

API Error Reference

Missing Variables Response Example:

{
  "error": "missing_variables",
  "detail": {
    "missing_variables": ["case_number", "hearing_date"],
    "required_variables": ["first_name", "case_number", "hearing_date", "venue"],
    "unused_variables": ["extra_field"]
  }
}

A/B Testing with Templates

Run A/B tests on your mail campaigns using templates:

1. Create Variants - Create multiple template versions (e.g., notice_version_a, notice_version_b)

2. Randomize Selection - Use your own logic to select which template GUID to use:

   const templates = {
     a: 'guid-for-version-a',
     b: 'guid-for-version-b'
   };
   const variant = Math.random() < 0.5 ? 'a' : 'b';
   const templateGuid = templates[variant];
   

3. Track Variants - Use the customer_reference field to identify which variant was sent:

   -F "customer_reference=campaign_2024_variant_a"
   

4. Analyze Results - Compare delivery and response metrics by customer_reference to measure effectiveness

Template Variables

Templates use Mustache syntax for variables:

<p>Dear {{first_name}},</p>
<p>Your case number {{case_number}} is scheduled for 
   {{hearing_date}} at {{venue}}.</p>

Variable Rules:

• Variable names: letters, numbers, underscores (e.g., first_name, case_number_2024)
• All variables in the template must be provided in the variables object
• Extra variables in your request are ignored (with warning in preview endpoint)
• Variables are case-sensitive

CSV Template Download

From the Templates page, click the download icon on any template to get a pre-formatted CSV with:

• All standard address columns
• Custom columns for template-specific variables
• Template ID pre-filled

This makes it easy to prepare bulk import files that match your template's requirements.

Best Practices

1. Test First - Use the /render endpoint to preview before creating orders
2. Validate Variables - The API will return which variables are missing
3. Use customer_reference - Track campaigns, variants, or internal IDs
4. Download CSV Templates - Get pre-formatted files from the Templates page

Ready to automate your physical mail? Start creating templates today and transform how your organization communicates through postal mail.