{"id":16109,"library":"mailersend","title":"MailerSend Node.js SDK","description":"The MailerSend Node.js SDK provides a comprehensive programmatic interface for interacting with the MailerSend API, enabling developers to efficiently send transactional and marketing emails, manage SMS campaigns, configure domains, set up webhooks, utilize templates, and track analytics data. The current stable version is `2.8.0`, released with a consistent and active development cadence, typically seeing updates monthly or bi-monthly. This commitment ensures the library remains up-to-date with API changes and introduces new features regularly. Key differentiators include its focus on high email deliverability, an intuitive API design that simplifies complex email operations, and built-in integrations for streamlined workflows. The SDK fully supports both email and SMS functionalities and ships with comprehensive TypeScript types, enhancing developer experience through improved type safety and autocompletion.","status":"active","version":"2.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/mailersend/mailersend-nodejs","tags":["javascript","mailersend","mailersend-ts","mailer_send","smtp-sender","email-sender","email-api","transactional-emails","transactional-sms","typescript"],"install":[{"cmd":"npm install mailersend","lang":"bash","label":"npm"},{"cmd":"yarn add mailersend","lang":"bash","label":"yarn"},{"cmd":"pnpm add mailersend","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary client class for interacting with the MailerSend API is a named export. Ensure you use named imports.","wrong":"import MailerSend from 'mailersend'; // Not a default export\nconst MailerSend = require('mailersend'); // CommonJS import in ESM context","symbol":"MailerSend","correct":"import { MailerSend } from 'mailersend';"},{"note":"Used for constructing the payload for sending emails, including recipients, subject, HTML/text content, and attachments.","wrong":"const { EmailParams } = require('mailersend'); // CommonJS import","symbol":"EmailParams","correct":"import { EmailParams } from 'mailersend';"},{"note":"Utility class for defining the sender's email address and name. Other utility classes like `Recipient` and `Attachment` are imported similarly.","symbol":"Sender","correct":"import { Sender } from 'mailersend';"}],"quickstart":{"code":"import { MailerSend, EmailParams, Sender, Recipient } from 'mailersend';\nimport * as dotenv from 'dotenv';\n\ndotenv.config();\n\nconst MAIL_FROM_ADDRESS = process.env.MAIL_FROM_ADDRESS || 'info@yourdomain.com';\nconst MAIL_FROM_NAME = process.env.MAIL_FROM_NAME || 'Your Company Name';\nconst MAIL_TO_ADDRESS = process.env.MAIL_TO_ADDRESS || 'recipient@example.com';\nconst MAIL_TO_NAME = process.env.MAIL_TO_NAME || 'Recipient Name';\n\nconst mailerSend = new MailerSend({\n  apiKey: process.env.MAILERSEND_API_TOKEN || '',\n});\n\nif (!process.env.MAILERSEND_API_TOKEN) {\n  console.error('Error: MAILERSEND_API_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\nasync function sendTestEmail() {\n  const sender = new Sender(MAIL_FROM_ADDRESS, MAIL_FROM_NAME);\n  const recipients = [new Recipient(MAIL_TO_ADDRESS, MAIL_TO_NAME)];\n\n  const emailParams = new EmailParams()\n    .setFrom(sender)\n    .setTo(recipients)\n    .setReplyTo(sender)\n    .setSubject('MailerSend Node.js SDK Test Email')\n    .setHtml('<strong>This is an automated test email from MailerSend Node.js SDK!</strong>')\n    .setText('This is an automated test email from MailerSend Node.js SDK!');\n\n  try {\n    const response = await mailerSend.email.send(emailParams);\n    console.log('Email sent successfully:', response.body);\n  } catch (error: any) {\n    console.error('Error sending email:', error.response?.body || error.message);\n  }\n}\n\nsendTestEmail();\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the MailerSend client and send a basic HTML email using environment variables for configuration. It covers setting up sender and recipient details and handling potential errors."},"warnings":[{"fix":"Consult the MailerSend V2 documentation for updated API methods and class structures. The project README explicitly links to the V1 documentation for reference during migration.","message":"The SDK underwent significant breaking changes between v1 and v2. Applications built with v1 will require code modifications to work with v2 and newer versions. Refer to the specific V1 documentation if you are migrating or maintaining an older application.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Review the MailerSend API documentation for the current recommended approach to email personalization, which typically involves using `setPersonalization` on `EmailParams` with an array of objects.","message":"The method for 'simple personalization' was removed in version 2.3.0. This might affect how dynamic data is injected into email templates if previous methods were used.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"Always use environment variables (e.g., `process.env.MAILERSEND_API_TOKEN`), a secrets manager, or a `.env` file (for local development) to manage your API key securely. Do not hardcode or commit API keys.","message":"The MailerSend SDK relies on an API token for authentication. Storing this directly in code or committing it to version control is a security risk. API tokens have full access to your MailerSend account.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use a named import for the `MailerSend` class: `import { MailerSend } from 'mailersend';`","cause":"Attempting to import `MailerSend` as a default export (`import MailerSend from 'mailersend'`) or using CommonJS `require` in an ESM context.","error":"TypeError: MailerSend is not a constructor"},{"fix":"Verify that your `MAILERSEND_API_TOKEN` environment variable (or wherever you've configured it) is correctly set to a valid MailerSend API key with the necessary permissions to send emails. Ensure there are no typos or leading/trailing spaces.","cause":"The provided API token is invalid, missing, or has insufficient permissions.","error":"Error sending email: { \"message\": \"Unauthenticated.\" }"},{"fix":"Ensure that all mandatory fields are set on your `EmailParams` instance. For example, `emailParams.setFrom(sender)`, `emailParams.setTo(recipients)`, and `emailParams.setSubject('...')` must be called with valid data.","cause":"Required email parameters, such as 'from', 'to', or 'subject', were not provided or were invalid when constructing the `EmailParams` object.","error":"Error sending email: { \"message\": \"The given data was invalid.\", \"errors\": { \"from\": [ \"The from field is required.\" ] } }"}],"ecosystem":"npm"}