Skip to content

Node.js SDK

Official Node.js SDK for the ToSend email API.

Installation

Terminal window
npm install tosend

Quick Start

import { ToSend } from 'tosend';


const tosend = new ToSend('tsend_your_api_key');


const response = await tosend.send({
  from: { email: 'hello@yourdomain.com', name: 'Your App' },
  to: [{ email: 'user@example.com' }],
  subject: 'Welcome!',
  html: '<h1>Hello!</h1><p>Thanks for signing up.</p>',
});


console.log(response.message_id);

Configuration

Simple (API key only)

const tosend = new ToSend('tsend_your_api_key');

With Options

const tosend = new ToSend({
  apiKey: 'tsend_your_api_key',
  baseUrl: 'https://api.tosend.com', // optional
  timeout: 30000, // optional, in milliseconds
});

Send Email

Basic Email

const response = await tosend.send({
  from: { email: 'hello@yourdomain.com', name: 'Your App' },
  to: [
    { email: 'user@example.com' },
    { email: 'another@example.com', name: 'John Doe' },
  ],
  subject: 'Hello!',
  html: '<h1>Welcome</h1>',
  text: 'Welcome', // optional
});

With CC, BCC, and Reply-To

const response = await tosend.send({
  from: { email: 'hello@yourdomain.com' },
  to: [{ email: 'user@example.com' }],
  cc: [{ email: 'cc@example.com' }],
  bcc: [{ email: 'bcc@example.com' }],
  reply_to: { email: 'support@yourdomain.com', name: 'Support' },
  subject: 'Hello',
  html: '<p>Hello World</p>',
});

With Attachments

import * as fs from 'fs';


const response = await tosend.send({
  from: { email: 'hello@yourdomain.com' },
  to: [{ email: 'user@example.com' }],
  subject: 'Your Invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      type: 'application/pdf',
      name: 'invoice.pdf',
      content: fs.readFileSync('invoice.pdf').toString('base64'),
    },
  ],
});

Batch Sending

Send multiple emails in a single request:

const response = await tosend.batch([
  {
    from: { email: 'hello@yourdomain.com' },
    to: [{ email: 'user1@example.com' }],
    subject: 'Hello User 1',
    html: '<p>Welcome!</p>',
  },
  {
    from: { email: 'hello@yourdomain.com' },
    to: [{ email: 'user2@example.com' }],
    subject: 'Hello User 2',
    html: '<p>Welcome!</p>',
  },
]);


response.results.forEach((result) => {
  if (result.status === 'success') {
    console.log('Sent:', result.message_id);
  } else {
    console.log('Failed:', result.message);
  }
});

Account Info

const info = await tosend.getAccountInfo();


console.log(info.account.title);
console.log(info.account.emails_usage_this_month);
console.log(info.account.emails_sent_last_24hrs);


info.domains.forEach((domain) => {
  console.log(domain.domain_name, domain.verification_status);
});

Error Handling

import { ToSend, ToSendError } from 'tosend';


try {
  const response = await tosend.send({
    from: { email: 'hello@yourdomain.com' },
    to: [{ email: 'user@example.com' }],
    subject: 'Hello',
    html: '<p>Hello</p>',
  });
} catch (error) {
  if (error instanceof ToSendError) {
    console.log('Error:', error.message);
    console.log('Code:', error.code);
    console.log('Errors:', error.errors);


    if (error.isValidationError) {
      // Handle validation error (422)
    }


    if (error.isAuthenticationError) {
      // Handle auth error (401/403)
    }


    if (error.isRateLimitError) {
      // Handle rate limit (429)
    }
  }
}

TypeScript

Full TypeScript support with exported types:

import {
  ToSend,
  ToSendError,
  SendEmailParams,
  SendEmailResponse,
  BatchEmailResponse,
  AccountInfo,
  Address,
  Attachment,
} from 'tosend';