mailtm-proxy

A TypeScript library for interacting with temporary email services like mail.tm and mail.gw, with proxy support to bypass rate limits.

Installation

npm install mailtm-proxy
# or
yarn add mailtm-proxy
# or
pnpm add mailtm-proxy

Features

• Create random email accounts
• Login to email accounts
• View message list
• View message details
• Delete messages
• Delete email accounts
• Proxy support for requests
• Support for multiple temporary email providers (mail.tm, mail.gw)
• Support for both ESM (ES Modules) and CJS (CommonJS)

Usage

Initialization

ES Modules (ESM)

// Using import with ESM projects
import { CustomMailjs } from 'mailtm-proxy';
// or default import
import CustomMailjs from 'mailtm-proxy';

// Initialize with default configuration (mail.tm, no proxy)
const mailjs = new CustomMailjs();

CommonJS (CJS)

// Using require with CommonJS projects
const { CustomMailjs } = require('mailtm-proxy');
// or default import
const CustomMailjs = require('mailtm-proxy');

// Initialize with default configuration (mail.tm, no proxy)
const mailjs = new CustomMailjs();

With Custom Configuration

// Configuration applies to both ESM and CJS
const mailjs = new CustomMailjs({
  provider: 'mail.gw', // 'mail.tm' or 'mail.gw'
  proxy: 'http://user:pass@ip:port' // Optional
});

Using with TypeScript

The library includes type definitions so you can use it without installing additional @types.

import { CustomMailjs } from 'mailtm-proxy';
import type { CreateRandomEmailResponse } from 'mailtm-proxy';

async function createEmail(): Promise<CreateRandomEmailResponse> {
  const mailjs = new CustomMailjs();
  return await mailjs.createRandomEmail();
}

Create Random Email Account

// Create email with default configuration
const account = await mailjs.createRandomEmail();
// { id: '...', email: '[email protected]', password: 'abc123' }

// Or create with custom configuration
const account = await mailjs.createRandomEmail({
  emailLength: 10, // Email length (default: 15)
  passwordLength: 10, // Password length (default: 7)
  emailPrefix: 'myemail' // Prefix for email address (optional)
});

Login to Account

const { token } = await mailjs.login({
  email: '[email protected]',
  password: 'your-password'
});

Get Message List

const messages = await mailjs.getMessages();

View Message Details

const messageDetails = await mailjs.getMessage('message-id');

Delete Message

await mailjs.deleteMessage('message-id');

Delete Account

await mailjs.deleteAccount('account-id');

Get Current Account Information

const accountInfo = await mailjs.me();

Node.js Compatibility

This library is bundled to support both modern and older environments:

• ES Modules: For modern projects, Node.js >= 14
• CommonJS: Backward compatibility with older Node.js versions

The package automatically detects and selects the appropriate format based on how you import/require it.

API Reference

CustomMailjs

constructor(options)

Initialize a new instance of CustomMailjs.

| Parameter | Type | Description | |---------|------|-------| | options | Object | Configuration options | | options.provider | string | Mail service provider ('mail.tm' or 'mail.gw'), default: 'mail.tm' | | options.proxy | string | Proxy URL to use for requests (optional) |

getDomains()

Get a list of available domains.

Returns: Promise<string[]> - List of domains.

createRandomEmail(params)

Create a random email account.

| Parameter | Type | Description | |---------|------|-------| | params | Object | Options | | params.emailLength | number | Email length, default: 15 | | params.passwordLength | number | Password length, default: 7 | | params.emailPrefix | string | Prefix for email address (optional) |

Returns: Promise<CreateRandomEmailResponse> - Created account information.

login(params)

Authenticate and get token.

| Parameter | Type | Description | |---------|------|-------| | params | Object | Login parameters | | params.email | string | Email address to login | | params.password | string | Password to login |

Returns: Promise<LoginResponse> - Authentication token.

getMessages()

Get all messages from authenticated account.

Returns: Promise<GetMessagesResponse[]> - List of messages.

getMessage(id)

Get a specific message by ID.

| Parameter | Type | Description | |---------|------|-------| | id | string | ID of message to retrieve |

Returns: Promise<GetMessageResponse> - Message details.

deleteMessage(id)

Delete a specific message by ID.

| Parameter | Type | Description | |---------|------|-------| | id | string | ID of message to delete |

Returns: Promise<void> - No data returned on success.

deleteAccount(id)

Delete authenticated account by ID.

| Parameter | Type | Description | |---------|------|-------| | id | string | ID of account to delete |

Returns: Promise<void> - No data returned on success.

me()

Get authenticated user account detailed information.

Returns: Promise<MeResponse> - Account details.