REST API Reference
JavaScript & TypeScript SDK
Install the official zero-dependency MailSend SDK for TypeScript, JavaScript, Node.js, Bun, Next.js, TanStack Start, and Cloudflare Workers.
Docs Summary
- What this page explains: Installing and using the official mailsend package from server-side JavaScript runtimes.
- Who should use it: Software engineers writing backend code integrations.
- Related MailSend feature: TypeScript types, safe retries, idempotency, and typed API errors
- Common use cases: Programmatic notifications, backend alerts
- Related docs: Email API, Webhooks, Introduction
The official package is mailsend. It is ESM-native, requires Node.js 18 or a compatible server runtime, includes TypeScript declarations, and has zero runtime dependencies.
Install
npm
npm install mailsendpnpm
pnpm add mailsendYarn
yarn add mailsendBun
bun add mailsendMAILSEND_API_KEY is a server-only secret. Never expose it in browser bundles, client components, NEXT_PUBLIC_* variables, mobile apps, or static websites.
Quick starttypescript
import { MailSend } from "mailsend";
const mailsend = new MailSend(process.env.MAILSEND_API_KEY!);
const email = await mailsend.emails.send({
from: "Acme <[email protected]>",
to: "[email protected]",
subject: "Welcome to Acme",
html: "<h1>Welcome!</h1><p>We're glad you're here.</p>",
});
console.log(email.id, email.status); // queuedAvailable methods
| Method | Purpose | API scope |
|---|---|---|
| mailsend.emails.send(payload, options?) | Queue one email with automatic idempotency and bounded retries. | emails:send |
| mailsend.emails.sendBatch(emails, options?) | Queue 1–100 independently validated emails. | emails:send |
| mailsend.emails.get(id, options?) | Retrieve message and recipient delivery state. | emails:read |
Safe error handlingtypescript
import { MailSend, RateLimitError, ValidationError } from "mailsend";
try {
await mailsend.emails.send(payload);
} catch (error) {
if (error instanceof RateLimitError) {
console.log("Retry after", error.retryAfter, "seconds");
} else if (error instanceof ValidationError) {
console.log(error.code, error.message, error.requestId);
}
}