MailerSend Node.js SDK
[](./LICENSE.md)
Hello, {{name}}!
", text: "Hello, {{name}}!", domain_id: "domain_id", categories: ["welcome"], tags: ["welcome"], auto_generate: false, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update a template ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.template.update("template_id", { name: "Updated Template Name", html: "Hello, {{name}}! Updated.
", text: "Hello, {{name}}! Updated.", auto_generate: true, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete a template ```js import 'dotenv/config'; import { MailerSend} from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.template.delete("template_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Email Verification ### Get all email verification lists ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.list({ page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get an email verification list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.single("email_verification_id", { detailed: true, page: 1, limit: 25, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Create an email verification list ```js import 'dotenv/config'; import { MailerSend, EmailVerification } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const emailVerification = new EmailVerification("My List", [ "test1@example.com", "test2@example.com", ]); // Optional: link to an existing list and trigger verification automatically // emailVerification.setListId("existing_list_id"); // emailVerification.setVerify(true); mailerSend.emailVerification.create(emailVerification) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Verify an email list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.verifyList("email_verification_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get email verification list results ```js import 'dotenv/config'; import { MailerSend, EmailVerificationResultType } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.getListResult("email_verification_id", { page: 1, limit: 25, results: [EmailVerificationResultType.VALID, EmailVerificationResultType.CATCH_ALL], }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Verify a single email ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.verifyEmail("test@example.com") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Verify a single email asynchronously ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.verifyEmailAsync("test@example.com") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get async email verification status ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.emailVerification.getVerifyEmailAsyncStatus("verification_job_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## WhatsApp ### Send a WhatsApp message ```js import 'dotenv/config'; import { MailerSend, WhatsAppParams } from "mailersend"; const mailersend = new MailerSend({ apiKey: process.env.API_KEY, }); const whatsappParams = new WhatsAppParams() .setFrom("12345678901") .setTo(["19191234567"]) .setTemplateId("template_id_123"); await mailersend.whatsapp.send(whatsappParams); ``` ### WhatsApp personalization Values are positional: the first value of each array replaces `{{1}}` in that section of the template, the second replaces `{{2}}`, and so on. `setButtons()` takes the URL parameters appended to the template's URL buttons, not full URLs. ```js import 'dotenv/config'; import { MailerSend, WhatsAppParams, WhatsAppPersonalization } from "mailersend"; const mailersend = new MailerSend({ apiKey: process.env.API_KEY, }); const personalization = [ new WhatsAppPersonalization("19191234567") .setHeader(["John"]) .setBody(["order #1234", "tomorrow"]) .setButtons(["track/1234"]), new WhatsAppPersonalization("19199876543") .setHeader(["Jane"]) .setBody(["order #5678", "Friday"]) .setButtons(["track/5678"]), ]; const whatsappParams = new WhatsAppParams() .setFrom("12345678901") .setTo(["19191234567", "19199876543"]) .setTemplateId("template_id_123") .setPersonalization(personalization); await mailersend.whatsapp.send(whatsappParams); ``` ## WhatsApp messages API A WhatsApp message is the resource created by a single [send request](#send-a-whatsapp-message). The delivery to each recipient is tracked separately as an [item](#whatsapp-items-api), and every status an item moves through is recorded as an [activity](#whatsapp-activities-api). Requires a token with one of the `whatsapp_read` or `whatsapp_full` scopes. Messages are kept for 7 days: an older message is no longer listed, and requesting it returns `404`. All WhatsApp lists use simple pagination. The response carries no `total` and no `last_page`, and `links.last` is always `null`: request the next page until `links.next` is `null`. `page` can't go beyond `100`, so narrow `date_from` and `date_to` to reach older rows. `date_from` and `date_to` accept a Unix timestamp or a datetime that includes a time, such as `2026-10-14T00:00:00Z`, assumed `UTC` and exclusive. A date without a time returns a `422` error. ### Get a list of WhatsApp messages ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.message.list({ whatsapp_account_id: "whatsapp_account_id", from: "15550001234", // The sender's phone number template_id: "template_id", date_from: 1790000000, // Unix timestamp or datetime date_to: 1790086400, // Unix timestamp or datetime limit: 25, // Min: 1, Max: 100, Default: 25 page: 1, // Min: 1, Max: 100 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` Messages are returned newest first. `WhatsAppMessageListResponse` describes the response body, and each item in `data` is a `WhatsAppMessageListItem` with `id`, `from`, `to`, `whatsapp_account_id`, `template_id` and `created_at`. `from` is the sender's phone number, or its WhatsApp username when the message was sent from the username or the sender has no phone number, and `null` when the sender has neither. ### Get a WhatsApp message ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.message.single("message_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` `WhatsAppMessageResponse` describes the response body. The message has the same fields as a list item, plus `items`: one `WhatsAppItem` per recipient, with the same fields as [Get a list of WhatsApp items](#get-a-list-of-whatsapp-items). Items are created asynchronously, so `items` can be empty right after the message is sent. ```ts import { MailerSend, WhatsAppMessageResponse } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY as string, }); const response = await mailerSend.whatsapp.message.single("message_id"); const message: WhatsAppMessageResponse = response.body; message.data.items.forEach((item) => console.log(item.to, item.status)); ``` ## WhatsApp items API An item is the delivery of a message to one recipient. Requires a token with one of the `whatsapp_read` or `whatsapp_full` scopes. ### Get a list of WhatsApp items ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.item.list({ recipient: "48600000001", // Phone number, WhatsApp username or BSUID whatsapp_message_id: "whatsapp_message_id", status: ["delivered", "read"], // queued, sent, delivered, read or failed whatsapp_account_id: "whatsapp_account_id", from: "15550001234", // The sender's phone number template_id: "template_id", date_from: 1790000000, // Unix timestamp or datetime date_to: 1790086400, // Unix timestamp or datetime limit: 25, // Min: 1, Max: 100, Default: 25 page: 1, // Min: 1, Max: 100 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` Items are returned newest first. `WhatsAppItemListResponse` describes the response body, and each item in `data` is a `WhatsAppItem` with `id`, `whatsapp_message_id`, `whatsapp_account_id`, `from`, `to`, `status`, `template_id`, `template_name`, `error_code`, `error_message` and `created_at`. Multiple `status` values are combined with `OR`. ### Get a WhatsApp item ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.item.single("item_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` `WhatsAppItemResponse` describes the response body. The item has the same fields as a list item, plus `recipient`, the [recipient](#whatsapp-recipients-api) the message was delivered to, and `activity`: every status the item moved through, each with `type` and `created_at`, in status order (`queued`, `sent`, `delivered`, `read`, `failed`). ## WhatsApp activities API An activity is a single status event of an item, so a delivered and read message appears once as `queued`, once as `sent`, once as `delivered` and once as `read`. Requires a token with one of the `whatsapp_read` or `whatsapp_full` scopes. Activity is kept for 7 days. ### Get a list of WhatsApp activities ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.activity.list({ whatsapp_item_id: "whatsapp_item_id", whatsapp_message_id: "whatsapp_message_id", recipient: "48600000001", // Phone number, WhatsApp username or BSUID type: ["delivered", "read"], // queued, sent, delivered, read or failed date_from: 1790000000, // Unix timestamp or datetime date_to: 1790086400, // Unix timestamp or datetime limit: 25, // Min: 1, Max: 100, Default: 25 page: 1, // Min: 1, Max: 100 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` Activities are returned newest first. `WhatsAppActivityListResponse` describes the response body, and each item in `data` is a `WhatsAppActivity` with `id`, `whatsapp_item_id`, `whatsapp_message_id`, `whatsapp_account_id`, `from`, `to`, `type` and `created_at`. Multiple `type` values are combined with `OR`. ## WhatsApp inbound messages API Inbound messages are the messages people send to your WhatsApp phone numbers. Requires a token with one of the `whatsapp_read` or `whatsapp_full` scopes. Inbound messages are kept for your plan's inbound retention period: an older message is no longer listed, and requesting it returns `404`. ### Get a list of WhatsApp inbound messages ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.inboundMessage.list({ whatsapp_account_id: "whatsapp_account_id", from: "48600000001", // The customer's phone number or BSUID type: ["text", "image"], date_from: 1790000000, // Unix timestamp or datetime date_to: 1790086400, // Unix timestamp or datetime limit: 25, // Min: 1, Max: 100, Default: 25 page: 1, // Min: 1, Max: 100 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` | Query parameter | Type | Required | Details | |-----------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `whatsapp_account_id` | `string` | no | The MailerSend sender ID of the phone number that received the messages. Must be one of your WhatsApp phone numbers. | | `from` | `string` | no | The customer's phone number in international format, or their BSUID. A WhatsApp username is not accepted. Max: `255` characters. | | `type` | `WhatsAppInboundMessageType[]` | no | Any of `text`, `image`, `audio`, `video`, `document`, `sticker`, `location`, `contacts`, `interactive`, `button`, `order`, `reaction`, `system`, `unknown`, `unsupported`. Values are combined with `OR`. | | `date_from` | `number \| string` | no | Unix timestamp or datetime that includes a time, assumed `UTC`. Exclusive. Must be lower than `date_to`. | | `date_to` | `number \| string` | no | Unix timestamp or datetime that includes a time, assumed `UTC`. Exclusive. Must be higher than `date_from`. | | `page` | `number` | no | Min: `1`, Max: `100`. | | `limit` | `number` | no | Min: `1`, Max: `100`, Default: `25`. | Inbound messages are returned newest first. `WhatsAppInboundMessageListResponse` describes the response body, and each item in `data` is a `WhatsAppInboundMessage` with `id`, `whatsapp_account_id`, `from`, `to`, `type`, `received_at`, `meta` and `context` when the message is a reply. `meta` holds the content of the message, and its shape depends on `type`: | `type` | `meta` | |--------------------------------------------------|------------------------------------------------------------------------| | `text` | `body` | | `image`, `audio`, `video`, `document`, `sticker` | `url`, `status`, `mime_type`, `size`, `caption`, `filename`, `animated` | | `location` | `latitude`, `longitude`, `name`, `address` | | `reaction` | `message_id`, `emoji` | | `button` | `text`, `payload` | | `interactive` | `reply_type` (`button_reply` or `list_reply`), `id`, `title`, `description` | | `contacts` | `contacts` | | `order`, `system`, `unknown`, `unsupported` | The object WhatsApp sent, as received, or `null` | Fields that WhatsApp did not send can be `null` or missing. For media, `meta.url` is a temporary signed URL, and is `null` once the file is no longer stored. Inbound media is kept for 1 day, so download the file as soon as you can if you need to keep it. ### Get a WhatsApp inbound message ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.inboundMessage.single("inbound_message_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` `WhatsAppInboundMessageResponse` describes the response body. The inbound message has the same fields as a list item. ```ts import { MailerSend, WhatsAppInboundMessageResponse } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY as string, }); const response = await mailerSend.whatsapp.inboundMessage.single("inbound_message_id"); const inboundMessage: WhatsAppInboundMessageResponse = response.body; if (inboundMessage.data.type === "image" && inboundMessage.data.meta?.status === "stored") { console.log(inboundMessage.data.meta.url); } ``` ## WhatsApp recipients API Requires a token with one of the `whatsapp_read` or `whatsapp_full` scopes. ### Get a list of WhatsApp recipients ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.recipient.list({ status: "active", // active, invalid, suppressed or blocked phone_number: "48600000001", limit: 25, // Min: 1, Max: 100, Default: 25 page: 1, // Min: 1, Max: 100 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` Recipients are returned newest first. `WhatsAppRecipientListResponse` describes the response body, and each item in `data` is a `WhatsAppRecipientListItem` with `id`, `phone_number`, `username`, `status` and `created_at`. ### Get a WhatsApp recipient ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.recipient.single("recipient_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` `WhatsAppRecipientResponse` describes the response body. The recipient has the same fields as a list item, plus `items`: their latest 25 items, newest first, with the same fields as [Get a list of WhatsApp items](#get-a-list-of-whatsapp-items). Pass an item's `id` to [Get a WhatsApp item](#get-a-whatsapp-item) for its status timeline. ## WhatsApp templates API Look up your templates and their `id`, which you pass as `template_id` when you [send a WhatsApp message](#send-a-whatsapp-message). Requires a token with one of the `whatsapp_read` or `whatsapp_full` scopes. ### Get a list of WhatsApp templates ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.template.list({ whatsapp_account_id: "whatsapp_account_id", status: "approved", // draft, pending, approved, rejected, archived, deleted, disabled, flagged, in_appeal, limit_exceeded, locked, paused, reinstated or pending_deletion category: "UTILITY", // UTILITY, AUTHENTICATION or MARKETING language: "en_US", limit: 25, // Min: 1, Max: 100, Default: 25 page: 1, // Min: 1, Max: 100 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` Templates are returned newest first. `WhatsAppTemplateListResponse` describes the response body, and each item in `data` is a `WhatsAppTemplate` with `id`, `whatsapp_account_id`, `name`, `readable_name`, `category`, `language`, `status`, `components`, `created_at` and `updated_at`. `components` has `header` and `body`, each `null` when the template has none, and `buttons`. `header.format` is `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` or `LOCATION`. Only `approved` templates can be sent. ### Get a WhatsApp template ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.whatsapp.template.single("template_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` `WhatsAppTemplateResponse` describes the response body. The template has the same fields as a list item. ## SMS ### Send SMS ```js import 'dotenv/config'; import { MailerSend, SMSParams } from "mailersend"; const mailersend = new MailerSend({ apiKey: process.env.API_KEY, }); const recipients = [ "+18332647501" ]; const smsParams = new SMSParams() .setFrom("+18332647501") .setTo(recipients) .setText("This is the text content"); await mailersend.sms.send(smsParams); ``` ### SMS personalization ```js import 'dotenv/config'; import { MailerSend, SMSParams, SMSPersonalization } from "mailersend"; const mailersend = new MailerSend({ apiKey: process.env.API_KEY, }); const recipients = [ "+18332647501", "+18332647502" ]; const personalization = [ new SMSPersonalization("+18332647501", { "name": "Dummy" }), new SMSPersonalization("+18332647502", { "name": "Not Dummy" }), ]; const smsParams = new SMSParams() .setFrom("+18332647501") .setTo(recipients) .setPersonalization(personalization) .setText("Hey {{name}} welcome to our organization"); await mailersend.sms.send(smsParams); ``` ## Phone Numbers ### Get phone number list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.number.list({ paused: false, limit: 10, page: 1 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get phone number ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.number.single("sms_number_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update phone number ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.number.update("sms_number_id", true) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete phone number ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.number.delete("sms_number_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Messages ### Get messages list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.message.list({ limit: 10, page: 1 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get a message ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.message.single("sms_message_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Activity ### Get activity list ```js import 'dotenv/config'; import { MailerSend, SmsActivityStatusType } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.activity.list({ sms_number_id: "number_id", status: [SmsActivityStatusType.SENT, SmsActivityStatusType.DELIVERED], limit: 10, page: 1 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Recipients ### Get recipient list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.recipient.list({ sms_number_id: "sms_number_id", status: "active", limit: 10, page: 1, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get recipient ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.recipient.single("sms_recipient_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update recipient ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.recipient.update("sms_recipient_id", "active") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Webhooks ### Get webhook list for a number ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.webhook.list("sms_number_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get webhook ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.webhook.single("sms_webhook_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Create webhook ```js import 'dotenv/config'; import { MailerSend, SmsWebhook, SmsWebhookEventType } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const smsWebhook = new SmsWebhook() .setName("Sms Webhook") .setUrl("https:://yourapp.com/hook") .setSmsNumberId("sms_number_id") .setEnabled(true) .setEvents([SmsWebhookEventType.SENT, SmsWebhookEventType.DELIVERED]) mailerSend.sms.webhook.create(smsWebhook) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update webhook ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.webhook.update("sms_webhook_id", { name: "Webhook", url: "https:://yourapp.com/hook", enabled: ["sms.sent", "sms.delivered", "sms.failed"], enabled: true }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete webhook ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.webhook.delete("sms_webhook_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Verify webhook signature See [Utils — Verify a webhook signature](#verify-a-webhook-signature). ## Inbound ### Get inbound list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.inbound.list({ enabled: 1, sms_number_id: "sms_number_id", limit: 10, page: 1, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get inbound ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.inbound.single("sms_inbound_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Add inbound ```js import 'dotenv/config'; import { MailerSend, SmsInbound } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const smsInbound = new SmsInbound() .setSmsNumberId("sms_number_id") .setEnabled(true) .setName("Inbound Name") .setForwardUrl("yourapp.com/hook") .setFilter({ comparer: "equal", value: "START" }); mailerSend.sms.inbound.create(smsInbound) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update inbound ```js import 'dotenv/config'; import { MailerSend, SmsInbound } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const smsInbound = new SmsInbound() .setSmsNumberId("sms_number_id") .setEnabled(true) .setName("Inbound Name Update") .setForwardUrl("yourapp.com/hook") .setFilter({ comparer: "equal", value: "START" }); mailerSend.sms.inbound.update("sms_inbound_id", {...smsInbound}) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete inbound ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.sms.inbound.delete("sms_inbound_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Identity ### Get identity list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.identity.list() .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get identity ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.identity.single("identity_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get identity by email address ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.identity.singleByEmail('email_address') .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Create identity ```js import 'dotenv/config'; import { MailerSend, Inbound, InboundFilterType } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const identity = new Identity() .setDomainId('domain_id') .setEmail('identity@yourdomain.com') .setName('Name') .setReplyToEmail('reply_identity@yourdomain.com') .setReplyToName('Reply Name') .setAddNote(false); mailerSend.email.identity.create(identity) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update identity ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const data = { name: 'name', reply_to_name: 'Reply Name', reply_to_email: 'reply@yourdomain.com', }; mailerSend.email.identity.update('identity_id', data) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update identity by email address ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const data = { name: 'name', reply_to_name: 'Reply Name', reply_to_email: 'reply@yourdomain.com', }; mailerSend.email.identity.updateByEmail('email_address', data) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete identity ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.identity.delete("identity_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete identity by email address ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.identity.deleteByEmail('email_address') .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Resend identity verification ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.identity.resend("identity_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## SMTP Users ### List SMTP users ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.smtpUser.list("domain_id", { page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get SMTP user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.smtpUser.single("domain_id", "smtp_user_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Create SMTP user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.smtpUser.create("domain_id", { name: "My SMTP User", enabled: true, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update SMTP user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.smtpUser.update("domain_id", "smtp_user_id", { name: "Updated SMTP User", enabled: false, }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete SMTP user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.email.smtpUser.delete("domain_id", "smtp_user_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Users ### Get user list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.list({ page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get single user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.single("user_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Invite a user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.create({ email: "user@example.com", role: "manager", // For role "custom", permissions is required: // permissions: ["read-activity", "read-analytics"], // templates: ["template_id"], // domains: ["domain_id"], }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.update("user_id", { role: "designer", }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete user ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.delete("user_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get invite list ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.listInvites({ page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get single invite ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.singleInvite("invite_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Resend invite ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.resendInvite("invite_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Cancel invite ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.user.deleteInvite("invite_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## DMARC Monitoring ### List monitors ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.list({ page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Create monitor ```js import 'dotenv/config'; import { MailerSend, Dmarc } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const dmarc = new Dmarc("domain_id"); mailerSend.dmarc.create(dmarc) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update monitor ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.update("monitor_id", { wanted_dmarc_record: "v=DMARC1; p=reject;" }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete monitor ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.delete("monitor_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get aggregated reports ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.report("monitor_id", { page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get IP-specific reports ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.reportByIp("monitor_id", "1.2.3.4", { page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get report sources ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.reportSources("monitor_id", { date_from: 1700000000, date_to: 1700100000, status: "accepted", // optional: "accepted" | "rejected" | "quarantined" }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Mark IP as favorite ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.addFavorite("monitor_id", "1.2.3.4") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Remove IP from favorites ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.dmarc.removeFavorite("monitor_id", "1.2.3.4") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Blocklist Monitoring ### List blocklist monitors ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.blocklistMonitor.list({ page: 1, limit: 25 }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Get single blocklist monitor ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.blocklistMonitor.single("monitor_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Create blocklist monitor ```js import 'dotenv/config'; import { MailerSend, BlocklistMonitor } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); const monitor = new BlocklistMonitor("example.com") .setName("My Domain Monitor") .setNotify(true) .setNotifyEmail("alerts@example.com"); mailerSend.blocklistMonitor.create(monitor) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Update blocklist monitor ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.blocklistMonitor.update("monitor_id", { name: "Updated Monitor Name", notify: true, notify_email: "alerts@example.com", }) .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ### Delete blocklist monitor ```js import 'dotenv/config'; import { MailerSend } from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.blocklistMonitor.delete("monitor_id") .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Other endpoints ### Get API quota ```js import 'dotenv/config'; import { MailerSend} from "mailersend"; const mailerSend = new MailerSend({ apiKey: process.env.API_KEY, }); mailerSend.others.getApiQuota() .then((response) => console.log(response.body)) .catch((error) => console.log(error.body)); ``` ## Utils ### Verify a webhook signature Use `MailerSendUtils.verifyWebHook()` to verify the HMAC signature on incoming webhook requests. This works for email, SMS and WhatsApp webhooks. It returns `false` when the signature does not match the payload, and throws when one of its arguments is missing — including when the `x-mailersend-signature` header is absent, which is usually a sign that the route or the signing secret is misconfigured. Wrap the call so that a request without a valid signature is rejected instead of crashing the handler. ```js import { MailerSendUtils } from "mailersend"; try { // rawBody must be the raw Buffer from the request (do not parse it as JSON first) const isValid = MailerSendUtils.verifyWebHook( rawBody, request.headers['x-mailersend-signature'], process.env.WEBHOOK_SIGNING_SECRET ); if (!isValid) { return response.status(401).send("Invalid signature"); } // handle the webhook payload } catch (error) { // the raw body, the signature header or the signing secret was missing console.error("Could not verify webhook signature:", error.message); return response.status(401).send("Invalid signature"); } ``` # Support and Feedback In case you find any bugs, submit an issue directly here in GitHub. You are welcome to create SDK for any other programming language. If you have any troubles using our API or SDK free to contact our support by email [info@mailersend.com](mailto:info@mailersend.com) The official documentation is at [https://developers.mailersend.com](https://developers.mailersend.com) # License [The MIT License (MIT)](LICENSE)