MailerSend Node.js SDK

The email list endpoint uses page and limit for pagination. To walk the entire result set, you must request the next page until links.next is null.

Important Rules:

• Every request must repeat domain_id, date_from, date_to, and any other filters alongside the page parameter. Dropping any of these returns a 422 error.
• Keep the limit constant throughout the entire walk to prevent page boundaries from shifting.
• links.last is always null; do not attempt to calculate the total page count upfront. Use links.next to determine if more data exists.
• meta provides current_page, current_page_url, from, path, per_page, and to, but does not include total or last_page.

import 'dotenv/config';
import { MailerSend } from "mailersend";

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

const queryParams = {
  domain_id: "domain_id",
  date_from: 1443651141,
  date_to: 1443661141,
  limit: 100,
};

let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await mailerSend.email.list({ ...queryParams, page });

  response.body.data.forEach((email) => console.log(email.id, email.status, email.subject));

  hasMore = response.body.links.next !== null;
  page++;
}

Inbound email handling uses filters to match or catch emails based on specific criteria.

InboundFilterType

Used to specify what part of the email to filter on:

• catch_all
• catch_recipient
• match_all
• match_sender
• match_domain
• match_header

ComparerType

Used to define the logic for the filter comparison:

• equal
• not-equal
• contains
• not-contains
• starts-with
• ends-with
• not-starts-with
• not-ends-with

Filter Structures

• InboundFilter: A basic filter with a comparer and a value.
• MatchInboundFilter: An extension of InboundFilter that includes an optional key (useful for matching specific headers).
• CatchFilter: A filter using an InboundFilterType and an optional array of InboundFilter objects.
• MatchFilter: A filter using an InboundFilterType and an optional array of MatchInboundFilter objects.

To send an email at a later time, use .setSendAt(timestampOrIsoString). This method accepts either a Unix timestamp (integer) or an ISO 8601 date string.

import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";

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

const sentFrom = new Sender("you@yourdomain.com", "Your name");

const recipients = [
  new Recipient("your@client.com", "Your Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setReplyTo(sentFrom)
  .setSubject("This is a scheduled Subject")
  .setHtml("<strong>This is a scheduled HTML content</strong>")
  .setText("This is a scheduled text content")
  // Accepts a Unix timestamp (integer) or an ISO 8601 date string
  .setSendAt(Math.floor((new Date(Date.now() + 30 * 60 * 1000)).getTime() / 1000)); // Unix timestamp – send in 30 mins
  // .setSendAt("2040-11-21T14:00:00+00:00"); // ISO 8601 alternative

await mailerSend.email.send(emailParams);

Note: The references field is available on paid plan accounts only.

To enable email threading, use .setInReplyTo(messageId) and .setReferences([messageId1, messageId2]) on EmailParams.

import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";

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

const sentFrom = new Sender("you@yourdomain.com", "Your name");

const recipients = [
  new Recipient("your@client.com", "Your Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setReplyTo(sentFrom)
  .setSubject("Re: This is a Subject")
  .setHtml("<strong>This is the HTML content</strong>")
  .setText("This is the text content")
  .setInReplyTo("<original-message-id@yourdomain.com>")
  .setReferences([
    "<original-message-id@yourdomain.com>",
    "<another-message-id@yourdomain.com>",
  ]);

await mailerSend.email.send(emailParams);

To attach files, create an array of Attachment objects and pass them to .setAttachments(attachments). The Attachment constructor requires the file content as a base64 encoded string, the filename, and the attachment type (e.g., 'attachment' or 'inline').

import 'dotenv/config';
import fs from "fs";
import { MailerSend, EmailParams, Sender, Recipient, Attachment } from "mailersend";

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

const sentFrom = new Sender("you@yourdomain.com", "Your name");

const recipients = [
  new Recipient("your@client.com", "Your Client")
];

const attachments = [
  new Attachment(
    fs.readFileSync('/path/to/file.pdf', { encoding: 'base64' }),
    'file.pdf',
    'attachment'
  )
]

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setReplyTo(sentFrom)
  .setAttachments(attachments)
  .setSubject("This is a Subject")
  .setHtml("<strong>This is the HTML content</strong>")
  .setText("This is the text content");

await mailerSend.email.send(emailParams);