Skip to main content

Overview

The official Sendmator Node.js SDK provides a type-safe, promise-based interface for integrating Sendmator into your Node.js and TypeScript applications.

Features​

  • ✅ Full TypeScript Support - Complete type definitions for all methods and responses
  • ✅ Promise-Based API - Modern async/await interface
  • ✅ Comprehensive Coverage - All Sendmator API endpoints
  • ✅ Error Handling - Detailed error messages with status codes
  • ✅ Team Support - Multi-tenant applications with team ID management
  • ✅ Automatic Retries - Built-in request timeout and error handling
  • ✅ Tree-Shakeable - Optimized bundle size

Installation​

npm install @sendmator/node

Or with yarn:

yarn add @sendmator/node

Or with pnpm:

pnpm add @sendmator/node

Quick Start​

import Sendmator from '@sendmator/node';

// Initialize the client
const sendmator = new Sendmator({
  apiKey: process.env.SENDMATOR_API_KEY,
});

// Send an email
const result = await sendmator.email.send({
  recipient_type: 'direct_email',
  direct_email: 'user@example.com',
  template_key: 'welcome-email',
  variables: {
    name: 'John Doe',
    loginUrl: 'https://app.example.com/login'
  }
});

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

Configuration​

Basic Configuration​

import Sendmator from '@sendmator/node';

const sendmator = new Sendmator({
  apiKey: 'sk_live_your_api_key', // Required
});

Advanced Configuration​

const sendmator = new Sendmator({
  apiKey: process.env.SENDMATOR_API_KEY,    // Required
  baseURL: 'http://localhost:3000/api',     // Optional: Override API URL (defaults to https://api.sendmator.com/api)
  timeout: 30000,                            // Optional: Request timeout (ms)
  teamId: 'team_uuid',                       // Optional: For team-scoped requests
});
Default Base URL

The SDK defaults to https://api.sendmator.com/api. Only override baseURL for local development or self-hosted instances.

Environment Variables​

# .env
SENDMATOR_API_KEY=sk_live_your_api_key_here
import Sendmator from '@sendmator/node';
import * as dotenv from 'dotenv';

dotenv.config();

const sendmator = new Sendmator({
  apiKey: process.env.SENDMATOR_API_KEY!,
});

Team Management​

For multi-tenant applications, you can set and manage team context:

// Set team ID for all subsequent requests
sendmator.setTeamId('team_uuid');

// Make team-scoped requests
await sendmator.contacts.list();

// Clear team ID
sendmator.clearTeamId();

// Or pass team ID during initialization
const sendmator = new Sendmator({
  apiKey: process.env.SENDMATOR_API_KEY,
  teamId: 'team_uuid',
});

Available Resources​

The SDK provides access to the following resources:

Contacts​

Manage your contact database with full CRUD operations and preference management.

sendmator.contacts.create(data)
sendmator.contacts.get(id)
sendmator.contacts.getByExternalId(externalId)
sendmator.contacts.list(params)
sendmator.contacts.update(id, data)
sendmator.contacts.delete(id, hard?)
sendmator.contacts.bulkCreate(data)
sendmator.contacts.addTags(id, tags)
sendmator.contacts.removeTags(id, tags)
sendmator.contacts.unsubscribe(id)
sendmator.contacts.getPreferences(id)
sendmator.contacts.updatePreferences(id, data)
sendmator.contacts.updateSinglePreference(id, channel, category, data)
sendmator.contacts.unsubscribeAll(id)
sendmator.contacts.unsubscribeChannel(id, channel)
sendmator.contacts.subscribeAll(id)

Email​

Send emails to contacts, tags, or direct email addresses.

sendmator.email.send(data)
sendmator.email.getExecutionStatus(executionId)
sendmator.email.listExecutions(params)

SMS​

Send SMS messages to your contacts.

sendmator.sms.send(data)
sendmator.sms.getExecutionStatus(executionId)
sendmator.sms.listExecutions(params)

WhatsApp​

Send WhatsApp messages using approved templates.

sendmator.whatsapp.send(data)
sendmator.whatsapp.getExecutionStatus(executionId)
sendmator.whatsapp.listExecutions(params)

OTP​

Generate and verify one-time passwords across multiple channels.

sendmator.otp.send(data)
sendmator.otp.verify(data)
sendmator.otp.resend(data)

Error Handling​

The SDK throws SendmatorError for API errors:

import Sendmator, { SendmatorError } from '@sendmator/node';

try {
  await sendmator.email.send({
    recipient_type: 'direct_email',
    direct_email: 'invalid-email',
    template_key: 'welcome',
  });
} catch (error) {
  if (error instanceof SendmatorError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Code:', error.code);
    console.error('Details:', error.details);
  }
}

Common Error Codes​

Status CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
404Not Found - Resource doesn't exist
409Conflict - Duplicate resource
429Too Many Requests - Rate limit exceeded
500Internal Server Error

TypeScript Support​

The SDK is written in TypeScript and provides complete type definitions:

import Sendmator, {
  Contact,
  SendEmailRequest,
  SendSMSRequest,
  SendOTPRequest,
  SendmatorResponse,
} from '@sendmator/node';

const sendmator = new Sendmator({
  apiKey: process.env.SENDMATOR_API_KEY,
});

// Fully typed request
const emailRequest: SendEmailRequest = {
  recipient_type: 'direct_email',
  direct_email: 'user@example.com',
  template_key: 'welcome-email',
  variables: { name: 'John' },
};

// Fully typed response
const response: SendmatorResponse = await sendmator.email.send(emailRequest);

Next Steps​

  • Contacts - Comprehensive contact management guide
  • Email - Send emails with templates or raw content
  • SMS - SMS messaging guide
  • WhatsApp - WhatsApp messaging guide
  • OTP - One-time password verification

Support​