@sidemail/sdk-js

v0.1.5

Published

2 years ago

Node.js library for the Sidemail API.

Downloads

0High
0Medium
0Low

pkrupar

sidemail transactional emails

Sidemail Node.js library

The Sidemail Node.js library provides convenient access to the Sidemail API from applications written in server-side JavaScript.

Installation

Install this package with:

npm install @sidemail/sdk-js --save
# or
yarn add @sidemail/sdk-js

Usage

First, the package needs to be configured with your project's API key, which you can find in the Sidemail Dashboard.

Here's how:

// Create Sidemail instance and set your API key.
const configureSidemail = require("@sidemail/sdk-js");
const sidemail = configureSidemail({ apiKey: "xxxxx" });

Then, you can call sidemail.sendEmail to send emails like so:

try {
  const response = await sidemail.sendEmail({
    toAddress: "[email protected]",
    fromAddress: "[email protected]",
    fromName: "Your app",
    templateName: "Welcome",
  });

  // Response contains email ID
  console.log(
    `An email with ID '${response.id}' was successfully queued for sending. :)`
  );
} catch (err) {
  // Uh-oh, we have an error! You error handling logic...
  console.error(err);
}

The response will look like this:

{
  "id": "5e858953daf20f3aac50a3da",
  "status": "queued"
}

Learn more about Sidemail API:

Email sending examples

Send password reset email template

await sidemail.sendEmail({
  toAddress: "[email protected]",
  fromAddress: "[email protected]",
  fromName: "Your app",
  templateName: "Password reset",
  templateProps: { resetUrl: "https://your.app/reset?token=123" },
});

Schedule email delivery

await sidemail.sendEmail({
  toAddress: "[email protected]",
  fromName: "Startup name",
  fromAddress: "[email protected]",
  templateName: "Welcome",
  templateProps: { firstName: "Patrik" },
  // Deliver email in 60 minutes from now
  scheduledAt: "2020-04-04T12:58:50.964Z",
});

Send email template with dynamic list

Useful for dynamic data where you have n items that you want to render in email. For example, items in a receipt, weekly statistic per project, new comments, etc.

await sidemail.sendEmail({
    toAddress: "[email protected]",
    fromName: "Startup name",
    fromAddress: "[email protected]",
    templateName: "Template with dynamic list",
    templateProps: {
        list: [
            { text: "Dynamic list" },
            { text: "allows you to generate email template content" },
            { text: "based on template props." },
        ],
    }
}
});

Send custom HTML email

await sidemail.sendEmail({
  toAddress: "[email protected]",
  fromName: "Startup name",
  fromAddress: "[email protected]",
  subject: "Testing html only custom emails :)",
  html: "<html><body><h1>Hello world! 👋</h1><body></html>",
});

Send custom plain text email

await sidemail.sendEmail({
  toAddress: "[email protected]",
  fromName: "Startup name",
  fromAddress: "[email protected]",
  subject: "Testing plain-text only custom emails :)",
  text: "Hello world! 👋",
});

Contacts

Create or update a contact

try {
  const response = await sidemail.contacts.createOrUpate({
    emailAddress: "[email protected]",
    identifier: "123",
    customProps: {
      name: "Marry Lightning",
      // ... more of your contact props ...
    },
  });

  // Response will contain scheduled email ID
  console.log(`Contact was '${response.status}'.`);
} catch (err) {
  // Uh-oh, we have an error! You error handling logic...
  console.error(err);
}

Find contact

try {
  const response = await sidemail.contacts.find({
    emailAddress: "[email protected]",
  });

  // Response will contain scheduled email ID
  console.log(`Contact data:' ${response.contact}'.`);
} catch (err) {
  // Uh-oh, we have an error! You error handling logic...
  console.error(err);
}

Delete contact

try {
  const response = await sidemail.contacts.delete({
    emailAddress: "[email protected]",
  });

  // Response will contain scheduled email ID
  console.log(`Contact deleted:' ${response.deleted}'.`);
} catch (err) {
  // Uh-oh, we have an error! You error handling logic...
  console.error(err);
}

More info

Visit Sidemail docs for more information.