SDK Reference

Complete TypeScript SDK reference. The PostaSend SDK is fully typed and works in Node.js 18+, Deno, Bun, and edge runtimes.

Installation and Setup

The SDK is available on npm as @postasend. It ships with full TypeScript definitions and has zero runtime dependencies.

bash

npm install @postasend

# Verify the installation
npx tsc --version # Requires TypeScript 4.7+

Client Configuration

The PostaSend client accepts configuration options for API key, base URL (for self-hosted deployments), timeout, and retry behavior.

typescript

import { PostaSend } from 'postasend';

const client = new PostaSend({
  apiKey: process.env.POSTASEND_API_KEY!,

  // Optional configuration
  baseUrl: 'https://api.postasend.dev', // default
  timeout: 30_000,                      // ms, default 30s
  maxRetries: 3,                        // default 3
  mode: 'live',                         // 'live' | 'test'
  logLevel: 'error',                    // 'debug' | 'info' | 'warn' | 'error'
});

Emails API

The emails namespace provides methods for sending and retrieving email messages.

typescript

// Send an email
const msg = await client.emails.send({
  from: string,
  to: string | string[] | Recipient[],
  cc?: string | string[] | Recipient[],
  bcc?: string | string[] | Recipient[],
  subject?: string,          // required if not using templateId
  html?: string,
  text?: string,
  templateId?: string,
  templateVersion?: number,
  data?: Record<string, unknown>,
  attachments?: Attachment[],
  headers?: Record<string, string>,
  tags?: string[],
  scheduledAt?: Date | string,
});

// Get message status
const message = await client.emails.get(messageId: string);

// List recent messages
const messages = await client.emails.list({
  limit?: number,   // default 20, max 100
  cursor?: string,
  tag?: string,
  status?: MessageStatus,
  from?: Date,
  to?: Date,
});

Templates API

Manage reusable email templates programmatically.

typescript

// Create template
const tmpl = await client.templates.create({
  name: string,
  subject: string,
  html: string,
  text?: string,
});

// Get template
const tmpl = await client.templates.get(templateId: string);

// Update template (creates new version)
const tmpl = await client.templates.update(templateId, {
  html?: string,
  subject?: string,
  text?: string,
});

// List templates
const { data, nextCursor } = await client.templates.list({
  limit?: number,
  cursor?: string,
});

// Preview with data
const preview = await client.templates.preview(templateId, {
  data: Record<string, unknown>,
  version?: number,
});

Error Handling

The SDK throws typed errors. Check the error code to handle specific failure cases gracefully.

typescript

import { PostaSend, PostaSendError, PostaSendAuthError } from 'postasend';

try {
  await client.emails.send({ ... });
} catch (error) {
  if (error instanceof PostaSendAuthError) {
    // 401: Invalid or expired API key
    console.error('Auth failed:', error.message);
  } else if (error instanceof PostaSendError) {
    // Other API errors (4xx/5xx)
    console.error('API error:', error.code, error.message);
    console.error('Request ID:', error.requestId);
  } else {
    // Network error, timeout, etc.
    throw error;
  }
}

← Webhooks