Node.js SDK

The HiSend Node.js SDK (@hisend/sdk) provides a convenient wrapper around our REST APIs, fully typed with TypeScript. It's the recommended way to integrate HiSend into your backend or serverless environments.

Installation

You can install the SDK using any Node package manager. We recommend bun or npm:

bun add @hisend/sdk

Initialization

Import the client and initialize it using the API Key generated in your project dashboard.

import { Hisend } from '@hisend/sdk';

const hisend = new Hisend({ apiKey: 'YOUR_API_KEY' });

Resources

The SDK is divided into resources, each handling a specific domain of the API.

Emails (`hisend.emails`)

The emails resource handles sending messages and fetching sent/received history.

`send(data: SendEmailRequest)`

Sends a single email.

const result = await hisend.emails.send({
  from: "noreply@yourdomain.com",
  to: ["user@example.com"],
  // Optional:
  cc: ["team@yourdomain.com"],
  bcc: ["hidden@yourdomain.com"],
  subject: "Welcome to HiSend!",
  html: "<h1>Welcome!</h1><p>We are glad to have you.</p>",
  text: "Welcome! We are glad to have you.",
  in_reply_to: "<original-message-id@domain.com>", // For threading replies
  attachments: [
    {
       filename: "invoice.pdf",
       content: "JVBERi0xLjcKCjEgMCBvYmog...", // Base64 encoded
       content_type: "application/pdf"
    }
  ]
});

`sendBatch(data: SendEmailRequest[])`

Sends multiple emails in a single API request, useful for bulk messaging/newsletters.

const batch = {
  requests: [
    { from: "sales@test.com", to: ["a@test.com"], subject: "A", html: "A" },
    { from: "sales@test.com", to: ["b@test.com"], subject: "B", html: "B" }
  ]
};
const result = await hisend.emails.sendBatch(batch);

`list()`

Returns a list of all emails (inbound and outbound) belonging to your project.

const emails = await hisend.emails.list();
console.log(`You have ${emails.length} emails.`);

`get(id: number)`

Retrieves the details of a specific email by its ID.

const email = await hisend.emails.get(1234);
console.log(email.subject);

Threads (`hisend.threads`)

The threads resource handles email conversations, grouping inbound and outbound replies into manageable topics.

`list()`

Returns all conversation threads for your project, ordered by the latest message time.

const threads = await hisend.threads.list();
console.log(`Active threads: ${threads.length}`);

`getEmails(id: number)`

Returns all individual emails that belong to a specific Thread ID, in chronological order.

const emailsInThread = await hisend.threads.getEmails(849);
emailsInThread.forEach(msg => {
  console.log(`${msg.from}: ${msg.text_body}`);
});

Domains (`hisend.domains`)

The domains resource manages the sender domains authorized for your project.

`list()`

Returns all domains registered to your project along with their verification statuses.

const domains = await hisend.domains.list();

`get(id: number)`

Retrieves the details and verification status of a specific domain by its ID.

const domain = await hisend.domains.get(101);

`add(data: AddDomainRequest)`

Registers a new domain to your project. Note that it will remain pending until you verify its DNS records.

const domain = await hisend.domains.add({ name: "newsletter.example.com" });

`verify(id: number)`

Triggers a manual DNS check to verify if the required records (MX, TXT, CNAME) have been added to your registrar.

const result = await hisend.domains.verify(domain.id);
console.log(`Verification status: ${result.status}`);

`delete(id: number)`

Removes a domain from your project.

await hisend.domains.delete(domain.id);

Routing (`hisend.routing`)

The routing resource manages how inbound emails are processed, allowing for Catch-All or exact-address routing to webhooks or list forwarding.

`list(domainId: number)`

Returns all inbound email routing rules configured for a specific domain.

const routes = await hisend.routing.list(domainId);

`get(domainId: number, id: number)`

Returns the details of a specific routing rule.

const route = await hisend.routing.get(domainId, routeId);

`create(domainId: number, data: CreateRoutingRequest)`

Creates a new routing rule on a specific domain.

const rule = await hisend.routing.create(domainId, {
    type: "specific_address",
    email_address: "support@yourdomain.com",
    endpoint_ids: [102, 103] // IDs of Endpoints to trigger
});

`update(domainId: number, id: number, data: UpdateRoutingRequest)`

Updates an existing routing rule on a specific domain.

const updatedRule = await hisend.routing.update(domainId, rule.id, {
    endpoint_ids: [102] // Removed endpoint 103
});

`delete(domainId: number, id: number)`

Deletes an existing inbound routing rule.

await hisend.routing.delete(domainId, rule.id);

Error Handling

All methods in the SDK throw standard Error objects containing the HTTP status details if the request is rejected (e.g., HTTP 401 Unauthorized or HTTP 400 Bad Request). We recommend wrapping API calls in try/catch blocks:

try {
  await hisend.emails.send({ /* ... */ });
} catch (error) {
  console.error("Failed to send email:", error.message);
}

Node.js SDK

On this page