Letter Template System - User Guide

The Letter Template System allows you to create customizable letter templates with dynamic content that can be populated via API calls. Templates support logos, multiple text blocks with formatting options, QR codes, and dynamic variables that are replaced at generation time.

• Visual Editor: Split-screen interface with live preview

• Dynamic Variables: Insert placeholders that are filled via API

• Logo Support: Upload and embed logos directly in templates

• Text Formatting: Control size, alignment, and weight for each text block

• QR Code Integration: Generate or embed QR codes in letters

• API Integration: Generate personalized letters via simple API calls

Template Name: A descriptive name for your template (e.g., "Payment Reminder Letter")

Template ID: Auto-generated slug based on the name, used for API references (e.g., "payment_reminder_letter")

• Upload: Click "Add new or select from Logo Library" to upload a PNG or JPEG logo

• Show/Hide: Toggle visibility with the checkbox

• Note: Logos are embedded directly in the template and stored as base64 data

Templates include three text blocks:

Headline Block (Text Block 1)

• Single-line text input

• Typically used for letter titles or main headings

• Formatting options: Size (Small/Medium/Large/X-Large), Alignment (Left/Center/Right), Bold

Body Block (Text Block 2)

• Multi-line textarea

• Main content area of the letter

• Supports line breaks and paragraph formatting

• Formatting options: Size, Alignment, Bold

Footer Block (Text Block 3)

• Multi-line textarea

• Closing remarks, signatures, or legal disclaimers

• Formatting options: Size, Alignment, Bold

Two Modes:

Generate Now Mode:

• Provide a static URL

• QR code is generated immediately and embedded in the template

• Choose size: Small (0.75"), Medium (1"), Large (1.5")

Variable Mode:

• QR code URL provided via API call

• Use {{qrcode}} variable in the URL field

• QR code generated at order creation time

Variables allow you to insert dynamic content that's populated when generating letters via API.

Variables use double curly braces: {{variable_name}}

Example:

Dear {{first_name}} {{last_name}},

Your payment of ${{amount}} is due on {{due_date}}.

Quick-insert buttons are available for common variables:

• {{first_name}} - Recipient's first name

• {{last_name}} - Recipient's last name

• {{company}} - Company name

• {{address}} - Street address

• {{city}} - City

• {{state}} - State/Province

• {{zip}} - Postal code

• {{venue}} - Custom venue/location

Click "Custom..." to add your own variables:

• {{account_number}}

• {{due_date}}

• {{amount_due}}

• {{tracking_id}}

• Any custom field name you need

Important: Variables are case-sensitive and should contain only letters, numbers, and underscores.

• Saves the current template

• Overwrites existing template data

• Returns to template list after saving

• Creates a copy of the current template

• Useful for creating variations

• Auto-appends " (Copy)" to the name

• Permanently removes the template

• Requires confirmation

• Cannot be undone

1. Open a saved template in edit mode

2. Click "Copy API Example" in the toolbar

3. A curl command will be copied to your clipboard

curl -v https://www.mailform.io/app/api/v1/orders \
  -F template=YOUR_TEMPLATE_GUID \
  -F 'customer_reference=ORDER_REF_001' \
  -F 'service=USPS_FIRST_CLASS' \
  -F 'to.name=Recipient Name' \
  -F 'to.organization=Recipient Company' \
  -F 'to.address1=123 Main Street' \
  -F 'to.address2=Suite 100' \
  -F 'to.city=Boston' \
  -F 'to.state=MA' \
  -F 'to.postcode=02101' \
  -F 'to.country=US' \
  -F 'from.name=Your Name' \
  -F 'from.organization=Your Company' \
  -F 'from.address1=456 Oak Avenue' \
  -F 'from.address2=Floor 2' \
  -F 'from.city=Cambridge' \
  -F 'from.state=MA' \
  -F 'from.postcode=02139' \
  -F 'from.country=US' \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  --form-string "variables={\"first_name\":\"John\"}"

• template: Your template GUID (automatically filled from template)

• customer_reference: Your order reference number

• service: Mailing service (e.g., USPS_FIRST_CLASS)

• to.*: Recipient address fields

• from.*: Return address fields

• Authorization: Your API bearer token

• variables: JSON object with variable values

Pass all your template variables as a JSON object:

--form-string "variables={
  \"first_name\":\"John\",
  \"last_name\":\"Doe\",
  \"account_number\":\"12345\",
  \"amount_due\":\"$125.00\",
  \"due_date\":\"January 31, 2024\"
}"

1. Keep it Simple: Use clear, concise language

2. Test Variables: Always test with sample data before production use

3. Consistent Formatting: Use consistent font sizes and alignment

4. Logo Size: Keep logos under 200x100px for best results

5. QR Codes: Test QR codes with different sizes to ensure scannability

1. Descriptive Names: Use clear variable names (e.g., {{payment_amount}} not {{amt}})

2. Consistent Case: Stick to lowercase with underscores

3. Document Variables: Keep a list of all variables used in each template

1. Trim Whitespace: The system automatically trims leading/trailing spaces

2. Line Breaks: Use natural line breaks in multi-line blocks

3. Special Characters: Avoid special characters in variable names

4. Length Limits: Template names max 128 characters, descriptions max 256 characters

• Check that Template Name and ID are filled

• Ensure you're logged in

• Verify you have permission to create templates

• Confirm variable syntax: {{variable_name}}

• Check spelling matches exactly between template and API call

• Ensure variables are passed in the correct JSON format

• Verify logo is PNG or JPEG format

• Check file size (recommended under 500KB)

• Ensure "Show logo" checkbox is enabled

• Now Mode: Verify URL is valid and accessible

• Variable Mode: Ensure {{qrcode}} variable is passed in API call

• Test QR code size for scannability (Medium or Large recommended)

Successful orders return:

{
  "status": "success",
  "order_id": "ord_xxx",
  "tracking_id": "trk_xxx"
}

For additional help:

• Check template preview before saving

• Use "Copy API Example" for correct API format

• Contact support with template GUID for troubleshooting