Skip to main content
OverviewGetting StartedAPI ReferencePlaygroundGuidesSDKsSMTPFAQ
Docs/SDKs/Node.js

Node.js SDK

Full TypeScript support, automatic retries, and promise-based API for SendMesh.

SDK packages will be published to npm soon. The API below shows the interface you can expect. Use the REST API directly in the meantime.

Installation

bash
npm install @sendmesh/node

Requires Node.js 18+ and TypeScript 5.0+ (optional but recommended).

Initialization

typescript
import { SendMesh } from '@sendmesh/node';

const sendmesh = new SendMesh({
  apiKey: 'sk_live_your_secret_key',
  // Optional configuration:
  baseUrl: 'https://api.sendmesh.co',  // default
  timeout: 30000,                        // request timeout in ms
  retries: 3,                            // automatic retries on 5xx
});

Error Handling

typescript
import { SendMesh, SendMeshError } from '@sendmesh/node';

try {
  await sendmesh.emails.send({ /* ... */ });
} catch (err) {
  if (err instanceof SendMeshError) {
    console.error('Code:', err.code);       // e.g. 'VALIDATION_ERROR'
    console.error('Message:', err.message);
    console.error('Status:', err.statusCode); // e.g. 400
    console.error('Details:', err.details);   // field-level errors
  }
}

Method Reference

POSTemails.send()

Send a single email to one or more recipients.

Parameters
typescript
{
  from: { email: string; name?: string };
  to: { email: string; name?: string }[];
  subject: string;
  html?: string;
  text?: string;
  replyTo?: string;
  tags?: string[];
  metadata?: Record<string, string>;
  templateId?: string;
  templateData?: Record<string, unknown>;
}
Returns
typescript
Promise<{
  data: {
    id: string;
    status: 'queued' | 'sent' | 'delivered';
    from: string;
    to: string[];
    subject: string;
    createdAt: string;
  };
}>
Example
typescript
const { data } = await sendmesh.emails.send({
  from: { email: 'hello@yourdomain.com', name: 'Your App' },
  to: [{ email: 'user@example.com', name: 'Jane Doe' }],
  subject: 'Welcome to Our App!',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  tags: ['welcome', 'transactional'],
});

console.log('Email ID:', data.id); // em_abc123def456
POSTemails.batch()

Send up to 1,000 emails in a single batch request.

Parameters
typescript
{
  from: { email: string; name?: string };
  messages: {
    to: { email: string; name?: string }[];
    subject: string;
    html?: string;
    text?: string;
    tags?: string[];
  }[];
}
Returns
typescript
Promise<{
  data: {
    batchId: string;
    queued: number;
    failed: number;
    emails: { id: string; to: string; status: string }[];
  };
}>
Example
typescript
const { data } = await sendmesh.emails.batch({
  from: { email: 'hello@yourdomain.com' },
  messages: [
    { to: [{ email: 'user1@example.com' }], subject: 'Hello 1', html: '<p>Hi 1</p>' },
    { to: [{ email: 'user2@example.com' }], subject: 'Hello 2', html: '<p>Hi 2</p>' },
  ],
});

console.log('Batch ID:', data.batchId);
console.log('Queued:', data.queued);
GETemails.list()

List sent emails with filtering and cursor-based pagination.

Parameters
typescript
{
  cursor?: string;
  limit?: number;    // default 20, max 100
  status?: 'queued' | 'sent' | 'delivered' | 'bounced' | 'failed';
  from?: string;     // ISO date
  to?: string;       // ISO date
}
Returns
typescript
Promise<{
  data: EmailSummary[];
  meta: { total: number; cursor: string | null; hasMore: boolean };
}>
Example
typescript
const { data, meta } = await sendmesh.emails.list({
  limit: 50,
  status: 'delivered',
});

for (const email of data) {
  console.log(email.id, email.subject, email.status);
}

if (meta.hasMore) {
  const next = await sendmesh.emails.list({ cursor: meta.cursor });
}
GETemails.get()

Retrieve details of a specific email including delivery events.

Parameters
typescript
emailId: string
Returns
typescript
Promise<{
  data: {
    id: string;
    from: string;
    to: string[];
    subject: string;
    status: string;
    events: { type: string; timestamp: string }[];
    createdAt: string;
  };
}>
Example
typescript
const { data } = await sendmesh.emails.get('em_abc123def456');

console.log('Status:', data.status);
for (const event of data.events) {
  console.log(event.type, event.timestamp);
}

GitHub Repository

View source, report issues, and contribute.

View Repository

Other SDKs

Also available for Python and PHP.

Python PHP