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.
For a more step-by-step walkthrough see the Cypress Guide.
- Node.js 20 or newer
npm install --save-dev cypress-mailiskyarn add cypress-mailisk --devAfter installing the package add the following in your project's cypress/support/e2e.js:
import 'cypress-mailisk';To be able to use the API you will need to add your API key to cypress.config.js:
module.exports = defineConfig({
env: {
MAILISK_API_KEY: 'YOUR_API_KEY',
},
});The cypress-mailisk plugin provides additional commands which can be accessed on the cypress object, for example cy.mailiskSearchInbox(). These commands extend the Chainable object which allows you to use the then() method to chain commands.
This is the main command to interact with Mailisk, it wraps the Search Inbox endpoint. See the reference documentation for the full list of filters and their description.
cy.mailiskSearchInbox('yournamespace', { to_addr_prefix: 'test.user@', subject_includes: 'register' }).then(
(response) => {
const emails = response.data;
expect(emails).to.not.be.empty;
},
);This command does a few extra things out of the box:
- 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).
// wait up to the default 5 min for *any* new mail
cy.mailiskSearchInbox(namespace);
// custom 60-second timeout
cy.mailiskSearchInbox(namespace, {}, { timeout: 1000 * 60 });
// polling pattern — return immediately, even if inbox is empty
cy.mailiskSearchInbox(namespace, { wait: false });
// returns the last 20 emails in the namespace immediately
cy.mailiskSearchInbox(namespace, { wait: false, from_timestamp: 0, limit: 20 });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:
cy.mailiskSearchInbox(namespace, {
to_addr_prefix: `test.user@${namespace}.mailisk.net`,
}).then((response) => {
const emails = response.data;
expect(emails).to.not.be.empty;
});Use from_addr_includes to narrow results to a sender or domain. This is useful when multiple systems write to the same namespace but only one sender matters for the test.
cy.mailiskSearchInbox(namespace, {
from_addr_includes: '@example.com',
}).then((response) => {
const emails = response.data;
expect(emails).to.not.be.empty;
});The subject_includes filter helps when the UI sends different notification types from the same sender. Matching is case-insensitive and only requires the provided string to be present.
cy.mailiskSearchInbox(namespace, {
to_addr_prefix: `test.user@${namespace}.mailisk.net`,
subject_includes: 'password reset',
}).then((response) => {
const emails = response.data;
expect(emails).to.not.be.empty;
});This command retrieves attachment metadata including download URL, filename, content type, and size.
cy.mailiskGetAttachment('attachment-id').then((attachment) => {
console.log(attachment.data.filename);
console.log(attachment.data.content_type);
console.log(attachment.data.size);
});This command downloads the actual attachment content as a Buffer. It first retrieves the attachment metadata, then downloads the file from the provided download URL.
cy.mailiskDownloadAttachment('attachment-id').then((buffer) => {
cy.writeFile('downloads/attachment.pdf', buffer);
});This is the main command to interact with Mailisk SMS, it wraps the Search SMS endpoint. Use a phone number that is registered to your account.
cy.mailiskSearchSms('phoneNumber', { from_date: new Date('2023-01-01T00:00:00Z'), limit: 5 }).then((response) => {
const smsMessages = response.data;
});This Cypress command does a few extra things out of the box compared to calling the raw API directly:
- 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 SMS older than 15 minutes by default (override with
from_date).
// wait up to the default 5 min for *any* new SMS sent to the phone number
cy.mailiskSearchSms('phoneNumber');
// custom 60-second timeout
cy.mailiskSearchSms('phoneNumber', {}, { timeout: 1000 * 60 });
// polling pattern — return immediately, even if inbox is empty
cy.mailiskSearchSms('phoneNumber', { wait: false });
// returns the last 20 SMS messages for the phone number immediately
cy.mailiskSearchSms('phoneNumber', { wait: false, from_date: new Date(0), limit: 20 });Use from_number to narrow results to a specific phone number.
cy.mailiskSearchSms('phoneNumber', {
from_number: '1234567890',
}).then((response) => {
const smsMessages = response.data;
});Use body to narrow results to a specific message body.
cy.mailiskSearchSms('phoneNumber', {
body: 'Here is your code:',
}).then((response) => {
const smsMessages = response.data;
});This command lists the SMS numbers available to the current API key.
cy.mailiskListSmsNumbers().then((response) => {
const smsNumbers = response.data;
expect(smsNumbers).to.not.be.empty;
});This example demonstrates how to search for emails with attachments and download them:
describe('Test email attachments', () => {
const namespace = 'yournamespace';
const testEmailAddr = `test.user@${namespace}.mailisk.net`;
it('Finds email with attachment and downloads it', () => {
cy.mailiskSearchInbox(namespace, {
to_addr_prefix: testEmailAddr,
subject_includes: 'invoice',
}).then((response) => {
expect(response.data).to.not.be.empty;
const email = response.data[0];
// Check if email has attachments
expect(email.attachments).to.not.be.empty;
const attachment = email.attachments[0];
// Get attachment metadata
cy.mailiskGetAttachment(attachment.id).then((attachmentData) => {
expect(attachmentData.data.filename).to.contain('.pdf');
expect(attachmentData.data.content_type).to.equal('application/pdf');
// Download the attachment
cy.mailiskDownloadAttachment(attachment.id).then((buffer) => {
// Save to downloads folder
cy.writeFile(`downloads/${attachmentData.data.filename}`, buffer);
// Verify file was downloaded
cy.readFile(`downloads/${attachmentData.data.filename}`).should('exist');
});
});
});
});
});This example demonstrates going to a password reset page, requesting a new password, receiving reset code link via email and finally setting the new password.
describe('Test password reset', () => {
let resetLink;
const namespace = 'yournamespace';
const testEmailAddr = `test.test@${namespace}.mailisk.net`;
it('Starts a password reset', () => {
cy.visit('https://example.com/password_reset');
cy.get('#email_field').type(testEmailAddr);
});
it('Gets a password reset email', () => {
cy.mailiskSearchInbox(namespace, {
to_addr_prefix: testEmailAddr,
subject_includes: 'password',
}).then((response) => {
expect(response.data).to.not.be.empty;
const email = response.data[0];
expect(email.subject).to.equal('Please reset your password');
resetLink = email.text.match(/.(https:\/\/example.com\/password_reset\/.*)>\n*/)[1];
expect(resetLink).to.not.be.undefined;
});
});
it('Goes to password reset link', () => {
cy.visit(resetLink);
cy.title().should('contain', 'Change your password');
cy.get('#password').type('MyNewPassword');
cy.get('#password_confirmation').type('MyNewPassword');
cy.get('form').submit();
});
});See the full Mailisk Documentation for more examples and information.