​
Prerequisites

Before getting started, you’ll need to:

  1. Authorize your sending domain
  2. Create and retrieve your SendLayer API key

​
Installation

Install the SendLayer Node.js SDK using the command:

npm install sendlayer

​
Usage

After the installation completes, you’re ready to start integrating the SDK to your code. The SDK includes modules to send emails, manage webhooks and events.

​
Sending an Email

Create a new .js file or edit an existing one. Then import the SendLayer module. Once done, you’ll need to initialize the module with your SendLayer API key.

sendEmail.js
import { SendLayer } from 'sendlayer';

// Initialize the email client with your API key
const sendlayer = new SendLayer('your-api-key');

// Send an email
const response = await sendlayer.Emails.send({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Test Email',
  text: 'This is a test email'
});

console.log('Email sent! Message ID:', response);

​
Sending HTML Emails

To send HTML emails, simply include the html parameter to the send() method.

sendEmail.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Send an email
const response = await sendlayer.Emails.send({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Test Email',
  html: '<html><body><p>This is a test email sent with the <a href="https://sendlayer.com">SendLayer</a> API!</p></body></html>'
});
You can include the text parameter to have a plain text and HTML version of your email message

​
Sending to Multiple Recipients

You can send emails to multiple recipients including "Cc" and "BCC" email addresses.

sendEmail.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Send to multiple recipients
const response = await sendlayer.Emails.send({
  from: {email: 'sender@example.com', name: 'Sender Name'}
  to: [
    { email: 'recipient1@example.com', name: 'Recipient 1' },
    { email: 'recipient2@example.com', name: 'Recipient 2' }
  ],
  subject: 'Complex Email',
  html: '<p>This is a <strong>test email</strong>!</p>',
  text: 'This is a test email!',
  cc: [{ email: 'cc@example.com', name: 'CC Recipient' }],
  bcc: [{ email: 'bcc@example.com', name: 'BCC Recipient' }],
  replyTo: [{ email: 'reply@example.com', name: 'Reply To' }],
});

Each recipient field is an array containing the recipient’s name and email as objects.

There are limits to the number of email recipients you can add to a single request. See our rate limiting guide to learn more.

​
Including Attachments

You can include attachments to your email message by adding the attachments parameter to the email payload.

sendEmail.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Send email with attachments
const response = await sendlayer.Emails.send({
  from: {email: 'sender@example.com', name: 'Sender Name'}
  to: [
    { email: 'recipient1@example.com', name: 'Recipient' }
  ],
  subject: 'Complex Email',
  html: '<p>This is a <strong>test email</strong>!</p>',
  attachments: [{
    path: 'path/to/file.pdf',
    type: 'application/pdf',
  }]
});
The maximum email size SendLayer allows is 10MB. This includes both the message as well as attachment files.

Simply replace the path parameter with the path to the attachment file you wish to attach and specify the correct type.

SendLayer SDK supports both local and remote file attachments and allows you to add multiple attachment files. See our tutorial to learn more about attaching files to emails.

​
Email Parameters

Below is a table containing the supported parameters for sending emails in Node.js using SendLayer SDK.

ParameterTypeRequiredDescription
tostring or arrayYesEmail address(es) of the recipient(s). Can be a single email string or an array of objects with ‘email’ and ‘name’ keys
fromstring or objectYesEmail address of the sender. Can be a single email string or an object with ‘email’ and ‘name’ keys
subjectstringYesSubject line of the email
textstringNoPlain text version of the email content
htmlstringNoHTML version of the email content
ccstring or arrayNoCC email address(es). Can be a single email string or an array of objects containing CC recipient email addresses and names
bccstring or arrayNoBCC email address(es). Can be a single email string or an array of objects containing BCC recipient email addresses and names
replyTostring or arrayNoReplyTo email address. Can be a single email string or an object containing reply-to email address and name
tagsarrayNoArray of strings for tagging emails
headersobjectNoObject containing custom headers
attachmentsarrayNoArray of objects containing file paths and MIME types for attachments

​
Managing Webhooks

With the SendLayer Node.js SDK, you can create new webhook, view all webhooks you’ve created and also delete a specific webhook.

​
Creating a New Webhook

To create a new webhook, you’ll need to first import the SendLayer module and initialize it with your API key.

Then call the Webhooks.create() method and specify the required parameters. This method requires the url and event parameters.

webhooks.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

params = {
  url: 'https://your-domain.com/webhook',
  event: 'open'
}

// Create a webhook
const webhook = await sendlayer.Webhooks.create(params);

The event parameter is constrained to the following options:

  • bounce
  • click
  • open
  • unsubscribe
  • complaint
  • delivery

Example success response for new webhook:

{
   "NewWebhookID": 23718
}

​
Getting All Webhooks

To view all the webhooks you’ve created, use the Webhooks.get() method.

webhooks.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Get all webhooks
const webhooks = await sendlayer.Webhooks.get();

Here is an example response:

{
  "Webhooks": [
    {
      "WebhookID": "23718",
      "CreatedAt": "2025-04-11 09:43:07",
      "UpdatedAt": "2025-04-11 09:43:07", 
      "Status": "Enabled",
      "WebhookURL": "http://example.com/webhook",
      "Event": "delivered",
      "LastResponseCode": "0",
      "LastResponseBody": "",
      "LastResponseAt": "0000-00-00 00:00:00",
      "LastResponseTryCounter": "0"
    }
  ]
}

​
Deleting a Webhook

To delete a specific webhook, use the Webhooks.delete() method. This method accepts one required parameter webhookId that needs to be a number.

Deleting a webhook cannot be undone. You won’t be able to recover or access your webhook after deleting it.
webhooks.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Delete a webhook
const webhookId = 23718;
await sendlayer.Webhooks.delete(webhookId);

​
Webhooks Parameters

The table below contains details about the supported parameters in the Webhooks module.

ParameterTypeRequiredDescription
urlstringYesThe webhook endpoint URL where events will be sent
eventstringYesThe type of event to listen for. Options: bounce, click, open, unsubscribe, complaint, delivery
webhookIdnumberYesUnique identifier for the webhook (used in delete operation)

​
Retrieving Email Events

You can view all events connected to your API key.

​
Getting All Events

To get started, import the SendLayer module and initialize it with your API key. Then call the Events.get() method to retrieve all events.

The Events.get() method retrieves the top 5 events in your account if no filter parameter is specified.
events.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Get all events
const events = await sendlayer.Events.get();

Example response:

{
  "totalRecords": 5,
  "events": [
    {
      "Event": "delivered",
      "LoggedAt": 1746340896,
      "LogLevel": "info",
      "Message": {
        "Headers": {
          "MessageId": "06e4491f-fc5a-49cb-bc57-xxxxxx",
          "From": [["", "sender@example.com"]],
          "ReplyTo": [],
          "To": [["", "recipient@example.com"]],
          "Cc": [],
          "Bcc": []
        },
        "Size": 2004,
        "Transport": "api"
      },
      "Recipient": "recipient@example.com",
      "Reason": "Email has been delivered."
    }
  ]
}

​
Filtering Events

The Events.get() method in the SendLayer module accepts some optional parameters. These parameters can be used to filter the API response. Here is an example:

events.js
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Filter events for the last 4 hours
const events = await sendlayer.Events.get({
  startDate: new Date(Date.now() - 4 * 60 * 60 * 1000), // 4 hours ago
  endDate: new Date(), // current time
  event: 'opened'
});

​
Events Parameters

The table below contains details about the available parameters in the Events module.

ParameterTypeRequiredDescription
startDateDateNoStart date for filtering events
endDateDateNoEnd date for filtering events
eventstringNoFilter the API request by the type of event. Supported events include: accepted, rejected, delivered, opened, clicked, unsubscribed, complained, failed
messageIdstringNoFilter by the email MessageId
startFromnumberNoSpecify a starting number for the email filter
retrieveCountnumberNoThis parameter controls the number of event records that’ll be displayed. It defaults to 5 if none is specified

​
Error Handling

The SDK provides custom error types (SendLayerError, SendLayerAPIError) for better error handling. You can use try/catch blocks to handle errors when sending emails:

import { SendLayer, SendLayerError, SendLayerAPIError } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

try {
  const response = await sendlayer.Emails.send({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Test Email',
    text: 'This is a test email'
  });
} catch (error) {
  if (error.name === 'SendLayerAPIError') {
    console.error('API error:', error.message);
  } else {
    console.error('Error:', error.message);
  }
}

Here is an example error response:

Error: Invalid event name - 'opened' is not a valid event name

​
More Examples

SendLayer Node.js SDK

View more details and examples on GitHub.