mailisk

Mailisk Node Client

Mailisk is an end-to-end email and SMS testing platform. It allows you to receive emails and SMS messages with code to automate tests.

• Get a unique subdomain and unlimited email addresses for free.
• Easily automate E2E password reset and account verification by catching emails.
• Receive SMS messages and automate SMS tests.
• Virtual SMTP and SMS support to test without 3rd party clients.

Get started

For a more step-by-step walkthrough see the NodeJS Guide.

Installation

Install with npm

npm install --save-dev mailisk

Install with Yarn

yarn add mailisk --dev

Usage

After installing the library import it and set the API Key

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

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

// send email (using virtual SMTP)
await mailisk.sendVirtualEmail(namespace, {
  from: "[e-mail]",
  to: `john@${namespace}.mailisk.net`,
  subject: "Testing",
  text: "This is a test.",
});

// receive email
const result = await mailisk.searchInbox(namespace);

console.log(result);

API Reference

This library wraps the REST API endpoints. Find out more in the API Reference.

Client functions (Email)

searchInbox(namespace, params?, requestOptions?)

Use searchInbox to fetch messages that arrived in a given namespace, optionally waiting until the first new mail shows up.

For the full parameter options see the endpoint reference.

Default behaviour:

• Waits until at least one new email arrives (override with wait: false).
• Times out after 5 minutes if nothing shows up (adjust via requestOptions.timeout).
• Ignores messages older than 15 minutes to avoid picking up leftovers from previous tests (change via from_timestamp).

Quick examples

// wait up to the default 5 min for *any* new mail
await mailisk.searchInbox(namespace);
// custom 60-second timeout
await mailisk.searchInbox(namespace, {}, { timeout: 1000 * 60 });
// polling pattern — return immediately, even if inbox is empty
await mailisk.searchInbox(namespace, { wait: false });
// returns the last 20 emails in the namespace immediately
await mailisk.searchInbox(namespace, { wait: false, from_timestamp: 0, limit: 20 });

Filter by destination address

A common pattern is to wait for the email your UI just triggered (e.g. password-reset). Pass to_addr_prefix so you don’t pick up stale messages:

const { data: emails } = await mailisk.searchInbox(namespace, {
  to_addr_prefix: `john@${namespace}.mailisk.net`,
});

sendVirtualEmail(namespace, params)

Send 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.

const namespace = "mynamespace";

await mailisk.sendVirtualEmail(namespace, {
  from: "[e-mail]",
  to: `john@${namespace}.mailisk.net`,
  subject: "This is a test",
  text: "Testing",
});

listNamespaces()

List all namespaces associated with the current API Key.

const { data: namespaces } = await mailisk.listNamespaces();

// will be ['namespace1', 'namespace2']
const namespacesList = namespaces.map((nr) => nr.namespace);

getAttachment(attachmentId)

Get information about an attachment.

const attachment = await mailisk.getAttachment(attachmentId);

downloadAttachment(attachmentId)

Retrieve the raw bytes of a file attached to an email message.
Typically you call this after searchInbox → iterate over email.attachments[] → pass the desired attachment.id.

Quick examples

import fs from "node:fs";
import path from "node:path";

// assume 'email' was fetched via searchInbox()
const { id, filename } = email.attachments[0];

// download the attachment
const buffer = await mailisk.downloadAttachment(id);

// save to disk (preserve original filename)
fs.writeFileSync(filename, buffer);

Streaming large files

downloadAttachment returns the entire file as a single Buffer. If you expect very large attachments and want to avoid holding them fully in memory, use getAttachment(attachmentId).download_url and stream with fetch / axios instead:

const meta = await mailisk.getAttachment(id);
const res = await fetch(meta.download_url);
const fileStream = fs.createWriteStream(filename);
await new Promise((ok, err) => res.body.pipe(fileStream).on("finish", ok).on("error", err));

Client functions (SMS)

searchSmsMessages(phoneNumber, params?, requestOptions?)

Fetch recent SMS messages that were delivered to one of your Mailisk phone numbers.
For the full parameter list see the Search SMS reference.

Default behaviour:

• Waits until at least one SMS matches the filters (override with wait: false).
• Times out after 5 minutes if nothing shows up (adjust via requestOptions.timeout).
• Ignores messages older than 15 minutes (change via from_date).

Quick examples

// get or wait for SMS messages sent to ths number
const { data: sms } = await mailisk.searchSmsMessages(phoneNumber);

// look for a verification code coming from a known sender
await mailisk.searchSmsMessages(phoneNumber, {
  from_number: "+1800555",
  body: "Your code",
});

// polling pattern — return immediately even if nothing matched
await mailisk.searchSmsMessages(
  phoneNumber,
  { wait: false, limit: 10, from_date: new Date(Date.now() - 1000 * 60 * 5).toISOString() },
  { timeout: 10_000 }
);

listSmsNumbers()

List all SMS phone numbers associated with the current account.

const { data: phoneNumbers } = await mailisk.listSmsNumbers();

sendVirtualSms(params)

Send a virtual SMS message to a phone number you have access to.

await mailisk.sendVirtualSms({
  from_number: "15551234567",
  to_number: "15557654321",
  body: "Test message",
});