@ekaone/mask-email

A lightweight, zero-dependency TypeScript library for masking email addresses.

Features

✨ Lightweight - Zero dependencies
🔒 Privacy-focused - Mask sensitive email information
📦 TypeScript - Full type safety and IntelliSense support
⚙️ Customizable - Flexible masking options
🎯 Simple API - Easy to use with sensible defaults

Installation

npm install @ekaone/mask-email

yarn add @ekaone/mask-email

pnpm add @ekaone/mask-email

Quick Start

import { maskEmail, maskEmailBatch, validateEmail, isValidEmail, anonymizeEmail, anonymizeEmailBatch } from '@ekaone/mask-email';

maskEmail('[email protected]');
// Output: 'ek********@gmail.com'

// Batch masking
maskEmailBatch(['[email protected]', '[email protected]']);
// Output: ['jo**@example.com', 'ja**@company.com']

Usage Examples

Basic Usage

import { maskEmail } from '@ekaone/mask-email';

// Default masking (shows first 2 characters)
maskEmail('[email protected]');
// Output: 'jo******@example.com'

maskEmail('[email protected]');
// Output: 'ad***@company.com'

Custom Visible Characters

Control how many characters remain visible at the beginning of the username:

// Show first 4 characters
maskEmail('[email protected]', { visibleChars: 4 });
// Output: 'ekao******@gmail.com'

// Show only 1 character
maskEmail('[email protected]', { visibleChars: 1 });
// Output: 'e*********@gmail.com'

Custom Mask Character

Change the masking character from the default *:

maskEmail('[email protected]', { maskChar: '#' });
// Output: 'us##@example.com'

maskEmail('[email protected]', { maskChar: '•' });
// Output: 'us••@example.com'

maskEmail('[email protected]', { maskChar: '-' });
// Output: '[email protected]'

Domain Masking

Mask the domain part of the email as well:

// Mask domain
maskEmail('[email protected]', { maskDomain: true });
// Output: 'us**@g****.com'

// Works with subdomains
maskEmail('[email protected]', { maskDomain: true });
// Output: 'co*****@m***.g*****.com'

Batch Masking

Process multiple emails at once with the same options:

import { maskEmailBatch } from '@ekaone/mask-email';

// Basic batch masking
const emails = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

maskEmailBatch(emails);
// Output: ['jo******@example.com', 'ja********@company.com', 'ad***@site.org']

// Batch with custom options
maskEmailBatch(emails, { visibleChars: 3, maskChar: '#' });
// Output: ['joh#####@example.com', 'jan#######@company.com', 'adm##@site.org']

// Batch with domain masking
maskEmailBatch(emails, { maskDomain: true });
// Output: ['jo******@ex******.com', 'ja********@co******.com', 'ad***@si**.org']

Viewable Mode

Return the original email without masking (useful for admin views):

maskEmail('[email protected]', { viewable: true });
// Output: '[email protected]'

Combined Options

Mix and match options for custom masking behavior:

maskEmail('[email protected]', {
  visibleChars: 3,
  maskChar: '-',
  maskDomain: true
});
// Output: '[email protected]'

maskEmail('[email protected]', {
  visibleChars: 1,
  maskChar: '*',
  maskDomain: true
});
// Output: 'a****@m***.c******.com'

Email Anonymization

Replace the username with a random identifier for complete privacy:

import { anonymizeEmail, anonymizeEmailBatch } from '@ekaone/mask-email';

// Basic anonymization
anonymizeEmail('[email protected]');
// Output: 'user_a1b2c3@*****.com'

// Custom prefix and ID length
anonymizeEmail('[email protected]', { prefix: 'anon', idLength: 8 });
// Output: 'anon_x7y2k9m4@*******.com'

// Keep domain visible
anonymizeEmail('[email protected]', { maskDomain: false });
// Output: '[email protected]'

// Batch anonymization
const emails = ['[email protected]', '[email protected]'];
anonymizeEmailBatch(emails);
// Output: ['user_a1b2c3@****.com', 'user_x7y8z9@****.com']

Batch Email Masking

Process multiple emails with the same options:

import { maskEmailBatch } from '@ekaone/mask-email';

const emails = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

// Basic batch masking
maskEmailBatch(emails);
// Output: ['jo******@example.com', 'ja********@company.com', 'ad***@site.org']

// Batch with custom options
maskEmailBatch(emails, { visibleChars: 3, maskChar: '#' });
// Output: ['joh#####@example.com', 'jan#######@company.com', 'adm##@site.org']

// Batch with domain masking
maskEmailBatch(emails, { maskDomain: true });
// Output: ['jo******@ex******.com', 'ja********@co******.com', 'ad***@si**.org']

Email Validation

Validate email format and optionally mask valid emails:

import { validateEmail, isValidEmail } from '@ekaone/mask-email';

// Validate and get masked email
const result = validateEmail('[email protected]');
// Returns: { valid: true, original: 'test@example.com', masked: 'te**@example.com' }

// Validation with custom masking options
const custom = validateEmail('[email protected]', { visibleChars: 3 });
// Returns: { valid: true, original: 'user@test.com', masked: 'use*@test.com' }

// Invalid email
const invalid = validateEmail('invalid-email');
// Returns: { valid: false, original: 'invalid-email', masked: null, error: 'Invalid email format' }

// Quick boolean check
isValidEmail('[email protected]'); // true
isValidEmail('invalid'); // false
isValidEmail(''); // false

API Reference

`maskEmailBatch(emails, options?)`

Masks an array of email addresses with the same options applied to each email.

Parameters

emails (string[]) - Array of email addresses to mask
options (EmailOptions, optional) - Configuration options (same as maskEmail)

Returns

(string[]) - Array of masked email addresses

Example

const emails = ['[email protected]', '[email protected]'];
maskEmailBatch(emails, { visibleChars: 1 });
// Output: ['u***@test.com', 'u***@demo.com']

`maskEmail(email, options?)`

Masks an email address according to the provided options.

Parameters

email (string) - The email address to mask
options (EmailOptions, optional) - Configuration options

Options

Option	Type	Default	Description
`maskChar`	`string`	`'*'`	Character used for masking
`visibleChars`	`number`	`2`	Number of characters visible at the beginning
`visibleCharsEnd`	`number`	`0`	Number of characters visible at the end
`maskPercentage`	`number`	-	Mask based on percentage (0-100), takes precedence over visibleChars
`maskDomain`	`boolean \| 'full'`	`false`	Mask domain: `true`/'partial' masks parts keeping TLD, `'full'` masks entire domain
`viewable`	`boolean`	`false`	Return original email without masking

Returns

(string) - The masked email address

TypeScript Types

interface EmailOptions {
  /** Character used for masking (default: '*') */
  maskChar?: string;
  /** Number of characters visible at the beginning (default: 2) */
  visibleChars?: number;
  /** Number of characters visible at the end (default: 0) */
  visibleCharsEnd?: number;
  /** Mask based on percentage (0-100), takes precedence over visibleChars */
  maskPercentage?: number;
  /** Return original email without masking (default: false) */
  viewable?: boolean;
  /** Mask domain: true/partial keeps TLD visible, 'full' masks entire domain (default: false) */
  maskDomain?: boolean | 'full';
}

`validateEmail(email, options?)`

Validates an email address and returns a result object with validation status and optional masked email.

Parameters

email (string) - The email address to validate
options (EmailOptions, optional) - Masking options applied if email is valid

Returns

(EmailValidationResult) - Object containing:
- valid (boolean) - Whether the email format is valid
- original (string) - The original email address
- masked (string | null) - Masked email if valid, null if invalid
- error (string, optional) - Error message if validation failed

Example

const result = validateEmail('[email protected]');
// Returns: { valid: true, original: 'test@example.com', masked: 'te**@example.com' }

const invalid = validateEmail('invalid-email');
// Returns: { valid: false, original: 'invalid-email', masked: null, error: 'Invalid email format' }

TypeScript Types

interface EmailValidationResult {
  valid: boolean;
  original: string;
  masked: string | null;
  error?: string;
}

`isValidEmail(email)`

Quick boolean validation without masking. Returns true if the email is valid, false otherwise.

Parameters

email (string) - The email address to validate

Returns

(boolean) - true if valid, false otherwise

Example

isValidEmail('[email protected]'); // true
isValidEmail('invalid'); // false
isValidEmail(''); // false

`anonymizeEmail(email, options?)`

Anonymizes an email by replacing the username with a random identifier. Useful for complete privacy protection.

Parameters

email (string) - The email address to anonymize
options (AnonymizeOptions, optional) - Anonymization options

Options

Option	Type	Default	Description
`prefix`	`string`	`'user'`	Prefix for the anonymous identifier
`idLength`	`number`	`6`	Length of the random identifier
`maskDomain`	`boolean`	`true`	Whether to mask the domain part

Returns

(string) - Anonymized email address

Example

anonymizeEmail('[email protected]');
// Output: 'user_a1b2c3@*****.com'

anonymizeEmail('[email protected]', { prefix: 'anon', idLength: 8 });
// Output: 'anon_x7y2k9m4@*******.com'

anonymizeEmail('[email protected]', { maskDomain: false });
// Output: '[email protected]'

TypeScript Types

interface AnonymizeOptions {
  prefix?: string;
  idLength?: number;
  maskDomain?: boolean;
}

`anonymizeEmailBatch(emails, options?)`

Batch anonymize multiple email addresses with the same options.

Parameters

emails (string[]) - Array of email addresses to anonymize
options (AnonymizeOptions, optional) - Anonymization options applied to all emails

Returns

(string[]) - Array of anonymized email addresses

Example

const emails = ['[email protected]', '[email protected]'];
anonymizeEmailBatch(emails);
// Output: ['user_a1b2c3@****.com', 'user_x7y8z9@****.com']

anonymizeEmailBatch(emails, { prefix: 'anon' });
// Output: ['anon_k3m9p2@****.com', 'anon_q5n8r4@****.com']

Real-World Use Cases

Display Emails in UI

const userEmail = '[email protected]';
const displayEmail = maskEmail(userEmail);

console.log(`Confirmation sent to: ${displayEmail}`);
// Output: "Confirmation sent to: cu******@company.com"

Logging Sensitive Data

const emails = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

emails.forEach(email => {
  console.log('Processing:', maskEmail(email, { visibleChars: 3 }));
});
// Output:
// Processing: adm**@site.com
// Processing: use****@example.com
// Processing: con****@business.org

Role-Based Masking

function getUserEmailForDisplay(email: string, userRole: string) {
  if (userRole === 'admin') {
    return maskEmail(email, { viewable: true });
  } else if (userRole === 'moderator') {
    return maskEmail(email, { visibleChars: 4, maskDomain: false });
  } else {
    return maskEmail(email, { visibleChars: 2, maskDomain: true });
  }
}

console.log(getUserEmailForDisplay('[email protected]', 'admin'));
// Output: '[email protected]'

console.log(getUserEmailForDisplay('[email protected]', 'moderator'));
// Output: '[email protected]'

console.log(getUserEmailForDisplay('[email protected]', 'user'));
// Output: 'jo**@e******.com'

Privacy-Compliant Email Display

// Show masked email in public profiles
function displayPublicProfile(user: { name: string; email: string }) {
  return {
    name: user.name,
    email: maskEmail(user.email, { maskDomain: true })
  };
}

const profile = displayPublicProfile({
  name: 'John Doe',
  email: '[email protected]'
});

console.log(profile);
// Output: { name: 'John Doe', email: 'jo******@e******.com' }

Edge Cases

The library handles various edge cases gracefully:

// Very short usernames
maskEmail('[email protected]', { visibleChars: 2 });
// Output: '[email protected]' (shows all available characters)

// Invalid email format (no @ symbol)
maskEmail('notanemail');
// Output: 'notanemail' (returns as-is)

// Empty or null values
maskEmail('');
// Output: ''

maskEmail(null);
// Output: null

// Multiple @ symbols (technically invalid but handled)
maskEmail('user@[email protected]');
// Output: 'us*******@domain.com' (uses last @ as separator)

// Subdomains
maskEmail('[email protected]', { maskDomain: true });
// Output: 'us**@m***.g*****.com'

Browser Support

This library works in all modern browsers and Node.js environments that support ES2015+.

✅ Chrome (latest)
✅ Firefox (latest)
✅ Safari (latest)
✅ Edge (latest)
✅ Node.js 14+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.cursor/skills/mask-email		.cursor/skills/mask-email
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@ekaone/mask-email

Features

Installation

Quick Start

Usage Examples

Basic Usage

Custom Visible Characters

Custom Mask Character

Domain Masking

Batch Masking

Viewable Mode

Combined Options

Email Anonymization

Batch Email Masking

Email Validation

API Reference

maskEmailBatch(emails, options?)

Parameters

Returns

Example

maskEmail(email, options?)

Parameters

Options

Returns

TypeScript Types

validateEmail(email, options?)

Parameters

Returns

Example

TypeScript Types

isValidEmail(email)

Parameters

Returns

Example

anonymizeEmail(email, options?)

Parameters

Options

Returns

Example

TypeScript Types

anonymizeEmailBatch(emails, options?)

Parameters

Returns

Example

Real-World Use Cases

Display Emails in UI

Logging Sensitive Data

Role-Based Masking

Privacy-Compliant Email Display

Edge Cases

Browser Support

Contributing

License

Links

Related Packages

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`maskEmailBatch(emails, options?)`

`maskEmail(email, options?)`

`validateEmail(email, options?)`

`isValidEmail(email)`

`anonymizeEmail(email, options?)`

`anonymizeEmailBatch(emails, options?)`

Packages