✨ Features

• 📬 Create Inbox: Generate a unique, random email address and create an inbox.
• 🔍 Fetch Latest Messages: Retrieve the latest messages from the inbox.
• 📄 Read Message Content: Get the content (HTML and text) of a specific message.
• 🧹 Clean Up: Automatically delete messages and accounts post-test to keep your environment neat.

🚀 Installation

Install the package using npm:

npm install temp-disposable-email --save-dev

Install the package using yarn:

yarn add temp-disposable-email --dev

📖 Usage

1️⃣ Importing the package

To use the package, import the functions in your TypeScript or JavaScript project:

Using ES Modules (Recommended)

import { generateEmail, getRecentEmail } from 'temp-disposable-email';

Using CommonJS

const { generateEmail, getRecentEmail } = require('temp-disposable-email');

2️⃣ Create an Inbox

This function creates a new disposable email account using a random prefix or a specified one.

const { emailAddress, accountId } = await generateEmail(); // or pass a custom prefix
console.log('Created email address:', emailAddress);

Parameters

• prefix (Optional): The prefix for the new email address. If not provided, a random email will be generated.

Returns

• Promise<object>: An object containing email details like emailAddress, and accountId.

3️⃣ Fetch Recent Email

This function retrieves the latest message from the created inbox. You can specify polling options (timeout, interval, logging) for periodic checks when no message is immediately available.

const message = await getRecentEmail();
console.log('Message received:', message);

Parameters

• options (Optional): Polling options that can include:
  • maxWaitTime: Maximum polling time in milliseconds (default: 30,000ms).
  • waitInterval: Interval between polling attempts in milliseconds (default: 2,000ms).
  • logPolling: Enable or disable logging of polling attempts (default: false).
  • deleteAfterRead: Whether to delete the latest message after reading, helpful for parallel run

Returns

• Promise<object | null>: An object containing email details like from, to, subject, intro, text, html, createdAt, updatedAt and attachments.

🔧 Examples

Playwright Example

For using temp-disposable-email with Playwright, you can use it directly or with fixtures.

Using Playwright Fixtures (Recommended)

import { test, expect } from 'temp-disposable-email/playwright';

test('sign up flow', async ({ page, emailHelper }) => {
  const { emailAddress, accountId } = await emailHelper.generateEmail();
  
  // Your test code...
  
  const email = await emailHelper.getRecentEmail({ 
    accountId,
    maxWaitTime: 50000 
  });
  
  const code = await emailHelper.getVerificationCode(email?.text);
});

For complete examples, see the Playwright folder.

Cypress Example

For using temp-disposable-email with Cypress.

Import package

Import the package in your support/commands.{ts|js}:

import 'temp-disposable-email/cypress';

TypeScript Setup

Add the type reference at the top of your test files:

/// <reference types="temp-disposable-email/cypress" />

Example Test

See the complete example in the Cypress folder.

it('[Custom Command] - Sign up - Check email content and subject', () => {
  // Create a dynamic email address
  cy.generateEmail(`cypress_${Math.random().toString().substr(2, 9)}`).then(
    ({ emailAddress, accountId }) => {
      // Navigate to the sign-up page
      cy.visit('https://app.postdrop.io/signup');

      // Fill in the sign-up form
      cy.get('#email').type(emailAddress);
      cy.get('#password').type('Pass@123');
      cy.get('#name').type('testMMMM');
      cy.get('#company').type('testMMMMc');
      cy.get('#btn-signup').click();
      // Verify the success message is displayed
      cy.contains('h1', 'Thanks for signing up!').should('be.visible');
      // Fetch the verification email
      cy.getRecentEmail({
        accountId, // Pass accountId for proper cleanup
        maxWaitTime: 80000,
        waitInterval: 1000,
        deleteAfterRead: true,
        logPolling: true,
      }).then((mailbox) => {
        // Assert email subject and content
        expect(mailbox?.subject).to.contain('Postdrop - Verify Account');
        expect(mailbox?.html[0]).to.contain(
          'please verify your account by clicking the button'
        );
      });
    }
  );
});

Node Example

Here's a complete example of creating an inbox, retrieving a message, and cleaning up:

import { generateEmail, getRecentEmail } from 'temp-disposable-email';

async function run() {
  try {
    // Create a new inbox
    const { emailAddress, accountId } = await generateEmail();
    console.log('Created email:', emailAddress);

    // Get the first available message from the inbox
    const message = await getRecentEmail({
      accountId, // Pass accountId for automatic cleanup
      maxWaitTime: 50000,
      waitInterval: 3000,
      logPolling: true,
    });
    console.log('Received message:', message);
  } catch (error) {
    console.error('Error:', error);
  }
}

run();

📚 API Documentation

generateEmail(prefix?: string): Promise<string>

• Description: Creates a disposable inbox with a randomly generated or provided prefix.
• Parameters:
  • prefix (Optional): A custom prefix for the email address.
• Returns: A promise that resolves to the generated email address.

{
  emailAddress: string;
  accountId: string;
}

getRecentEmail(options?: GetEmailOptions): Promise<any | null>

• Description: Retrieves the latest message from the inbox, polling if necessary.
• Parameters:
  • options (Optional): Polling configuration for waiting for messages. See GetEmailOptions.
    • accountId (Optional): Account ID for cleanup after reading. Recommended to prevent resource leaks.
    • maxWaitTime (Optional): The maximum time to wait for messages (in milliseconds).
    • waitInterval (Optional): The interval between polling attempts (in milliseconds).
    • logPolling (Optional): Whether to log each polling attempt for debugging purposes.
    • deleteAfterRead (Optional): Whether to delete messages after reading
• Returns: A promise that resolves to the message content (or null if no messages are found).

{
  from: { address: string };
  to: { address: string }[];
  subject: string;
  intro: string;
  text: string;
  html: string[];
  createdAt: string;
  updatedAt: string;
  attachments: {
    title: string;
    data: Buffer;
  }[];
}

📄 License

This project is licensed under the MIT License.