transactional-sdk

Official TypeScript SDK for the Transactional Email & SMS API.

Installation

npm install transactional-sdk
# or
yarn add transactional-sdk
# or
pnpm add transactional-sdk

Quick Start

import { Transactional } from 'transactional-sdk';

const client = new Transactional({
  apiKey: 'tr_live_xxxxx',
});

// Send an email
const result = await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello!',
  html: '<h1>Hello World</h1>',
  text: 'Hello World',
});

console.log('Email sent:', result.messageId);

Features

• Full TypeScript support with comprehensive type definitions
• Automatic retries with exponential backoff
• All API endpoints supported (Email, SMS, Templates, and more)
• Works in Node.js, Bun, Deno, and Edge runtimes
• Zero dependencies

Usage Examples

Send Email with Template

const result = await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  template: 'welcome-email',
  data: {
    name: 'John',
    company: 'Acme Inc',
  },
});

Send to Multiple Recipients

const result = await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  subject: 'Team Update',
  html: '<p>Here is your weekly update...</p>',
});

Batch Send

const results = await client.emails.sendBatch([
  {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hello User 1',
    html: '<p>Hello!</p>',
  },
  {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hello User 2',
    html: '<p>Hello!</p>',
  },
]);

Send SMS

const result = await client.sms.send({
  from: '+15551234567',
  to: '+15559876543',
  body: 'Your verification code is 123456',
});

Manage Templates

// List templates
const { templates } = await client.templates.list();

// Create a template
const template = await client.templates.create({
  name: 'Welcome Email',
  alias: 'welcome-email',
  subject: 'Welcome {{name}}!',
  html: '<h1>Welcome {{name}}!</h1>',
});

// Update a template
await client.templates.update(template.id, {
  subject: 'Welcome to our platform, {{name}}!',
});

View Statistics

const stats = await client.stats.getOutbound({
  fromDate: '2024-01-01',
  toDate: '2024-01-31',
});

console.log(`Sent: ${stats.sent}`);
console.log(`Delivered: ${stats.delivered}`);
console.log(`Bounced: ${stats.bounced}`);

Error Handling

import { Transactional, TransactionalError } from 'transactional-sdk';

try {
  await client.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Test',
    html: '<p>Test</p>',
  });
} catch (error) {
  if (error instanceof TransactionalError) {
    console.log('API Error:', error.message);
    console.log('Error Code:', error.code);
    console.log('HTTP Status:', error.status);
  }
}

Configuration

const client = new Transactional({
  // Required: Your API key
  apiKey: 'tr_live_xxxxx',

  // Optional: Custom base URL (default: https://api.usetransactional.com)
  baseUrl: 'https://api.usetransactional.com',

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,

  // Optional: Number of retries (default: 3)
  retries: 3,
});

Available Resources

| Resource | Description | |----------|-------------| | client.emails | Send emails and batch emails | | client.sms | Send SMS messages | | client.templates | Manage email templates | | client.domains | Domain verification and DNS | | client.senders | Sender signature management | | client.bounces | Bounce management | | client.suppressions | Suppression list management | | client.messages | Message history | | client.stats | Email and SMS statistics | | client.webhooks | Webhook management |

Requirements

• Node.js 18.0.0 or later
• TypeScript 5.0 or later (for TypeScript users)

Documentation

Full documentation is available at usetransactional.com/docs/sdk

License

MIT - see LICENSE for details.