Send your first physical letter from code in under 5 minutes.

The developer epiphany: Bridging software bits and physical letterboxes

Prerequisites: What you need before making your first API call

The 3-step programmatic postal workflow

Step 1: Your first letter via cURL (The 60-second test)

Terminal (cURL Quickstart) — bash
curl -X POST https://api.letterapi.uk/v1/letters \
  -H "Authorization: Bearer test_key_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Jane Doe",
      "address_line_1": "10 Downing Street",
      "city": "London",
      "postcode": "SW1A 2AA",
      "country": "GB"
    },
    "content": {
      "type": "html",
      "html": "<h1>Hello from code!</h1><p>This physical letter was dispatched using LetterAPI in under 5 minutes.</p>"
    },
    "postage": "first_class"
  }'

Response (HTTP 201 Created) — json
{
  "id": "let_8f92a1c4b7e3",
  "status": "created",
  "mode": "test",
  "postage": "first_class",
  "recipient": {
    "name": "Jane Doe",
    "address_line_1": "10 Downing Street",
    "city": "London",
    "postcode": "SW1A 2AA",
    "paf_verified": true,
    "delivery_point_suffix": "1A"
  },
  "cost": {
    "amount": 0.86,
    "currency": "GBP"
  },
  "preview_url": "https://api.letterapi.uk/v1/letters/let_8f92a1c4b7e3/preview.pdf",
  "created_at": "2026-10-14T10:15:30.000Z"
}

Step 2: Idiomatic implementation in TypeScript / Node.js

src/quickstart.ts — typescript
import fetch from 'node-fetch';
​
interface DispatchResponse {
  id: string;
  status: string;
  preview_url: string;
  cost: { amount: number; currency: string };
}
​
async function sendLetter(): Promise<void> {
  const apiKey = process.env.LETTERAPI_KEY || 'test_key_abc123xyz789';
​
  const payload = {
    recipient: {
      name: 'Dr. Alexander Wright',
      address_line_1: '42 Baker Street',
      city: 'London',
      postcode: 'NW1 6XE',
      country: 'GB'
    },
    content: {
      type: 'html',
      html: `
        <div style="font-family: Arial, sans-serif; font-size: 11pt; color: #111;">
          <h2 style="color: #0284c7; border-bottom: 2px solid #0284c7; padding-bottom: 8px;">
            Account Security Notice
          </h2>
          <p>Dear Alexander,</p>
          <p>Your password was successfully updated on <strong>14 October 2026 at 09:30 AM</strong>.</p>
          <p>If you did not authorize this change, please contact our 24/7 security hotline immediately at <strong>0800 123 4567</strong>.</p>
          <div style="margin-top: 30px; padding: 12px; background: #f0fdf4; border-left: 4px solid #16a34a;">
            <strong>Verification Reference:</strong> SEC-99482-GB
          </div>
        </div>
      `
    },
    postage: 'first_class',
    options: {
      double_sided: false,
      color: true
    },
    metadata: {
      user_id: 'usr_882910',
      event_type: 'SECURITY_CREDENTIAL_CHANGE'
    }
  };
​
  const res = await fetch('https://api.letterapi.uk/v1/letters', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
​
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`LetterAPI Error [${res.status}]: ${err.message}`);
  }
​
  const result = (await res.json()) as DispatchResponse;
  console.log(`✓ Letter successfully dispatched! ID: ${result.id}`);
  console.log(`✓ PDF Vector Proof: ${result.preview_url}`);
}
​
sendLetter().catch(console.error);

Step 3: Idiomatic implementation in Python

quickstart.py — python
import os
import requests
​
def send_letter():
    api_key = os.getenv("LETTERAPI_KEY", "test_key_abc123xyz789")
    url = "https://api.letterapi.uk/v1/letters"
​
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
​
    payload = {
        "recipient": {
            "name": "Sarah Jenkins",
            "address_line_1": "14 Cathedral Close",
            "city": "Salisbury",
            "postcode": "SP1 2EF",
            "country": "GB"
        },
        "content": {
            "type": "html",
            "html": """
            <div style="font-family: Georgia, serif; line-height: 1.6;">
                <h2>Notice of Annual Dividend Payment</h2>
                <p>Dear Sarah,</p>
                <p>We are pleased to confirm that your quarterly dividend of <strong>£142.50</strong> has been credited to your nominated bank account.</p>
                <p>Attached to this statement is your tax voucher for your annual HMRC self-assessment records.</p>
            </div>
            """
        },
        "postage": "first_class",
        "options": {
            "color": True
        }
    }
​
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
​
    data = response.json()
    print(f"✓ Letter created successfully! ID: {data['id']}")
    print(f"✓ Vector PDF Proof: {data['preview_url']}")
​
if __name__ == "__main__":
    send_letter()

Mastering DL window envelope geometry: Preventing address clipping and layout bleed

Real-time webhooks: Subscribing to Royal Mail Mailmark delivery telemetry

Simulating postal lifecycles in the developer sandbox

Flipping the switch: Transitioning from sandbox to live production dispatch

Advanced document layout techniques: CSS paged media, page breaks, and dynamic headers

Handling multi-page PDFs and dynamic enclosures: Merging attachments and terms

Security best practices: API key scoping, IP allowlisting, and webhook signature verification

Frontend integration: Powering address autocomplete and PAF cleansing in web forms

Global reach: International postal dispatch across 190+ countries via Royal Mail International Priority

Modern serverless architecture: Edge functions, Next.js Server Actions, and idempotent background workers

The developer transformation: Unlocking the physical world from your terminal

Ready to send your first physical letter?