A Ruby gem for generating unique email aliases with timestamp-based suffixes. Perfect for testing, temporary accounts, service sign-ups, or organizing email workflows with automatically generated unique variations.
Features
- Unique Generation: Creates email aliases with timestamp-based suffixes to ensure uniqueness
- Flexible Configuration: Customize local parts, domains, and number of emails generated
- CLI & Library: Use from command line or integrate into your Ruby applications
- Clipboard Integration: Optionally copy generated emails to system clipboard (graceful fallback if unavailable)
- Cross-Platform: Works on Linux, macOS, and Windows
- Multiple Output Formats: Single email or semicolon-separated list for multiple emails
Installation
System Installation
gem install mailaliaser
Bundler
Add this line to your application's Gemfile:
gem 'mailaliaser'
And then execute:
bundle install
Optional: Clipboard Support
For clipboard functionality, install system dependencies:
Ubuntu/Debian:
sudo apt-get install xsel
# or for Wayland
sudo apt-get install wl-clipboard
macOS:
# Clipboard support included by default
Windows:
# Clipboard support included by default
Usage
Command Line Interface
Basic Usage
# Generate a single email alias
mailaliaser -l myname -d example.com
# Output: myname+1640995200001@example.com
# Generate multiple aliases
mailaliaser -l user -d test.org -n 5
# Output: user+1640995200001@test.org;user+1640995200002@test.org;...
Options
Option | Short | Description | Required | Default |
---|---|---|---|---|
--local-part |
-l |
Local part of email address | ✅ | - |
--domain |
-d |
Domain part of email address | ✅ | - |
--number |
-n |
Number of emails to generate | ❌ | 1 |
--clipboard |
-c |
Copy to system clipboard | ❌ | true |
--quiet |
-q |
Suppress output to stdout | ❌ | false |
--help |
-h |
Show help message | ❌ | - |
--version |
-v |
Show version information | ❌ | - |
Examples
# Generate 3 aliases for testing
mailaliaser -l testuser -d myapp.com -n 3
# Generate without clipboard (useful in CI/scripts)
mailaliaser -l api -d service.com --no-clipboard
# Generate quietly (only copy to clipboard)
mailaliaser -l silent -d example.org -q
# Generate for multiple services
mailaliaser -l newsletter -d news.com -n 10
Ruby Library
Basic Usage
require 'mailaliaser'
# Generate a single email
generator = Mailaliaser::Generator.new(
local_part: 'user',
domain: 'example.com'
)
email = generator.generate
puts email
# => "user+1640995200001@example.com"
Advanced Configuration
# Generate multiple emails with custom options
generator = Mailaliaser::Generator.new(
local_part: 'service',
domain: 'myapp.com',
number: 5,
clipboard: false, # Don't copy to clipboard
quiet: true # Don't output to stdout
)
emails = generator.generate
# Returns array of 5 unique email addresses
Integration Examples
# Testing scenarios
RSpec.describe 'User Registration' do
let(:test_email) do
Mailaliaser::Generator.new(
local_part: 'test',
domain: 'example.com',
clipboard: false,
quiet: true
).generate
end
it 'creates user with unique email' do
user = User.create(email: test_email)
expect(user).to be_valid
end
end
# Service integrations
class NewsletterSignup
def self.generate_test_email
Mailaliaser::Generator.new(
local_part: 'newsletter-test',
domain: ENV['TEST_DOMAIN'],
quiet: true
).generate
end
end
Use Cases
- Software Testing: Generate unique email addresses for test scenarios
- Service Sign-ups: Create temporary emails for service registrations
- Email Organization: Generate tagged emails for different purposes
- Load Testing: Create multiple unique email addresses for performance testing
- Development: Generate test data with guaranteed unique email addresses
- CI/CD Pipelines: Automated testing with unique email generation
Output Format
- Single email: Returns the email address directly
- Multiple emails: Returns semicolon-separated list for easy parsing
# Single email
"user+1640995200001@example.com"
# Multiple emails
"user+1640995200001@example.com;user+1640995200002@example.com;user+1640995200003@example.com"
Requirements
- Ruby >= 2.7
- Optional: System clipboard utilities (xsel, wl-clipboard, or built-in on macOS/Windows)
Development
After checking out the repo, run:
# Install dependencies
bundle install
# Run tests
bundle exec rake spec
# Run linting
bundle exec rake rubocop
# Run all checks (linting + tests)
bundle exec rake
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Make your changes
- Add tests for new functionality
- Ensure all tests pass (
bundle exec rake
) - Commit your changes (
git commit -am 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
Code Style
This project uses RuboCop for code style enforcement. Please ensure your code follows the established conventions by running:
bundle exec rake rubocop
Versioning
This gem follows Semantic Versioning. For available versions, see the releases page.
License
The gem is available as open source under the terms of the MIT License.
Support
- Issues: GitHub Issues
- Documentation: This README and inline code documentation
- Changelog: CHANGELOG.md
Made with ❤️ for the Ruby community