BaxMail SDK for Node.js

Server-side transactional email via BaxMail — for Express, NestJS, Next.js API routes, and any Node.js backend.

For BaxMail webhook verification (and other BaxCloud product webhooks), use @baxcloud/baxcloud-server-sdk alongside this package.

Product-specific SDKs:

• @baxcloud/baxstream — docs — video conversion + AI
• @baxcloud/baxmail — docs — transactional email
• @baxcloud/baxverify — docs — SMS OTP verification
• @baxcloud/baxlinks — docs — deep linking & attribution

Installation

npm install @baxcloud/baxmail

pnpm add @baxcloud/baxmail

Quick Start

import { BaxCloudMailClient } from '@baxcloud/baxmail';

const mail = new BaxCloudMailClient({
  projectId: process.env.BAXCLOUD_PROJECT_ID!,
  apiKey: process.env.BAXCLOUD_API_KEY!,
});

await mail.sendEmail({
  to: '[email protected]',
  subject: 'Welcome to MyApp',
  html: '<h1>Thanks for signing up!</h1>',
  text: 'Thanks for signing up!',
});

Sender address (from / fromName)

By default, BaxMail uses the default sender configured in Dashboard → BaxMail → Setup.

Override per message when needed:

await mail.sendEmail({
  to: '[email protected]',
  subject: 'Your receipt',
  html: '<p>Order #1234 confirmed.</p>',
  from: '[email protected]', // must be on a verified domain
  fromName: 'My App',                        // display name in the inbox
  replyTo: '[email protected]',
});

The from address must belong to a domain verified in BaxMail setup. If omitted, the project default is used.

Verified sending domain (sendingDomain)

When your project has multiple verified domains, pass sendingDomain to pick which domain to send from:

await mail.sendEmail({
  to: '[email protected]',
  subject: 'Brand B update',
  html: '<p>Hello</p>',
  sendingDomain: 'brand-b.com', // → [email protected] (project default local-part)
  fromName: 'Brand B',
});

Client-wide default:

const mail = new BaxCloudMailClient({
  projectId: '...',
  apiKey: '...',
  sendingDomain: 'yourdomain.com',
});

Sent as the X-BaxMail-Domain header. When omitted, BaxMail uses the default from BaxMail Setup.

API Reference

| Method | Description | |--------|-------------| | sendEmail(options) | Send transactional email | | getStats(days?) | Sent / delivered / failed counts | | listLogs(options?) | Paginated delivery logs |

sendEmail options

| Field | Required | Description | |-------|----------|-------------| | to | Yes | Recipient email | | subject | Yes | Email subject | | html | Yes | HTML body | | text | No | Plain-text fallback | | from | No | Override sender address (verified domain) | | fromName | No | Override sender display name | | sendingDomain | No | Verified domain (X-BaxMail-Domain header) when from is omitted | | replyTo | No | Reply-To address | | attachments | No | Base64 attachments | | metadata | No | Stored in delivery logs |

Error handling

import { BaxMailError } from '@baxcloud/baxmail';

try {
  await mail.sendEmail({ to: '[email protected]', subject: 'Hi', html: '<p>Hi</p>' });
} catch (err) {
  if (err instanceof BaxMailError) {
    console.error(err.statusCode, err.code, err.message);
    // err.details?.helpUrl → dashboard link for setup issues
  }
}

Common error codes: BAXMAIL_FEATURE_DISABLED, BAXMAIL_DOMAIN_NOT_VERIFIED, BAXMAIL_SENDER_NOT_CONFIGURED, BAXMAIL_SEND_FAILED.

Full reference: baxcloud.tech/docs/baxmail

Examples

See examples/ for Express and order confirmation samples.

Requirements

• Node.js 18+
• BaxMail enabled on your BaxCloud project
• Verified sending domain (Dashboard → BaxMail → Setup)
• API key with BaxMail scope

Related SDKs

• @baxcloud/baxcloud-server-sdk — docs — webhooks, rooms, streaming, PK Battle
• @baxcloud/baxstream — docs — video conversion + AI
• @baxcloud/baxverify — docs — SMS OTP verification
• @baxcloud/baxlinks — docs — deep linking & attribution
• @baxcloud/parse-server-baxmail — docs — Parse Server email adapter

License

MIT

Support

• Help: https://baxcloud.tech/dashboard/help
• Contact: https://baxcloud.tech/contact
• Documentation: https://baxcloud.tech/docs/baxmail/sdk/node
• Email: [email protected]