Integrating LetterAPI with Node.js and TypeScript: Clean, typed postal automation.

Defining the TypeScript domain models: Zero-guesswork types

The 3-step plan: Type-safe postal dispatch in Node.js

Technical blueprint: Complete TypeScript postal client with Zod validation

src/services/letter-client.ts — typescript
import axios, { AxiosInstance } from 'axios';
import { z } from 'zod';
​
// 1. Define Zod Schemas for Runtime Validation
export const RecipientSchema = z.object({
  name: z.string().min(2, 'Recipient name is required'),
  company: z.string().optional(),
  address_line1: z.string().min(3, 'Thoroughfare address is required'),
  address_line2: z.string().optional(),
  city: z.string().min(2, 'City is required'),
  postcode: z.string().regex(/^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i, 'Invalid UK postcode format'),
  country: z.literal('GB').default('GB')
});
​
export const CreateLetterInputSchema = z.object({
  recipient: RecipientSchema,
  template_html: z.string().min(20, 'HTML content is too short'),
  postage_class: z.enum(['first_class', 'second_class']).default('second_class'),
  color: z.boolean().default(false),
  double_sided: z.boolean().default(false),
  metadata: z.record(z.any()).optional()
});
​
export type Recipient = z.infer<typeof RecipientSchema>;
export type CreateLetterInput = z.infer<typeof CreateLetterInputSchema>;
​
export interface LetterApiResponse {
  id: string;
  status: 'created' | 'validating' | 'queued_for_print' | 'printed' | 'dispatched' | 'delivered';
  recipient: {
    formatted_address: string[];
    paf_verified: boolean;
  };
  postage_class: 'first_class' | 'second_class';
  pages: number;
  cost: {
    currency: 'GBP';
    print: number;
    postage: number;
    total: number;
  };
  estimated_delivery: string;
  created_at: string;
}
​
export class LetterApiClient {
  private http: AxiosInstance;
​
  constructor(apiKey: string = process.env.LETTERAPI_API_KEY || '') {
    if (!apiKey) {
      throw new Error('LETTERAPI_API_KEY environment variable is required');
    }
    this.http = axios.create({
      baseURL: 'https://api.letterapi.uk/v1',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      timeout: 15000
    });
  }
​
  async sendLetter(input: CreateLetterInput, idempotencyKey?: string): Promise<LetterApiResponse> {
    // Validate input at runtime using Zod
    const validatedInput = CreateLetterInputSchema.parse(input);
​
    const headers: Record<string, string> = {};
    if (idempotencyKey) {
      headers['Idempotency-Key'] = idempotencyKey;
    }
​
    const response = await this.http.post<LetterApiResponse>('/letters', validatedInput, { headers });
    return response.data;
  }
​
  async getLetterStatus(letterId: string): Promise<LetterApiResponse> {
    const response = await this.http.get<LetterApiResponse>(`/letters/${letterId}`);
    return response.data;
  }
}

Verifying webhook signatures in Express and Next.js API routes

Technical blueprint: Type-safe Express webhook listener

src/webhooks/letterapi-webhook.ts — typescript
import express, { Request, Response } from 'express';
import crypto from 'crypto';
​
const app = express();
const WEBHOOK_SECRET = process.env.LETTERAPI_WEBHOOK_SECRET || 'whsec_sample_secret_key_84920';
​
interface LetterWebhookPayload {
  event: 'letter.printed' | 'letter.dispatched' | 'letter.delivered' | 'letter.failed';
  letter_id: string;
  timestamp: string;
  metadata?: Record<string, any>;
  delivery_details?: {
    carrier: string;
    mailmark_barcode: string;
    delivery_office: string;
  };
  error?: {
    code: string;
    message: string;
  };
}
​
app.post('/api/webhooks/letterapi', express.raw({ type: 'application/json' }), (req: Request, res: Response) => {
  const signatureHeader = req.headers['x-letterapi-signature'] as string;
​
  if (!signatureHeader) {
    return res.status(401).json({ error: 'Missing signature header' });
  }
​
  // Verify HMAC SHA-256 Signature
  const rawBody = req.body as Buffer;
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
​
  const signatureBuffer = Buffer.from(signatureHeader, 'hex');
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
​
  if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
    console.error('[Security Alert] Invalid LetterAPI webhook signature!');
    return res.status(401).json({ error: 'Invalid webhook signature' });
  }
​
  const payload: LetterWebhookPayload = JSON.parse(rawBody.toString('utf8'));
  console.log(`[LetterAPI Webhook] Event: ${payload.event} for Letter: ${payload.letter_id}`);
​
  switch (payload.event) {
    case 'letter.delivered':
      console.log(`✓ Letter ${payload.letter_id} delivered by ${payload.delivery_details?.carrier}`);
      // Update database, notify customer success, trigger CRM task
      break;
    case 'letter.dispatched':
      console.log(`-> Letter ${payload.letter_id} handed to Royal Mail`);
      break;
    case 'letter.failed':
      console.error(`✗ Letter ${payload.letter_id} failed: ${payload.error?.message}`);
      break;
  }
​
  res.status(200).json({ received: true });
});
​
app.listen(4000, () => console.log('LetterAPI webhook listener active on port 4000'));

The failure stakes: The hidden cost of manual and untyped mailing

The success transformation: Elegant, end-to-end typed postal pipelines

Building an enterprise NestJS postal module with dependency injection

Technical blueprint: Complete NestJS PostalService implementation

src/postal/postal.service.ts — typescript
import { Injectable, Logger, BadRequestException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import axios, { AxiosInstance } from 'axios';
import { CreateLetterDto, LetterResponseDto } from './dto/letter.dto';
​
@Injectable()
export class PostalService {
  private readonly logger = new Logger(PostalService.name);
  private readonly httpClient: AxiosInstance;
​
  constructor(private readonly configService: ConfigService) {
    const apiKey = this.configService.get<string>('LETTERAPI_API_KEY');
    if (!apiKey) {
      throw new Error('LETTERAPI_API_KEY configuration is missing');
    }
    this.httpClient = axios.create({
      baseURL: 'https://api.letterapi.uk/v1',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      timeout: 15000,
    });
  }
​
  async dispatchLetter(dto: CreateLetterDto, idempotencyKey?: string): Promise<LetterResponseDto> {
    this.logger.log(`Dispatching letter for recipient: ${dto.recipient.name}, Postcode: ${dto.recipient.postcode}`);
    try {
      const response = await this.httpClient.post<LetterResponseDto>('/letters', dto, {
        headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {},
      });
      this.logger.log(`Letter created successfully: ID ${response.data.id}`);
      return response.data;
    } catch (error: any) {
      this.logger.error(`LetterAPI Dispatch Failed: ${error.response?.data?.message || error.message}`);
      throw new BadRequestException(error.response?.data || 'Failed to dispatch letter');
    }
  }
}

Handling stream-based PDF uploads with form-data and Node.js Streams

Resilient worker queues with BullMQ, Redis, and automated dead-letter queues

Comprehensive unit testing with Vitest and MSW (Mock Service Worker)

Monitoring, telemetry, and OpenTelemetry tracing for postal pipelines

Type-safe error hierarchies: Handling DomainErrors, NetworkErrors, and ValidationErrors in TypeScript

Deploying postal microservices to AWS Lambda and Cloudflare Workers

Handling rate limits, 429 status codes, and leaky bucket throttling in Node.js

Securing environmental credentials and secret management in CI/CD pipelines

The complete Node.js end-to-end postal pipeline: From database trigger to physical doorstep

Key takeaways for TypeScript engineers: Clean architecture for physical delivery