Node.js SDK

The jetemail package is the official Node.js SDK for JetEmail transactional email (MIT license, Node.js 18+, uses native fetch, no runtime dependencies). Create a transactional API key in the dashboard: Outbound → Keys → Add API key. Use that key with the SDK.

Installation

npm install jetemail

Package on npm: jetemail. The package ships TypeScript types and both ESM (import) and CommonJS (require) builds.

Quick start

import { JetEmail } from 'jetemail';

const client = new JetEmail('your-transactional-api-key');

await client.email.send({
  from: 'Your App <hello@yourdomain.com>',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome!</h1>'
});

In CommonJS projects, use const { JetEmail } = require('jetemail'); instead of the import. Use a from address on a verified domain (see Getting started).

Constructor

// API key string
const client = new JetEmail('your-transactional-api-key');

// Or with options
const client = new JetEmail({
  apiKey: 'your-transactional-api-key',
  baseUrl: 'https://api.jetemail.com' // optional, this is the default
});

The constructor throws an Error if apiKey is missing. The client exposes two services:

Service	Property	Description
Email	`client.email`	Send a single email
Batch	`client.batch`	Send up to 100 emails in one request

`client.email.send(options)`

Send a single email. Options use the same field names as the REST API (snake_case, e.g. reply_to).

Field	Required	Description
`from`	✓	Sender, e.g. `"Name <email@domain.com>"`
`to`	✓	Recipient(s), string or array (max 50)
`subject`	✓	Subject line
`html`	*	HTML body (need `html` and/or `text`)
`text`	*	Plain text (need `html` and/or `text`)
`cc`, `bcc`, `reply_to`		Recipients, string or array (max 50 each)
`headers`		Custom headers as `{ 'X-Header': 'value' }`
`attachments`		Array of `{ filename, data }` where `data` is base64 (max 40MB total)

import { readFileSync } from 'fs';

const result = await client.email.send({
  from: 'App <noreply@example.com>',
  to: 'user@example.com',
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed.</p>',
  text: 'Your order has been confirmed.',
  cc: ['manager@example.com'],
  bcc: ['archive@example.com'],
  reply_to: 'support@example.com',
  headers: {
    'X-Custom-Header': 'value'
  },
  attachments: [
    {
      filename: 'receipt.pdf',
      data: readFileSync('/path/to/receipt.pdf').toString('base64')
    }
  ]
});

console.log(result.id);       // Message ID
console.log(result.response); // Queue confirmation message

Response shape: { id: string; response: string }. The SDK validates from, to, subject, and html/text locally before making the request and throws a plain Error if any is missing (see Error handling).

`client.batch.send(emails)`

Send up to 100 emails in one request. Each element uses the same fields as a single send. Returns summary (total, successful, failed) and results per message (success with id and response, or error with error and the original email).

const result = await client.batch.send([
  {
    from: 'App <noreply@example.com>',
    to: 'user1@example.com',
    subject: 'Hello User 1',
    html: '<p>Welcome!</p>'
  },
  {
    from: 'App <noreply@example.com>',
    to: 'user2@example.com',
    subject: 'Hello User 2',
    html: '<p>Welcome!</p>'
  }
]);

console.log(result.summary.successful);

for (const item of result.results) {
  if (item.status === 'success') {
    console.log(item.id);
  } else {
    console.log(item.error);
  }
}

An empty array, more than 100 emails, or an invalid email in the array throws a plain Error before any request is made.

Error handling

API errors throw JetEmailError, which has statusCode (HTTP status), message, and response (the parsed error body, { message?: string; error?: string }, when the API returned JSON).

import { JetEmail, JetEmailError } from 'jetemail';

try {
  await client.email.send({ /* ... */ });
} catch (error) {
  if (error instanceof JetEmailError) {
    console.error(error.statusCode, error.message, error.response);
  } else {
    throw error;
  }
}

Client-side validation failures (missing required fields, an empty or oversized batch, or a missing apiKey) throw a plain Error rather than JetEmailError. Network failures from fetch are not wrapped and surface as-is. Common status codes: 400 invalid request, 401 bad/missing API key, 500 server error.

TypeScript

Exported types: JetEmail, JetEmailConfig, SendEmailOptions, SendEmailResponse, SendBatchResponse, BatchEmailResult, BatchEmailSuccess, BatchEmailError, Attachment, EmailHeaders, EmailRecipient, JetEmailError, plus the Emails and Batch service classes.

For additional examples, see the README on npm. REST details: API reference.

​Node.js SDK

​Installation

​Quick start

​Constructor

​client.email.send(options)

​client.batch.send(emails)

​Error handling

​TypeScript