Lettermint Node.js SDK

The official Node.js SDK for Lettermint.

Installation

npm install lettermint

Usage

Sending Emails

Use a project sending token with Lettermint.email(...). Sending tokens authenticate with the x-lettermint-token header.

import{Lettermint}from"lettermint";constemail=Lettermint.email(process.env.LETTERMINT_SENDING_TOKEN!);

The SDK provides a fluent interface for sending emails:

constresponse=awaitemail.from('sender@acme.com').to('recipient@acme.com').subject('Hello from Lettermint').text('This is a test email sent using the Lettermint Node.js SDK.').send();console.log(`Email sent with ID: ${response.message_id}`);console.log(`Status: ${response.status}`);

Advanced Email Options

constresponse=awaitemail.from('John Doe <sender@acme.com>').to('recipient1@acme.com','recipient2@acme.com').cc('cc@acme.com').bcc('bcc@acme.com').replyTo('reply@acme.com').subject('Hello from Lettermint').html('<h1>Hello</h1><p>This is an HTML email.</p>').text('This is a plain text version of the email.').headers({'X-Custom-Header': 'Custom Value',}).attach('attachment.txt',Buffer.from('Hello World').toString('base64')).attach('logo.png',Buffer.from('...').toString('base64'),'logo')// Inline attachment.idempotencyKey('unique-id-123').metadata({foo: 'bar',}).tag('campaign-123').send();

The legacy constructor still works for sending-only usage:

constlettermint=newLettermint({apiToken: 'your-sending-token'});awaitlettermint.email.from('sender@acme.com').to('recipient@acme.com').subject('Hello').send();

Batch Sending

constresponse=awaitemail.sendBatch([{from: 'sender@acme.com',to: ['recipient@acme.com'],subject: 'Hello from Lettermint',text: 'This is a batch email.',},]);

Team API

Use a team API token with Lettermint.api(...). API tokens authenticate with Authorization: Bearer ... and are separate from project sending tokens.

constapi=Lettermint.api(process.env.LETTERMINT_API_TOKEN!);constdomains=awaitapi.domains.list({'page[size]': '10'});constproject=awaitapi.projects.create({name: 'Production',smtp_enabled: true,});conststats=awaitapi.stats.retrieve({start: '2026-01-01',end: '2026-01-31',});constmessageHtml=awaitapi.messages.html('message-id');

Both API surfaces support ping():

awaitemail.ping();awaitapi.ping();

API Reference

Lettermint Class

The main entry points for the SDK.

constemail=Lettermint.email('your-sending-token',{baseUrl: 'https://api.lettermint.co/v1',timeout: 30000,});constapi=Lettermint.api('your-api-token',{baseUrl: 'https://api.lettermint.co/v1',timeout: 30000,});

Email Endpoint

Methods for sending emails:

• from(email: string): Set the sender email address
• to(...emails: string[]): Set one or more recipient email addresses
• subject(subject: string): Set the email subject
• html(html: string | null): Set the HTML body of the email
• text(text: string | null): Set the plain text body of the email
• cc(...emails: string[]): Set one or more CC email addresses
• bcc(...emails: string[]): Set one or more BCC email addresses
• replyTo(...emails: string[]): Set one or more Reply-To email addresses
• headers(headers: Record<string, string>): Set custom headers for the email
• attach(filename: string, base64Content: string, content_id?: string): Attach a file to the email. Optional content_id for inline attachments.
• route(route: string): Set the routing key for the email
• idempotencyKey(key: string): Set an idempotency key to prevent duplicate email sends
• metadata(metadata: Record<string, string>): Set metadata for the email
• tag(tag: string): Set a tag for the email
• send(): Send the email and return a promise with the response
• sendBatch(payload): Send multiple email payloads in one request
• ping(): Ping the Sending API and return the raw response body

API Endpoint Groups

The full API client exposes domains, messages, projects, routes, stats, suppressions, team, and webhooks. Request and response types are exported from the package.

License

MIT