[![npm version](https://img.shields.io/npm/v/cypress-temp-mail)](https://www.npmjs.com/package/cypress-temp-mail)
[![npm downloads](https://img.shields.io/npm/dm/cypress-temp-mail)](https://www.npmjs.com/package/cypress-temp-mail)
[![license](https://img.shields.io/github/license/madhusaran/cypress-temp-mail)](https://github.com/madhusaran/cypress-temp-mail)


[![cypress-temp-mail](https://github.com/madhusaran/cypress-temp-mail/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/madhusaran/cypress-temp-mail/actions/workflows/node.js.yml)

[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/EUWyif5YN84SKhaNfWiKfp/SKcU1Ac4pexEmmk3agK539/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/circleci/EUWyif5YN84SKhaNfWiKfp/SKcU1Ac4pexEmmk3agK539/tree/main)


# cypress-temp-mail ✔
cypress-temp-mail is a lightweight npm library designed to generate temporary email addresses for end-to-end testing with Cypress. It streamlines the process of testing email-related functionalities in your applications.

## Features ✔

- **Quick Setup**: Easily integrate with your Cypress tests.
- **Disposable Emails**: Generate temporary emails for testing sign-ups, password resets, and more.

## Why Choose `cypress-temp-mail`?

- **Fast Setup**: Quickly add disposable email support to your Cypress tests.
- **No Runtime Dependencies**: Inboxes come from the free [mail.tm](https://mail.tm) API through `cy.request`, with no account or API key needed.
- **Waits for Mail**: `cy.getMailbox({ minMessages: 1 })` polls until the mail arrives, no fixed `cy.wait` needed.
- **Flexible**: Supports multiple use cases like sign-up, password reset, and email validation testing.

## Installation

Install `cypress-temp-mail` using npm:

```bash 
npm install cypress-temp-mail --save-dev
```

## Usage

Add the import to your Cypress project's `cypress/support/e2e.js` (or `commands.js`) file:

```javascript
import 'cypress-temp-mail'
```

For TypeScript projects, add `"cypress-temp-mail"` to `compilerOptions.types` in your `tsconfig.json`.

## Generate a new temporary email:

```javascript
cy.createTempMail(mailingAddressLabel)  // Creates a new inbox and yields { address }

// Example
cy.createTempMail('signup' + Date.now()).then(({ address }) => {
  cy.get('#email').type(address)   // e.g. signup1730000000000@<mail.tm domain>
})
```

The label must be unique (an address cannot be created twice), so add a timestamp or random suffix. Omit it to get a random address.

## Check the inbox:

```javascript
cy.getMailbox()                                   // mails of the latest created inbox, newest first
cy.getMailbox({ minMessages: 1, timeout: 60000 }) // wait until at least one mail has arrived
cy.getMailbox({ address })                        // another inbox created earlier in the same spec
```

Options: `address` (default: latest inbox), `minMessages` (default `0`, no waiting), `timeout` (default `30000` ms), `interval` between polls (default `3000` ms).

Yields:

```javascript
{
  address: string,
  messageCount: number,
  messages: { from: string, timestamp: string, subject: string, message: string, html: string }[]
}
```

Example:

```javascript
cy.getMailbox({ minMessages: 1 }).then(({ messages }) => {
  expect(messages[0].subject).to.contain('Verify your account')
})
```

## Limits

Inboxes come from the free [mail.tm](https://mail.tm) service, so its limits apply:

- **No fixed number of inboxes**: any unique label gives a new address.
- **Rate limit per IP**: mail.tm allows about 30 requests a minute. `cy.createTempMail()` makes 3 requests, and `cy.getMailbox()` makes 1 per check plus 1 per mail read. In practice, expect around **5–10 new inboxes a minute**.
- **Automatic retry**: rate-limited requests (HTTP 429) wait and retry up to 5 times, so a busy suite slows down rather than failing.
- **Shared CI runners**: machines that share an outgoing IP share the limit.

Tips: create one inbox per test (not per assertion), and keep the polling `interval` at 3000 ms or more.

## Changelog

### [3.1.0] - 2026-10-28
- `getMailbox` can wait for mail: `minMessages`, `timeout` and `interval` options
- `getMailbox({ address })` reads any inbox created in the same spec
- Each inbox gets its own random password (3.0.x used a shared, guessable one)
- Messages include `from`, `timestamp`, `message` (text) and `html` (now a string)
- Rate-limited (HTTP 429) mail.tm requests are retried
- Removed the `@cemalgnlts/mailjs` dependency; `cypress` is now a peer dependency
- `createTempMail()` without a label generates a random address

### [3.0.1] - 2025-03-12
- Updated the temp email provider engine

### [1.0.0] - 2024-03-01
- Initial Release


## Contributing
Contributions are welcome! 🙏

## Keywords

This package is relevant for the following topics:

- Cypress
- Temporary Email
- Email Testing
- Cypress Plugin
- Email Validation
- End-to-End Testing
- Disposable Email
- Email Generator