Temp Disposable Email ๐ง
A lightweight, efficient npm package for creating and managing temporary disposable email accounts.
โจ Features |
๐ Install |
๐ Usage |
๐ง Examples |
๐ API Documentation
---
## โจ 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:
```bash
npm install temp-disposable-email --save-dev
```
Install the package using yarn:
```bash
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)
```typescript
import { generateEmail, getRecentEmail } from 'temp-disposable-email';
```
#### Using CommonJS
```javascript
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.
```typescript
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`: 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.
```typescript
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`: 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)
```typescript
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](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/tree/master/examples/playwright).
### **Cypress Example**
For using temp-disposable-email with Cypress.
#### Import package
Import the package in your `support/commands.{ts|js}`:
```typescript
import 'temp-disposable-email/cypress';
```
#### TypeScript Setup
Add the type reference at the top of your test files:
```typescript
///
## ๐ API Documentation
### `generateEmail(prefix?: string): Promise`
- **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.
```json
{
emailAddress: string;
accountId: string;
}
```
### `getRecentEmail(options?: GetEmailOptions): Promise`
- **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).
```json
{
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.
