Skip to content
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.

Reading Email

You can read emails using the Search Inbox endpoint. This will return the last limit emails that were sent to {anything}@{namespace}.mailisk.net.

import axios from "axios";

const API_KEY = "YOUR_API_KEY";
const NAMESPACE = "YOUR_NAMESPACE";

axios
  .get(`https://api.mailisk.com/api/emails/${NAMESPACE}/inbox`, {
    params: {
      limit: 10,
    },
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": API_KEY,
    },
  })
  .then((res) => console.log(res.data));

This snippet will read the last 10 emails that were sent to your mailbox. If you wish to read more emails you can add the offset property in combination with the limit property and total_count from the response to get pagination.

The response will look similar to this:

{
  "options": {
    "total_count": 1,
    "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": "...",
      "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,
      "spam_score": 1.6
    }
  ]
}

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

Waiting for Email

You'll often want to wait for an email to arrive before continuing with your tests. While this can be achieved by retrying the request an easier solution is to use the built-in wait property.

This will make it so the request will keep redirecting to itself until at least one result is returned. Meaning this request does not timeout.

Since we generally only care about recent email, we can also add from_timestamp which will filter out all older emails. Without this the request would returny immediately if any older emails were already in the inbox.








 







 
 

 








import axios from "axios";

const API_KEY = "YOUR_API_KEY";
const NAMESPACE = "YOUR_NAMESPACE";

// since the from_timestamp expects timestamp in seconds,
// and .getTime gives us milliseconds, we need to divide by 1000
const timestamp = Math.floor((new Date()).getTime() / 1000)

axios
  .get(
    `https://api.mailisk.com/api/emails/${NAMESPACE}/inbox`,
    {
      params: {
        limit: 10,
        from_timestamp: timestamp,
        wait: true,
      },
      timeout: 300 * 1000, // wait 5 minutes before timing out
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": API_KEY,
      },
    }
  )
  .then((res) => console.log(res.data));

Note

Since this request will never timeout and will only return when at least one email would be returned. We've added a manual timeout, so if an email doesn't arrive within 5 minutes it'll timeout. This is generally good practice to ensure your integration tests do not hang forever.

Filtering Email

Often you don't want to just wait for any email, instead you want to wait for specific emails to arrive in your inbox. This can be achieved using the to_addr_prefix property.









 








 











import axios from "axios";

const API_KEY = "YOUR_API_KEY";
const NAMESPACE = "YOUR_NAMESPACE";

const timestamp = Math.floor((new Date()).getTime() / 1000)

// filter emails which have a recepient starting with testuser1@...
const prefix = "testuser1@"

axios
  .get(
    `https://api.mailisk.com/api/emails/${NAMESPACE}/inbox`,
    {
      params: {
        limit: 10,
        from_timestamp: timestamp,
        to_addr_prefix: prefix,
        wait: true,
      },
      timeout: 300 * 1000,
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": API_KEY,
      },
    }
  )
  .then((res) => console.log(res.data));

With this, only emails that have a destination address starting with testuser1@ will be returned.

Since we included the at (@) character, only emails sent to testuser1@{namespace}.mailisk.net will be returned.

Tip

When writing integration tests you can send emails to test-{timestamp}@. This way you ensure that every test has a new email address. which allows you to easily filter emails using to_addr_prefix.

Sending Email

Mailisk supports outbound SMTP. This allows sending emails with SMTP to your namespace.

You can find your SMTP credentials in the namespace settings. The following snippet will send an email to your namespace inbox:

const nodemailer = require("nodemailer");

const SMTP_USER = "yournamespace@mailisk.net";
const SMTP_PASSWORD = "password";

const transport = nodemailer.createTransport({
  pool: true,
  host: "smtp.mailisk.net",
  port: 587,
  secure: false,
  auth: {
    user: SMTP_USER,
    pass: SMTP_PASSWORD,
  },
});

async function main() {
  await transport.sendMail({
    from: "hello@test.com",
    to: "test@yournamespace.mailisk.net",
  });
}

main().catch(console.error);