BaxMail/Node.js SDK

Node.js SDK

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

Installation

npm install @baxcloud/baxmail
# or
pnpm add @baxcloud/baxmail

Requires Node.js 18+. The client connects to BaxCloud automatically — only projectId and apiKey are required.

Quick Start

1import { BaxCloudMailClient } from '@baxcloud/baxmail';
2
3const mail = new BaxCloudMailClient({
4  projectId: process.env.BAXCLOUD_PROJECT_ID!,
5  apiKey: process.env.BAXCLOUD_API_KEY!,
6});
7
8await mail.sendEmail({
9  to: 'user@example.com',
10  subject: 'Welcome to MyApp',
11  html: '<h1>Thanks for signing up!</h1>',
12  text: 'Thanks for signing up!',
13});

Sender address (from / fromName)

By default, BaxMail uses the default sender configured in Dashboard → BaxMail → Setup. Override per message when needed:

1await mail.sendEmail({
2  to: 'user@example.com',
3  subject: 'Your receipt',
4  html: '<p>Order #1234 confirmed.</p>',
5  from: 'noreply@your-verified-domain.com', // must be on a verified domain
6  fromName: 'My App',                        // display name in the inbox
7  replyTo: 'support@your-verified-domain.com',
8});

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

Verified sending domain

When your project has multiple verified domains, pass sendingDomain to pick which domain to send from (without specifying the full from address). BaxMail uses your project's default local-part, e.g. noreply@that-domain.com.

1await mail.sendEmail({
2  to: 'user@example.com',
3  subject: 'Brand B update',
4  html: '<p>Hello</p>',
5  sendingDomain: 'brand-b.com',
6  fromName: 'Brand B',
7});
8
9// Or set a client default:
10const mail = new BaxCloudMailClient({
11  projectId: '...',
12  apiKey: '...',
13  sendingDomain: 'yourdomain.com',
14});

Sent as the X-BaxMail-Domain header. When omitted, the default verified domain from BaxMail Setup is used.

Configuration

Option	Required	Description
projectId	Yes	BaxCloud project ID
apiKey	Yes	API key with BaxMail enabled
sendingDomain	No	Default verified domain for all sends
timeout	No	Request timeout in ms (default 30000)
debug	No	Log requests to console

API Methods

Method	Description
sendEmail	Send email (optional from, fromName, sendingDomain)
getStats	Sent / delivered / failed counts
listLogs	Paginated delivery logs

Parse Server

For Parse Server email verification and password reset, install @baxcloud/parse-server-baxmail — not a copy-paste adapter file.

npm install @baxcloud/parse-server-baxmail

Full setup: Parse Server SDK guide

Error codes

Failed BaxMail API calls return a structured JSON envelope. Use error.code for programmatic handling and error.details.helpUrl to link users to the right dashboard page.

{
  "success": false,
  "error": {
    "code": "BAXVERIFY_FEATURE_DISABLED",
    "message": "BaxVerify is not enabled for this project. Enable it under Project → Features.",
    "details": {
      "projectId": "your-project-id",
      "helpUrl": "https://baxcloud.tech/dashboard/projects/your-project-id?tab=features",
      "docsUrl": "https://baxcloud.tech/docs/baxverify"
    }
  },
  "timestamp": "2026-06-06T12:00:00.000Z",
  "path": "/v1/auth/sms/send"
}

Code	HTTP	Message	What to do
BAXMAIL_FEATURE_DISABLED	403	BaxMail is not enabled for this project.	Enable BaxMail under Project → Features (details.helpUrl).
BAXMAIL_PLAN_NOT_INCLUDED	403	Your plan does not include BaxMail.	Upgrade your subscription (details.helpUrl → Billing).
BAXMAIL_API_KEY_SCOPE	403	API key lacks BaxMail scope.	Create or edit an API key with BaxMail enabled.
BAXMAIL_SENDER_NOT_CONFIGURED	400	No sender email configured.	Verify a domain and set a default from address in BaxMail Setup (details.helpUrl).
BAXMAIL_DOMAIN_NOT_VERIFIED	403	Sending domain is not verified.	Add DNS records and verify the domain in BaxMail Setup (details.helpUrl).
BAXMAIL_PROVIDER_NOT_CONFIGURED	400	Email provider is not configured on the platform.	Contact BaxCloud support.
BAXMAIL_SEND_FAILED	400	Failed to send email.	Check domain verification, from address, and recipient.
BAXMAIL_RECIPIENT_SUPPRESSED	400	Recipient is suppressed after a hard bounce.	Do not send to this address, or remove it from the project suppression list.
BAXMAIL_PROJECT_INACTIVE	403	Project is not active.	Reactivate the project in the dashboard.
BAXMAIL_PROJECT_HEADER_REQUIRED	400	X-Project-Id header is required.	Send X-Project-Id with every request.
BAXMAIL_API_KEY_PROJECT_MISMATCH	403	API key does not belong to this project.	Use an API key created for the same project as X-Project-Id.

1import { BaxMailError } from '@baxcloud/baxmail';
2
3try {
4  await mail.sendEmail({ to: 'user@example.com', subject: 'Hi', html: '<p>Hi</p>' });
5} catch (err) {
6  if (err instanceof BaxMailError) {
7    switch (err.code) {
8      case 'BAXMAIL_DOMAIN_NOT_VERIFIED':
9        // err.details?.helpUrl → BaxMail Setup
10        break;
11      case 'BAXMAIL_SENDER_NOT_CONFIGURED':
12        // Set default from in BaxMail Setup
13        break;
14      default:
15        console.error(err.statusCode, err.code, err.message);
16    }
17  }
18}

REST API reference: BaxMail docs