@usetransactional/node

Official TypeScript SDK for the Transactional Email & SMS API.

Installation

npm install @usetransactional/node
# or
yarn add @usetransactional/node
# or
pnpm add @usetransactional/node

Quick Start

import { Transactional } from '@usetransactional/node';

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

// Send an email
const result = await client.emails.send({
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  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: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  template: 'welcome-email',
  data: {
    name: 'John',
    company: 'Acme Inc',
  },
});

Send to Multiple Recipients

const result = await client.emails.send({
  from: 'sender@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  subject: 'Team Update',
  html: '<p>Here is your weekly update...</p>',
});

Batch Send

const results = await client.emails.sendBatch([
  {
    from: 'sender@yourdomain.com',
    to: 'user1@example.com',
    subject: 'Hello User 1',
    html: '<p>Hello!</p>',
  },
  {
    from: 'sender@yourdomain.com',
    to: 'user2@example.com',
    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 '@usetransactional/node';

try {
  await client.emails.send({
    from: 'sender@yourdomain.com',
    to: 'recipient@example.com',
    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.