mailer-send-ts

Typescript MailerSend library for NodeJS

For official javascript library please visit HERE

For response Body, Headers and Status Codes please visit Official API Docs

Utils

• Webhook verify (Email and SMS)

Supported APIs

Email

• Send an email
• Send bulk emails
• Get bulk email status

Email Webhooks

• List webhooks
• Get a webhook
• Create a webhook
• Update a webhook
• Delete a webhook

Activity

• Get a list of activities

Analytics

• Analytics by date
• Opens by country
• Opens by user-agent name
• Opens by reading environment

Domains

• Get a list of domains
• Get a single domain
• Add domain
• Delete a domain
• Get recipients for a domain
• Update domain settings
• Get DNS Records
• Verify Domain

Inbound routing

• Get a list of inbound routes
• Get a single inbound route
• Add an inbound route
• Update an inbound route
• Delete an inbound route

Messages

• Get a list of messages
• Get info for a single message

Scheduled messages

• Get list of scheduled messages
• Get a single scheduled message
• Delete a scheduled message

Recipients

• Get recipients
• Get a single recipient
• Delete a recipient
• Get recipients from a suppression list
• Add recipients to a suppression list
• Delete recipients from a suppression list
• Hard Bounces
• Spam Complaints
• Unsubscribes

Templates

• Get templates
• Get a single template
• Delete a template

Tokens

• Create a token
• Update a token
• Delete a token

SMS

• Send an SMS

Phone numbers

• Get a list of SMS phone numbers
• Get an SMS phone number
• Update a single SMS phone number
• Delete an SMS phone number

SMS Messages

• Get a list of SMS messages
• Get an SMS message

SMS Activity

• Get a list of activities
• Get activity of a single message

SMS Recipients

• Get a list of SMS recipients
• Get an SMS recipient
• Update a single SMS recipient

SMS Webhooks

• Get a list of SMS webhooks
• Get a single SMS webhook
• Create an SMS webhook
• Update a single SMS webhook
• Delete an SMS webhook

SMS Inbound routing

• Get a list of SMS inbound routes
• Get a single SMS inbound route
• Add an SMS inbound route
• Update an inbound route
• Delete an SMS inbound route

Installation

Setup

npm install mailer-send-ts --S

Usage

Init api key

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

Email

API Documentation

Send an email

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];


const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setSubject("Your subject")
  .setText("Hello world!")
  .setHtml("<b>Hello world!</b>");

const response = await mailerSend.email.send(emailParams);

Add CC, BCC recipients

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];
const recipientsCC = [
  new Recipient("[e-mail]", "Your CC Client")
];
const recipientsBcc = [
  new Recipient("[e-mail]", "Your BCC Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setCc(recipientsCC)
  .setBcc(recipientsBcc)
  .setSubject("Your subject")
  .setText("Hello world!")
  .setHtml("<b>Hello world!</b>");

const response = await mailerSend.email.send(emailParams);

Send a template-based email

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setSubject("Your subject")
  .setTemplateId("your_template_id");

const response = await mailerSend.email.send(emailParams);

Advanced personalization

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];

const personalization = [
  {
    email: "[e-mail]",
    data: {
      test: 'Test Value'
    },
  }
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setSubject("Subject, {{ test }}")
  .setText("This is the text content, {{ test }}")
  .setHtml("This is the HTML content, {{ test }}");

const response = await mailerSend.email.send(emailParams);

Simple personalization

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];

const variables = [
  {
    email: "[e-mail]",
    substitutions: [
      {
        var: 'test',
        value: 'Test Value'
      }
    ],
  }
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setSubject("Subject, {$test}")
  .setHtml("This is the HTML content, {$test}")
  .setText("This is the text content, {$test}");

const response = await mailerSend.email.send(emailParams);

Send email with attachment

const fs = require('fs');
import { MailerSend, EmailParams, Sender, Recipient, Attachment } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];

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

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

mailerSend.email.send(emailParams);

Send bulk emails

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const bulkEmails: EmailParams[] = [];

const sentFrom = new Sender("[e-mail]", "Your name");

const recipients = [
  new Recipient("[e-mail]", "Your Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setSubject("Your subject")
  .setText("Hello world!")
  .setHtml("<b>Hello world!</b>");

bulkEmails.push(emailParams);

const sentFrom2 = new Sender("[e-mail]", "Your name");

const recipients2 = [
  new Recipient("[e-mail]", "Your Client")
];

const emailParams2 = new EmailParams()
  .setFrom(sentFrom2)
  .setTo(recipients2)
  .setSubject("Your subject")
  .setText("Hello world2!")
  .setHtml("<b>Hello world2!</b>");

bulkEmails.push(emailParams2);

const response = await mailerSend.email.sendBulk(bulkEmails);

Get bulk emails status

import { MailerSend, EmailParams, Sender, Recipient } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.email.getBulkStatus("bulk_id_here");

Email Webhooks

API Documentation

Create email webhook

import { MailerSend, EmailWebhook, EmailWebhookEventType } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const params = new EmailWebhook()
  .setUrl("https://test.com/webhook")
  .setName("Webhook Name")
  .setEvents([EmailWebhookEventType.SENT, EmailWebhookEventType.OPENED])
  .setDomainId("test_domain")
  .setEnabled(true);


const response = await mailerSend.email.createWebhook(params);

List email webhooks

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.email.listWebhook("domain_id_here");

Get email webhook

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.email.getWebhook("webhook_id_here");

Update email webhook

import { MailerSend, IEmailWebhookUpdate, EmailWebhookEventType } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const updates: Partial<IEmailWebhookUpdate> = {
  enabled: true,
  url: "https://new-url.com/webhook",
  name: "New name",
  events: [EmailWebhookEventType.CLICKED]
}

const response = await mailerSend.email.updateWebhook("webhook_id_here", updates);

Delete email webhook

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.email.deleteWebhook("webhook_id_here");

Activity

API Documentation

Get a list of activities

import { ActivityEventType, ActivityQueryParams, MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: ActivityQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  date_from: 1443651141, // Format: 1443651141
  date_to: 1443651141, // Format: 1443651141
  event: [ActivityEventType.SENT, ActivityEventType.SOFT_BOUNCED, ...]
}

// Query params are not required
const activities = await mailerSend.activity.domain("your_domain_id", queryParams);

Messages

API Documentation

Get a list of messages

import { MailerSend, MessageQueryParams } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: MessageQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2
}

// Query params are not required
const messages = await mailerSend.message.list(queryParams);

Get single message

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const message = await mailerSend.message.single("your_message_id");

Domains

API Documentation

Create domain

import { MailerSend, Domain } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const domain = new Domain("mydomain.com", "rp_subdomain", "ct_subdomain", "ir_subdomain");

const response = await mailerSend.domain.create(domain);

Get a list of domains

import { MailerSend, DomainQueryParams } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: DomainQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  verified: true // Not required
}
// Query params are not required
const domains = await mailerSend.domain.list(queryParams);

Get a single domain

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const domain = await mailerSend.domain.single("your_domain_id");

Get recipients for a domain

import { MailerSend, DomainRecipientsQueryParams } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: DomainRecipientsQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2
}

// Query params are not required
const recipients = await mailerSend.domain.recipients("your_domain_id", queryParams);

Delete a domain

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.domain.delete("your_domain_id");

Update domain settings

import { MailerSend, DomainSettings } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const domainUpdates: DomainSettings = {
  send_paused: true,
  track_clicks: true,
  track_opens: true,
  track_unsubscribe: true,
  track_unsubscribe_html: "<p>Click here to <a href=\"{$unsubscribe}\">unsubscribe<\/a><\/p>",
  track_unsubscribe_plain: "Click here to unsubscribe: {$unsubscribe}",
  track_content: true,
  custom_tracking_enabled: true,
  custom_tracking_subdomain: "email"
}

const response = await mailerSend.domain.updateSettings("your_domain_id", domainUpdates);

Get DNS Records

import { MailerSend, DomainSettings } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const dns = await mailerSend.domain.dns("your_domain_id");

Verify a domain

import { MailerSend, DomainSettings } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const dns = await mailerSend.domain.dns("your_domain_id");

Recipients

API Documentation

Get recipients

import { MailerSend, RecipientsQueryParams } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: RecipientsQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  domain_id: "your_domain_id" // not required
}

// Query params are not required
const recipients = await mailerSend.recipient.list(queryParams);

Get a single recipient

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const recipient = await mailerSend.recipient.single("your_recipient_id");

Delete a recipient

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.recipient.delete("your_recipient_id");

Get recipients from a suppression list

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: RecipientsQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  domain_id: "your_domain_id" // not required
}
// Query params are not required
const blockList = await mailerSend.recipient.blockList(queryParams);

Add recipients to a suppression list

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const recipient: BlockListRecipient = {
  domain_id: "83gwk2j7zqz1nxyd", // not required
  recipients: ["[e-mail]"], // If patterns is not defined, this property is required.
  patterns: [".*@example.com"] // If recipients is not defined, this property is required.
};

const blocked = await mailerSend.recipient.blockRecipient(recipient);

Delete recipients from a suppression list

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

// To delete specific entries
const ids = ["60f198790542d97fb66dfe52", "60f198790542d97fb66dfe53"]
const removed = await mailerSend.recipient.delBlockListRecipients(ids);

Delete all recipients from a suppression list

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const removed = await mailerSend.recipient.delAllBlockListRecipients();

Get hard bounced recipients

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: RecipientsQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  domain_id: "your_domain_id" // not required
};
// Query params are not required
const hardBounceList = await mailerSend.recipient.hardBounceList(queryParams);

Get recipients who have spam complained

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const queryParams: RecipientsQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  domain_id: "your_domain_id" // not required
};

// Query params are not required
const response = await mailerSend.recipient.spamComplaintsList(queryParams);

Unsubscribes list

import { MailerSend } from "mailer-send-ts";

const queryParams: RecipientsQueryParams = {
  limit: 10, // Default 25.Min 10, Max 50
  page: 2,
  domain_id: "your_domain_id" // not required
};

const response = await mailerSend.recipient.unsubscribesList(queryParams);

Tokens

API Documentation

Create a token

import { MailerSend, Token, TokenScopeType } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const token = new Token("token_name", "domain_id", [TokenScopeType.EMAIL_FULL, TokenScopeType.WEBHOOKS_FULL, ...scopes])

const response = await mailerSend.token.create(token);

Update a token

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.token.updateSettings("your_token_id", { status: "pause" });

Delete a token

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const response = await mailerSend.token.delete("your_token_id");

SMS

API Documentation

Send SMS

import { MailerSend } from "mailer-send-ts";

const mailerSend = new MailerSend({ apiKey: "your_api_key_here" });

const personalization: SMSPersonalization[] = [];

personalization.push(new SMSPersonalization("[phone]", { name: "Dummy" }));
personalization.push(new SMSPersonalization("[phone]", { name: "Not Dummy" }));

const params = new SMSParams()
  .setFrom("[phone]")
  .setTo([
    "[phone]",
    "[phone]"
  ])
  .setText("Hey {{name}}! This is just a friendly hello :D")
  .setPersonalization(personalization);

const response = mailerSend.sms.send(params);

Utils

Webhook signature check

import { MailerUtils } from "mailer-send-ts";

MailerUtils.verifyWebHook(rawBody, signature, signinSecret);

Arguments

rawBody - request rawBody (not json)
Note! If you are using express with body parser, check here how to extract rawBody

signature - webhook signature found in request's header - signature

signinSecret - signing secret is a random string that is generated when you create a webhook