mailersend-nodejs

MailerSend is the official Node.js and TypeScript SDK for the MailerSend transactional messaging platform, providing a fully typed client for sending email, SMS, and WhatsApp messages, verifying email addresses, and monitoring deliverability. It wraps every documented MailerSend REST endpoint — email sending and scheduling, domain and webhook management, activity and analytics reporting, SMTP users, DMARC and blocklist monitoring — behind a single MailerSend client instance with per-resource sub-modules.

Built with TypeScript from the ground up and backed by a Jest test suite that mocks the MailerSend API with nock, the SDK targets teams already using MailerSend for deliverability who want a typed, promise-based interface instead of hand-rolled HTTP calls. It is actively maintained by MailerSend itself, with dozens of releases and consistent monthly commit activity.

What You Get

• A single MailerSend client exposing typed sub-modules for email, SMS, WhatsApp, tokens, users, DMARC, and blocklist monitoring
• Builder-style parameter classes (EmailParams, Recipient, Sender) for constructing requests with method chaining
• Full coverage of MailerSend’s v1 and v2 REST endpoints, including bulk email, scheduled sends, and email verification
• First-class TypeScript typings shipped from lib/index.d.ts for autocomplete and compile-time safety
• A documented webhook-signature verification utility for validating inbound MailerSend webhook payloads

Common Use Cases

• Sending transactional emails (password resets, receipts, notifications) from a Node.js backend with CC/BCC, attachments, and template support
• Sending and personalizing bulk SMS or WhatsApp messages to customer lists
• Verifying email addresses in bulk before a marketing send to protect sender reputation
• Managing sending domains, DNS records, and webhooks programmatically as part of an onboarding flow
• Monitoring DMARC reports and blocklist status for a sending domain from CI or a scheduled job

Under The Hood

Architecture The SDK is organized as a facade (MailerSend) that instantiates per-resource sub-modules (EmailModule, SMSModule, TokenModule, UserModule, DmarcModule, BlocklistMonitorModule, WhatsAppModule, OthersModule, EmailVerificationModule), each extending a shared RequestService base class that wraps the gaxios HTTP client with bearer-token authentication. EmailModule further delegates to nested sub-modules (Activity, Analytics, Domain, Inbound, Message, Schedule, Recipient, Template, Webhook, Identity, SmtpUser) mirroring MailerSend’s own API routing tree. Request data flows through builder-pattern parameter classes (EmailParams, Recipient, Sender) that accumulate state via chained setters before RequestService.request() serializes the body and query string (via qs) and issues the call, normalizing headers and re-throwing structured {headers, body, statusCode} errors on failure. It is a clean, shallow layered structure with no dependency-injection framework — every module simply takes (apiKey, baseUrl) — so a change to RequestService would ripple through every module, but the surface area of that class is small and stable.

Tech Stack The codebase is 100% TypeScript, compiled with tsc per tsconfig.json and published as CommonJS plus .d.ts typings under lib/. Runtime dependencies are deliberately minimal: gaxios (a fetch-based HTTP client) for requests and qs for query-string serialization — there is no web framework or ORM since this is purely an outbound API client. Development tooling includes Jest with ts-jest for running TypeScript tests, nock for HTTP mocking, Prettier for formatting, and dotenv for loading credentials in the example scripts. GitHub Actions workflows run CI, and renovate.json keeps dependencies current automatically.

Code Quality Nineteen test files under src/__tests__/modules use nock to mock MailerSend’s HTTP responses, giving close to one test file per module (Email, SMS, Token, User, Dmarc, BlocklistMonitor, Identity, SmtpUser, Domain, Inbound, Schedule, Analytics, Message, Template, Activity, EmailVerification, Recipient, and SMS-specific variants). RequestService re-throws a structured error object on failed requests rather than swallowing errors, and TypeScript provides static typing throughout, though a handful of any types (in query-parameter and header handling) slightly loosen strictness. Inline code comments are sparse — the SDK leans on TypeScript signatures, the extensive README, and the examples/ directory rather than docblocks for documentation. Tests run via GitHub Actions CI on every change.

API Design The public API is highly ergonomic: a single new MailerSend({apiKey}) call exposes intuitively named sub-clients (.email, .sms, .whatsapp, .token, .user, .dmarc, .blocklistMonitor) that mirror MailerSend’s own product surface, and fluent builder classes (EmailParams().setFrom().setTo().setSubject().setHtml()) reduce the common send-email case to a handful of chained calls. The README documents essentially every endpoint with copy-pasteable examples, and a large parallel examples/ directory ships runnable scripts organized by API version (v1/v2) and resource. Naming is consistent across modules (list/single/create/update/delete), which lowers the learning curve for anyone who has used one resource to use another — though the design itself is a conventional REST-wrapping SDK rather than a novel abstraction.