isend.ai Node.js SDK

A simple Node.js SDK for sending emails through isend.ai using various email connectors like AWS SES, SendGrid, Mailgun, and more.

Installation

npm install @isend-ai/nodejs-sdk

Quick Start

const { ISendClient } = require('@isend-ai/nodejs-sdk');

// Initialize the client
const client = new ISendClient('your-api-key-here');

// Send email using template
const emailData = {
  template_id: 124,
  to: '[email protected]',
  dataMapping: {
    name: 'ISend'
  }
};

client.sendEmail(emailData)
  .then(response => {
    console.log('Email sent successfully!', response);
  })
  .catch(error => {
    console.error('Error sending email:', error.message);
  });

TypeScript

import { ISendClient } from '@isend-ai/nodejs-sdk';

// Initialize the client
const client = new ISendClient('your-api-key-here');

// Send email using template
async function sendEmail() {
  try {
    const emailData = {
      template_id: 124,
      to: '[email protected]',
      dataMapping: {
        name: 'ISend'
      }
    };
    
    const response = await client.sendEmail(emailData);
    console.log('Email sent successfully!', response);
  } catch (error) {
    console.error('Error sending email:', error.message);
  }
}

sendEmail();

Usage

Send Email Using Template

const emailData = {
  template_id: 124,
  to: '[email protected]',
  dataMapping: {
    name: 'ISend'
  }
};

const response = await client.sendEmail(emailData);

Custom Configuration

const client = new ISendClient('your-api-key-here', {
  timeout: 60000, // 60 seconds
  baseURL: 'https://custom.isend.ai/api' // Custom API endpoint
});

API Reference

ISendClient

Constructor

new ISendClient(string apiKey, ISendConfig config = {})

Parameters:

• apiKey (string): Your isend.ai API key (required)
• config (ISendConfig): Additional configuration options (optional)

Methods

sendEmail(EmailData emailData): Promise

Sends an email using the provided template and data.

Parameters:

• emailData (EmailData): Email data including:
  • template_id (number): The template ID to use
  • to (string): Recipient email address
  • dataMapping (object): Data mapping for template variables

Returns: Promise

getApiKey(): string

Returns the masked API key for debugging purposes.

Returns: string (masked API key)

getConfig(): ISendConfig

Returns the current configuration.

Returns: ISendConfig

Types

ISendConfig

interface ISendConfig {
  timeout?: number;    // Request timeout in milliseconds (default: 30000)
  baseURL?: string;    // Custom API base URL (default: 'https://www.isend.ai/api')
}

EmailData

interface EmailData {
  template_id: number;                    // Template ID to use
  to: string;                            // Recipient email address
  dataMapping?: Record<string, any>;     // Data mapping for template variables
  [key: string]: any;                    // Additional email properties
}

ISendResponse

interface ISendResponse {
  success: boolean;      // Whether the request was successful
  message?: string;      // Response message
  data?: any;           // Response data
  [key: string]: any;   // Additional response properties
}

ISendError

interface ISendError {
  message: string;       // Error message
  status?: number;       // HTTP status code
  code?: string;         // Error code
}

Error Handling

The SDK throws ISendError for any errors:

try {
  const response = await client.sendEmail({
    template_id: 124,
    to: '[email protected]',
    dataMapping: {
      name: 'ISend'
    }
  });
} catch (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.status);
  console.error('Code:', error.code);
}

Examples

See the examples/ directory for complete usage examples:

• examples/send-email.js - JavaScript example
• examples/send-email.ts - TypeScript example

Development

Prerequisites

• Node.js 14.0.0 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/isend-ai/nodejs-sdk.git
cd nodejs-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

Available Scripts

• npm run build - Build the TypeScript code
• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint issues

Requirements

• Node.js 14.0.0 or higher
• npm or yarn

License

MIT License