The @usetransactional/node SDK provides a fully typed TypeScript client for the Transactional API. Send emails, SMS messages, manage templates, domains, and more with built-in retries, error handling, and complete type safety.

Installation

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

Quick Start

const { Transactional } = require("@usetransactional/node");
 
const client = new Transactional({ apiKey: "your-api-key" });
 
const response = await client.emails.send({
  from: "sender@yourdomain.com",
  to: "recipient@example.com",
  subject: "Hello from Transactional",
  htmlBody: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  textBody: "Welcome! Thanks for signing up.",
});
 
console.log("Message ID:", response.messageId);

Configuration

When creating a client instance, you can pass an options object to customize behavior:

const client = new Transactional({
  apiKey: "your-api-key",
  baseUrl: "https://api.usetransactional.com",
  timeout: 30000,
  retries: 3,
});

Option	Type	Default	Description
`apiKey`	`string`	required	Your Transactional API key
`baseUrl`	`string`	`https://api.usetransactional.com`	API base URL (override for self-hosted or testing)
`timeout`	`number`	`30000`	Request timeout in milliseconds
`retries`	`number`	`3`	Number of automatic retries on transient failures

Email

Send an Email

Use client.emails.send() to send a single email. All available parameters are shown below:

const response = await client.emails.send({
  // Required
  from: "sender@yourdomain.com",
  to: "recipient@example.com", // string or string[]
  subject: "Order Confirmation",
 
  // Content (provide htmlBody, textBody, or templateAlias)
  htmlBody: "<h1>Your order is confirmed</h1>",
  textBody: "Your order is confirmed",
 
  // Template-based sending (alternative to htmlBody/textBody)
  templateAlias: "order-confirmation",
  templateModel: { orderId: "12345", total: "$49.99" },
 
  // Recipients
  cc: "manager@example.com",       // string or string[]
  bcc: "archive@example.com",      // string or string[]
  replyTo: "support@yourdomain.com",
 
  // Tracking & metadata
  tag: "order-confirmation",
  trackOpens: true,
  trackLinks: true,
  metadata: { orderId: "12345", userId: "user_abc" },
  messageStream: "outbound",
 
  // Attachments
  attachments: [
    {
      name: "receipt.pdf",
      content: "base64-encoded-content",
      contentType: "application/pdf",
    },
  ],
 
  // Custom headers
  headers: {
    "X-Custom-Header": "custom-value",
  },
});

Send Batch Emails

Send multiple emails in a single API call using client.emails.sendBatch():

const responses = await client.emails.sendBatch([
  {
    from: "sender@yourdomain.com",
    to: "alice@example.com",
    subject: "Welcome, Alice!",
    htmlBody: "<p>Welcome aboard, Alice.</p>",
    tag: "welcome",
  },
  {
    from: "sender@yourdomain.com",
    to: "bob@example.com",
    subject: "Welcome, Bob!",
    htmlBody: "<p>Welcome aboard, Bob.</p>",
    tag: "welcome",
  },
]);

Template-Based Sending

If you have pre-configured templates, you can reference them by alias and pass dynamic data:

const response = await client.emails.send({
  from: "sender@yourdomain.com",
  to: "recipient@example.com",
  subject: "Your Weekly Report",
  templateAlias: "weekly-report",
  templateModel: {
    userName: "Alice",
    reportDate: "2025-01-15",
    metrics: { sent: 1200, delivered: 1185, opened: 834 },
  },
});

SMS

Send an SMS

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

You can also send template-based SMS messages:

const response = await client.sms.send({
  from: "+15551234567",
  to: "+15559876543",
  templateAlias: "verification-code",
  templateModel: { code: "123456" },
});

Send Batch SMS

const responses = await client.sms.sendBatch([
  {
    from: "+15551234567",
    to: "+15559876543",
    body: "Your order has shipped!",
  },
  {
    from: "+15551234567",
    to: "+15551112222",
    body: "Your order has shipped!",
  },
]);

Retrieve SMS Messages

// Get a specific SMS by ID
const sms = await client.sms.get("sms_abc123");
 
// List sent SMS messages
const messages = await client.sms.list();
 
// List inbound SMS messages
const inbound = await client.sms.listInbound();

Templates

Manage your email and SMS templates programmatically.

List Templates

const templates = await client.templates.list();

Get a Template

const template = await client.templates.get("template_abc123");

Create a Template

const template = await client.templates.create({
  name: "Welcome Email",
  subject: "Welcome to {{companyName}}",
  htmlBody: "<h1>Welcome, {{name}}!</h1><p>Thanks for joining {{companyName}}.</p>",
  textBody: "Welcome, {{name}}! Thanks for joining {{companyName}}.",
  alias: "welcome-email",
});
 
console.log("Created template:", template.id);

Update a Template

const updated = await client.templates.update("template_abc123", {
  subject: "Welcome to {{companyName}} - Updated",
  htmlBody: "<h1>Welcome, {{name}}!</h1><p>We're glad to have you at {{companyName}}.</p>",
});

Delete a Template

await client.templates.delete("template_abc123");

Domains

Manage sending domains and DNS verification.

List Domains

const domains = await client.domains.list();

Get Domain Details

const domain = await client.domains.get("domain_abc123");
console.log("Verified:", domain.verified);
console.log("DNS records:", domain.dnsRecords);

Create a Domain

const domain = await client.domains.create({
  name: "mail.yourdomain.com",
});
 
console.log("Add these DNS records:", domain.dnsRecords);

Verify a Domain

After adding the required DNS records, trigger verification:

const result = await client.domains.verify("domain_abc123");
console.log("Verified:", result.verified);

Delete a Domain

await client.domains.delete("domain_abc123");

Other Resources

The SDK provides access to additional API resources:

Resource	Methods	Description
`client.senders`	`list()`, `get()`, `create()`, `update()`, `delete()`	Manage sender identities and signatures
`client.messages`	`list()`, `get()`, `getDetails()`	Retrieve sent message history and details
`client.bounces`	`list()`, `get()`, `activate()`	View and manage bounced messages
`client.suppressions`	`list()`, `check()`, `add()`, `remove()`	Manage suppression lists for compliance
`client.stats`	`getOverview()`, `getEmailStats()`, `getSmsStats()`	Retrieve delivery and engagement statistics
`client.webhooks`	`list()`, `get()`, `create()`, `update()`, `delete()`	Configure webhook endpoints for events

Error Handling

All SDK errors extend the base TransactionalError class. Use try/catch to handle errors gracefully:

const { TransactionalError } = require("@usetransactional/node");
 
try {
  const response = await client.emails.send({
    from: "sender@yourdomain.com",
    to: "recipient@example.com",
    subject: "Test",
    htmlBody: "<p>Hello</p>",
  });
} catch (error) {
  if (error instanceof TransactionalError) {
    console.error("Message:", error.message);
    console.error("Code:", error.code);
    console.error("Status:", error.status);
  } else {
    throw error;
  }
}

Error Types

Error Class	Description
`TransactionalError`	Base error class for all SDK errors
`ApiError`	Server returned a non-2xx response (4xx or 5xx)
`ValidationError`	Request payload failed validation (missing or invalid fields)
`NetworkError`	Network connectivity issue (DNS failure, connection refused)
`TimeoutError`	Request exceeded the configured timeout

TypeScript Types

The SDK exports all request and response types for full type safety:

const {
  Transactional,
  TransactionalError,
} = require("@usetransactional/node");
 
// Key interfaces available:
// SendEmailOptions    - Parameters for client.emails.send()
// SendSmsOptions      - Parameters for client.sms.send()
// Template            - Template object returned by client.templates.get()
// Domain              - Domain object returned by client.domains.get()
// EmailResponse       - Response from client.emails.send()
// SmsResponse         - Response from client.sms.send()
// BounceRecord        - Bounce record from client.bounces.list()
// SuppressionRecord   - Suppression record from client.suppressions.list()
// WebhookConfig       - Webhook configuration object

Requirements

Node.js 18 or later
TypeScript 5.0+ (optional, but recommended for full type safety)

Node.js SDK