Mailisk
On this page

NodeJS Guide ​

If you haven't already, see Getting Started to get setup and find your API key. The following examples will assume you have already received your API key and created a namespace.

If you're instead working with Node and using Cypress check out the Cypress Guide.

mailisk-node ​

Mailisk offers a NodeJS library mailisk-node. This is an official library that wraps the API Reference endpoints into functions.

Installation ​

First install the library using npm

shell
npm install --save-dev mailisk

Or yarn

shell
yarn add mailisk --dev

Setup Client ​

Once installed import the library and create the client by passing in your API key

js
const { MailiskClient } = require("mailisk");

const mailisk = new MailiskClient({ apiKey: "YOUR_API_KEY" });

Reading Email ​

You can read emails using the searchInbox function.

  • By default it uses the wait flag. This means the call won't return until at least one email is received. Disabling this flag via wait: false can cause it to return an empty response immediately.
  • The request timeout is adjustable by passing timeout in the request options. By default it uses a timeout of 5 minutes.
  • By default from_timestamp is set to current timestamp - 5 seconds. This ensures that only new emails are returned. Without this, older emails would also be returned, potentially disrupting you if you were waiting for a specific email. This can be overriden by passing the from_timestamp parameter (from_timestamp: 0 will disable filtering by email age).
js
// timeout of 5 minutes
await mailisk.searchInbox(namespace);
// timeout of 1 minute
await mailisk.searchInbox(namespace, {}, { timeout: 1000 * 60 });
// returns immediately, even if the result would be empty
await mailisk.searchInbox(namespace, { wait: false });

This snippet will read the last 10 emails that were sent to your namespace with the address john@mynamespace.mailisk.net.

The response will look similar to this:

json
{
  "total_count": 1,
  "options": {
    "limit": 10,
    "offset": 0
  },
  "data": [
    {
      "id": "1659368409795-42UcuQtMy",
      "from": {
        "address": "contact@mailisk.com",
        "name": ""
      },
      "to": [
        {
          "address": "john@sh7o3t3e4jvj.mailisk.net",
          "name": ""
        }
      ],
      "subject": "Test - Welcome to Mailisk 👋",
      "html": "<html>...",
      "text": "*Welcome to Mailisk*\n\nHello there 👋\nWelcome to Mailisk! We're excited to have you!\n\nGo ahead and ...",
      "received_date": "2022-08-01T15:40:09.000Z",
      "received_timestamp": 1659368409,
      "expires_timestamp": 1659372009
    }
  ]
}

The total_count tells us the total number of emails that match our query, depending on limit and offset a subset of this will be returned. See the Search Inbox Response for more information on the other fields.

Sending Email ​

Mailisk supports sending an email using Virtual SMTP. This will fetch the SMTP settings for the selected namespace and send an email. These emails can only be sent to an address that ends in @{namespace}.mailisk.net.

js
const namespace = "mynamespace";

await mailisk.sendVirtualEmail(namespace, {
  from: "test@example.com",
  to: `john@${namespace}.mailisk.net`,
  subject: "This is a test",
  text: "Testing",
});