MailerSend Node.js SDK

Common errors

• TypeError: MailerSend is not a constructor

  cause Attempting to import `MailerSend` as a default export (`import MailerSend from 'mailersend'`) or using CommonJS `require` in an ESM context.
  fix Use a named import for the `MailerSend` class: `import { MailerSend } from 'mailersend';`

• Error sending email: { "message": "Unauthenticated." }

  cause The provided API token is invalid, missing, or has insufficient permissions.
  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.

• Error sending email: { "message": "The given data was invalid.", "errors": { "from": [ "The from field is required." ] } }

  cause Required email parameters, such as 'from', 'to', or 'subject', were not provided or were invalid when constructing the `EmailParams` object.
  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.

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install mailersend npm
• yarn add mailersend yarn
• pnpm add mailersend pnpm

Imports

• MailerSend
  wrong:

  import MailerSend from 'mailersend'; // Not a default export
  const MailerSend = require('mailersend'); // CommonJS import in ESM context

  correct:

  import { MailerSend } from 'mailersend';

  The primary client class for interacting with the MailerSend API is a named export. Ensure you use named imports.
• EmailParams
  wrong:

  const { EmailParams } = require('mailersend'); // CommonJS import

  correct:

  import { EmailParams } from 'mailersend';

  Used for constructing the payload for sending emails, including recipients, subject, HTML/text content, and attachments.
• Sender

  import { Sender } from 'mailersend';

  Utility class for defining the sender's email address and name. Other utility classes like `Recipient` and `Attachment` are imported similarly.

Quickstart

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.

import { MailerSend, EmailParams, Sender, Recipient } from 'mailersend';
import * as dotenv from 'dotenv';

dotenv.config();

const MAIL_FROM_ADDRESS = process.env.MAIL_FROM_ADDRESS || 'info@yourdomain.com';
const MAIL_FROM_NAME = process.env.MAIL_FROM_NAME || 'Your Company Name';
const MAIL_TO_ADDRESS = process.env.MAIL_TO_ADDRESS || 'recipient@example.com';
const MAIL_TO_NAME = process.env.MAIL_TO_NAME || 'Recipient Name';

const mailerSend = new MailerSend({
  apiKey: process.env.MAILERSEND_API_TOKEN || '',
});

if (!process.env.MAILERSEND_API_TOKEN) {
  console.error('Error: MAILERSEND_API_TOKEN environment variable is not set.');
  process.exit(1);
}

async function sendTestEmail() {
  const sender = new Sender(MAIL_FROM_ADDRESS, MAIL_FROM_NAME);
  const recipients = [new Recipient(MAIL_TO_ADDRESS, MAIL_TO_NAME)];

  const emailParams = new EmailParams()
    .setFrom(sender)
    .setTo(recipients)
    .setReplyTo(sender)
    .setSubject('MailerSend Node.js SDK Test Email')
    .setHtml('<strong>This is an automated test email from MailerSend Node.js SDK!</strong>')
    .setText('This is an automated test email from MailerSend Node.js SDK!');

  try {
    const response = await mailerSend.email.send(emailParams);
    console.log('Email sent successfully:', response.body);
  } catch (error: any) {
    console.error('Error sending email:', error.response?.body || error.message);
  }
}

sendTestEmail();