@sendmator/node

v0.0.3

Published

14 days ago

Official Node.js SDK for Sendmator - Multi-channel messaging API (Email, SMS, WhatsApp, Push Notifications, OTP)

@sendmator/node

Official Node.js SDK for Sendmator - A powerful multi-channel messaging API for Email, SMS, WhatsApp, and OTP.

Features

📧 Email - Send transactional and bulk emails
📱 SMS - Send SMS messages worldwide
💬 WhatsApp - Send WhatsApp Business messages
🔐 OTP - One-Time Password authentication
👥 Contacts - Manage your contact lists
🚀 TypeScript - Full TypeScript support with type definitions
🔒 Secure - API key authentication with team isolation
⚡ Promise-based - Modern async/await API

Installation

npm install @sendmator/node

or with yarn:

yarn add @sendmator/node

Quick Start

// ESM / TypeScript (named import recommended)
import { Sendmator } from '@sendmator/node';

// CommonJS
// const { Sendmator } = require('@sendmator/node');

// Initialize the SDK
const sendmator = new Sendmator({
  apiKey: 'sk_test_your-api-key'
});

// Send an email - it's this simple!
await sendmator.email.sendTo('[email protected]', {
  template_key: 'welcome-email',
  variables: { name: 'John' }
});

Authentication

Get your API key from the Sendmator Dashboard.

const sendmator = new Sendmator({
  apiKey: 'sk_test_...',  // Required: Your API key
  teamId: 'team-id',      // Optional: Team ID for multi-tenant apps
  baseURL: 'https://api.sendmator.com/api', // Optional: Custom API URL
  timeout: 30000           // Optional: Request timeout in ms (default: 30000)
});

Email Examples

Send to Email Address (Simplest Method)

// Using a template
await sendmator.email.sendTo('[email protected]', {
  template_key: 'welcome-email',
  variables: { name: 'John' }
});

// With custom content
await sendmator.email.sendTo('[email protected]', {
  subject: 'Welcome!',
  html: '<h1>Hello John!</h1>',
  text: 'Hello John!' // Optional plain text version
});

// With custom sender
await sendmator.email.sendTo('[email protected]', {
  template_key: 'verify-api-otp',
  first_name: 'John',
  last_name: 'Doe',
  variables: {
    company: 'Acme Corp',
    OTP_CODE: 123456
  },
  from_email: '[email protected]',
  from_name: 'Acme Team'
});

Send to Existing Contact

await sendmator.email.sendToContact('user-123', {
  template_key: 'order-confirmation',
  variables: {
    order_id: 'ORD-456',
    total: '$99.99'
  }
});

Send to All Contacts (Broadcast)

// Simple broadcast
await sendmator.email.sendToAll({
  template_key: 'newsletter',
  variables: {
    month: 'March',
    year: 2025
  }
});

// Scheduled broadcast
await sendmator.email.sendToAll({
  template_key: 'announcement',
  variables: { feature: 'Dark Mode' },
  trigger_at: '2025-03-15T10:00:00Z', // ISO 8601 UTC timestamp
  from_email: '[email protected]',
  from_name: 'Company News'
});

Send to Contacts with Tags

// Single tag
await sendmator.email.sendToTags(['premium'], {
  template_key: 'exclusive-offer',
  variables: { discount: '20%' }
});

// Multiple tags
await sendmator.email.sendToTags(['premium', 'active'], {
  template_key: 'feature-announcement',
  variables: { feature: 'Advanced Analytics' }
});

// With scheduling
await sendmator.email.sendToTags(['beta'], {
  template_key: 'beta-update',
  variables: { version: '2.0' },
  from_email: '[email protected]',
  from_name: 'Beta Team',
  trigger_at: '2025-03-10T09:00:00Z'
});

Send to Segment

await sendmator.email.sendToSegment('segment-id-here', {
  template_key: 'targeted-campaign',
  variables: { campaign: 'Q1 2025' },
  from_email: '[email protected]'
});

Advanced: Full Control with send()

For advanced use cases, use the send() method with full control:

await sendmator.email.send({
  recipient_type: 'direct_email',
  direct_email: '[email protected]',
  direct_first_name: 'John',
  direct_last_name: 'Doe',
  template_key: 'welcome',
  variables: { company: 'Acme' },
  from_email: '[email protected]',
  from_name: 'Company',
  reply_to: '[email protected]',
  metadata: { user_id: '123', source: 'signup' },
  trigger_at: '2025-03-10T10:00:00Z'
});

Get Execution Status

const response = await sendmator.email.sendTo('[email protected]', {
  template_key: 'welcome'
});

// Check status later
const status = await sendmator.email.getExecutionStatus(response.data.trigger_id);
console.log(status.data);

List Executions

const executions = await sendmator.email.listExecutions({
  page: 1,
  limit: 20
});

executions.data.forEach(execution => {
  console.log(`${execution.id}: ${execution.status}`);
});

SMS

Send Single SMS

await sendmator.sms.send({
  recipient_type: 'direct_sms',
  direct_sms: '+1234567890',
  template_key: 'otp-sms',
  variables: {
    code: '123456',
    app_name: 'MyApp'
  }
});

Send Bulk SMS

await sendmator.sms.send({
  recipient_type: 'tag',
  tags: ['premium'],
  template_key: 'promotion-sms',
  variables: { discount: '20%' }
});

Send WhatsApp Message

await sendmator.whatsapp.send({
  recipient_type: 'direct_whatsapp',
  direct_whatsapp: '+1234567890',
  template_key: 'order-confirmation',
  variables: {
    customer_name: 'John',
    order_id: 'ORD-123',
    total: '$99.99'
  },
  conversation_category: 'UTILITY' // MARKETING, UTILITY, AUTHENTICATION
});

Send Bulk WhatsApp

await sendmator.whatsapp.send({
  recipient_type: 'all',
  template_key: 'announcement',
  variables: { message: 'New feature available!' },
  conversation_category: 'MARKETING'
});

OTP (One-Time Password)

Send OTP

// Send via email
const response = await sendmator.otp.send({
  channels: ['email'],
  recipients: {
    email: '[email protected]'
  }
});

console.log('Session ID:', response.data.session_id);

// Send via SMS
await sendmator.otp.send({
  channels: ['sms'],
  recipients: {
    sms: '+1234567890'
  }
});

// Send via multiple channels
await sendmator.otp.send({
  channels: ['email', 'sms'],
  recipients: {
    email: '[email protected]',
    sms: '+1234567890'
  }
});

Verify OTP

const result = await sendmator.otp.verify({
  session_token: 'session-id-from-send-response',
  otps: {
    email: '123456'
  }
});

if (result.data.verified) {
  console.log('OTP verified successfully!');
  // Proceed with user authentication
} else {
  console.log('Invalid OTP');
}

Resend OTP

await sendmator.otp.resend({
  session_token: 'session-id'
});

Contacts

Create Contact

const contact = await sendmator.contacts.create({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
  phone: '+1234567890',
  tags: ['customer', 'premium'],
  custom_fields: {
    plan: 'pro',
    signup_date: '2025-01-01'
  }
});

Get Contact

// By ID
const contact = await sendmator.contacts.get('contact-id');

// By email
const contact = await sendmator.contacts.getByEmail('[email protected]');

List Contacts

const contacts = await sendmator.contacts.list({
  page: 1,
  limit: 20,
  tags: ['premium'],
  search: 'john'
});

console.log(contacts.data);           // Array of contacts
console.log(contacts.pagination);     // Pagination info

Update Contact

await sendmator.contacts.update('contact-id', {
  first_name: 'Jane',
  tags: ['premium', 'vip'],
  custom_fields: { plan: 'enterprise' }
});

Delete Contact

await sendmator.contacts.delete('contact-id');

Manage Subscriptions

// Unsubscribe
await sendmator.contacts.unsubscribe('contact-id');

// Resubscribe
await sendmator.contacts.resubscribe('contact-id');

Manage Tags

// Add tags
await sendmator.contacts.addTags('contact-id', ['premium', 'early-adopter']);

// Remove tags
await sendmator.contacts.removeTags('contact-id', ['trial']);

Multi-Tenant Applications

For multi-tenant applications, you can set the team ID dynamically:

const sendmator = new Sendmator({ apiKey: 'sk_test_...' });

// Set team ID for a specific tenant
sendmator.setTeamId('team-123');
await sendmator.email.sendTo('[email protected]', {
  template_key: 'welcome'
});

// Switch to a different tenant
sendmator.setTeamId('team-456');
await sendmator.email.sendTo('[email protected]', {
  template_key: 'welcome'
});

// Clear team ID
sendmator.clearTeamId();

Error Handling

The SDK throws SendmatorError for API errors:

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

try {
  await sendmator.email.sendTo('[email protected]', {
    template_key: 'welcome'
  });
} catch (error) {
  if (error instanceof SendmatorError) {
    console.log('Status code:', error.statusCode);
    console.log('Error code:', error.code);
    console.log('Message:', error.message);
    console.log('Details:', error.details);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

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

// Type-safe email send
const request: SendEmailRequest = {
  recipient_type: 'direct_email',
  direct_email: '[email protected]',
  template_key: 'welcome',
  variables: { name: 'John' }
};

const response: SendmatorResponse = await sendmator.email.send(request);

API Method Reference

Email Methods

| Method | Description | Use Case | |--------|-------------|----------| | sendTo(email, options) | Send to email address | Quick, single recipient sends | | sendToContact(externalId, options) | Send to existing contact | Personalized emails to registered users | | sendToAll(options) | Broadcast to all contacts | Newsletters, announcements | | sendToTags(tags, options) | Send to tagged contacts | Targeted campaigns | | sendToSegment(segmentId, options) | Send to segment | Dynamic audience targeting | | send(request) | Advanced send with full control | Complex requirements |

All methods support:

Template-based or inline content
Variable substitution
Custom sender (from_email, from_name)
Scheduled sends (trigger_at)
Metadata for tracking

Environment Variables

You can store your API key in environment variables:

# .env
SENDMATOR_API_KEY=sk_test_your-api-key
SENDMATOR_TEAM_ID=your-team-id

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

Common Patterns

Transactional Emails

// Welcome email after signup
await sendmator.email.sendTo(user.email, {
  template_key: 'welcome',
  first_name: user.firstName,
  variables: {
    verification_url: generateVerificationUrl(user.id)
  }
});

// Order confirmation
await sendmator.email.sendToContact(user.externalId, {
  template_key: 'order-confirmation',
  variables: {
    order_id: order.id,
    items: order.items,
    total: order.total
  }
});

Marketing Campaigns

// Send to premium customers
await sendmator.email.sendToTags(['premium', 'active'], {
  template_key: 'new-feature',
  variables: {
    feature: 'Advanced Analytics',
    cta_url: 'https://app.example.com/analytics'
  },
  from_email: '[email protected]',
  from_name: 'Marketing Team'
});

Scheduled Sends

// Schedule for next week
const nextWeek = new Date();
nextWeek.setDate(nextWeek.getDate() + 7);

await sendmator.email.sendToAll({
  template_key: 'weekly-digest',
  variables: { week: '12' },
  trigger_at: nextWeek.toISOString()
});

Version Management

To publish a new version:

# Patch version (0.1.0 -> 0.1.1)
npm version patch

# Minor version (0.1.0 -> 0.2.0)
npm version minor

# Major version (0.1.0 -> 1.0.0)
npm version major

# Publish to NPM
npm publish --access public

Resources

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see the LICENSE file for details.

Support

For issues and questions:

📧 Email: [email protected]
💬 Discord: Join our community
🐛 Issues: GitHub Issues

Made with ❤️ by the Sendmator team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sendmator/node

Features

Installation

Quick Start

Authentication

Email Examples

Send to Email Address (Simplest Method)

Send to Existing Contact

Send to All Contacts (Broadcast)

Send to Contacts with Tags

Send to Segment

Advanced: Full Control with send()

Get Execution Status

List Executions

SMS

Send Single SMS

Send Bulk SMS

WhatsApp

Send WhatsApp Message

Send Bulk WhatsApp

OTP (One-Time Password)

Send OTP

Verify OTP

Resend OTP

Contacts

Create Contact

Get Contact

List Contacts

Update Contact

Delete Contact

Manage Subscriptions

Manage Tags

Multi-Tenant Applications

Error Handling

TypeScript Support

API Method Reference

Email Methods

Environment Variables

Common Patterns

Transactional Emails

Marketing Campaigns

Scheduled Sends

Version Management

Resources

Contributing

License

Support