Package Exports
- email-deliverability-tester
- email-deliverability-tester/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (email-deliverability-tester) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Email Deliverability Tester
A comprehensive email deliverability testing utility that validates email format, domain existence, DNS records, and tests actual delivery via AWS SES and SMTP. Perfect for applications that need to verify email addresses before sending important communications.
๐ Features
- โ Email Format Validation - Validates email address format using regex
- ๐ Domain Verification - Checks if the email domain exists
- ๐ฎ MX Record Lookup - Retrieves and validates MX records for the domain
- ๐ก๏ธ SPF Record Check - Looks up SPF records for sender policy validation
- ๐ DMARC Record Check - Verifies DMARC policy records
- ๐ค AWS SES Integration - Send emails and test delivery via Amazon SES
- ๐ง SMTP Support - Send emails and test delivery via custom SMTP servers
- ๐ Batch Processing - Test multiple email addresses at once
- ๏ฟฝ Auto-Configuration - Automatically detects AWS SES and SMTP settings from environment variables
- ๐ Attachment Support - Send emails with file attachments
- ๐ฅ Multiple Recipients - Support for CC, BCC, and multiple TO addresses
- ๏ฟฝ๐ก Smart Recommendations - Provides actionable recommendations based on test results
- ๐ Performance Tracking - Measures test duration and provides batch statistics
- ๐ฏ TypeScript Support - Full TypeScript definitions included
- ๐ฅ๏ธ CLI Tool - Command-line interface for quick testing and sending
- โก Zero-Config Setup - Works out of the box with environment variables
๐ฆ Installation
npm install email-deliverability-tester
๐ง Quick Start
Basic Usage (Auto-Configuration)
The simplest way to use the package is with environment variables. The system will automatically detect your email provider configuration:
import { EmailSender, quickSendEmail } from 'email-deliverability-tester';
// Auto-detects configuration from environment variables
const result = await quickSendEmail({
to: 'recipient@example.com',
subject: 'Hello World',
text: 'This email was sent with auto-detected configuration!'
});
console.log(`Email sent: ${result.success}`);
Email Validation Only
import { quickEmailValidation } from 'email-deliverability-tester';
// Quick email validation (no actual delivery test)
const result = await quickEmailValidation('user@example.com');
console.log(`Email is ${result.isValid ? 'valid' : 'invalid'}`);
console.log(`Domain exists: ${result.domainExists}`);
console.log(`MX records found: ${result.mxRecords.length}`);
Manual Configuration
For more control, you can provide explicit configuration:
import { EmailSender, EmailDeliverabilityTester } from 'email-deliverability-tester';
// Manual AWS SES configuration
const sender = new EmailSender({
aws: {
accessKeyId: 'your-aws-access-key',
secretAccessKey: 'your-aws-secret-key',
region: 'us-east-1'
},
defaultFrom: 'your-from-email@domain.com'
});
const result = await sender.sendWithSes({
to: 'recipient@example.com',
subject: 'Manual Configuration Test',
text: 'This email was sent with manual configuration.'
});
AWS SES Integration
import { EmailDeliverabilityTester } from 'email-deliverability-tester';
const tester = new EmailDeliverabilityTester({
accessKeyId: 'your-aws-access-key',
secretAccessKey: 'your-aws-secret-key',
region: 'us-east-1'
}, 'your-from-email@domain.com');
const result = await tester.testEmailDeliverability({
email: 'recipient@example.com',
provider: 'aws-ses',
skipActualDelivery: false // Set to true to skip sending actual email
});
console.log(`Delivery test: ${result.deliverabilityTests.awsSes?.success}`);
SMTP Testing
import { quickEmailTestWithSmtp } from 'email-deliverability-tester';
const smtpConfig = {
host: 'smtp.gmail.com',
port: 587,
secure: false,
auth: {
user: 'your-email@gmail.com',
pass: 'your-app-password'
}
};
const result = await quickEmailTestWithSmtp('recipient@example.com', smtpConfig);
console.log(`SMTP test: ${result.deliverabilityTests.smtp?.success}`);
๐ฅ๏ธ CLI Usage
After installation, you can use the CLI tool:
# Install globally for CLI access
npm install -g email-deliverability-tester
# Test a single email (validation only)
email-test --email test@example.com --validate
# Test with AWS SES
email-test --email test@example.com --provider aws-ses
# Test multiple emails
email-test --emails "test1@example.com,test2@example.com" --validate
# Test with custom SMTP
email-test --email test@example.com --provider smtp \
--smtp-host smtp.gmail.com --smtp-port 587 \
--smtp-user your@gmail.com --smtp-pass app-password
CLI Options
Options:
--email, -e <email> Single email address to test
--emails <email1,email2> Multiple email addresses (comma-separated)
--provider, -p <provider> Email provider: aws-ses, smtp, both (default: both)
--smtp-host <host> SMTP server hostname
--smtp-port <port> SMTP server port (default: 587)
--smtp-user <username> SMTP username
--smtp-pass <password> SMTP password
--smtp-secure <true|false> Use secure connection (default: false)
--test-subject <subject> Custom test email subject
--test-message <message> Custom test email message
--skip-delivery Skip actual email delivery (validation only)
--validate, -v Validation mode (same as --skip-delivery)
--help, -h Show help message
๐ Environment Variables
The package automatically detects configuration from environment variables, making setup effortless:
AWS SES Configuration (Auto-detected)
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_REGION=us-east-1
AWS_EMAIL_FROM=no-reply@yourdomain.com
SMTP Configuration (Auto-detected)
# Standard SMTP variables
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_smtp_username
SMTP_PASS=your_smtp_password
SMTP_SECURE=false
# Alternative variable names also supported
SMPTP_HOST=smtp.gmail.com
SMPT_USER=your_smtp_username
SMPT_PASSWORD=your_smtp_password
SMPT_EMAIL_FROM=smtp@yourdomain.com
General Configuration
EMAIL_FROM=default@yourdomain.com
Usage with Auto-Detection
With environment variables set up, you can use the package without any configuration:
import { EmailSender, quickSendEmail } from 'email-deliverability-tester';
// Simple email sending - auto-detects provider
const result = await quickSendEmail({
to: 'recipient@example.com',
subject: 'Auto-detected Configuration',
text: 'This email uses auto-detected SMTP or AWS SES configuration!'
});
// Advanced email with attachments
const sender = new EmailSender(); // Auto-detects from env vars
const advancedResult = await sender.send({
to: ['user1@example.com', 'user2@example.com'],
cc: 'manager@example.com',
subject: 'Monthly Report',
html: '<h1>Report</h1><p>Please find the monthly report attached.</p>',
attachments: [
{
filename: 'report.pdf',
content: reportBuffer,
contentType: 'application/pdf'
}
]
});
Batch Email Validation
import { batchEmailValidation } from 'email-deliverability-tester';
const emails = ['user1@example.com', 'user2@gmail.com', 'invalid-email'];
const result = await batchEmailValidation(emails);
console.log(`Valid emails: ${result.validEmails.length}`);
console.log(`Invalid emails: ${result.invalidEmails.length}`);
๐ API Reference
EmailDeliverabilityTester
Main class for email deliverability testing.
Constructor
new EmailDeliverabilityTester(awsConfig?, fromEmail?)
awsConfig
(optional): AWS SES configuration objectfromEmail
(optional): Default from email address
Methods
testEmailDeliverability(config: EmailTestConfig): Promise<EmailTestResult>
Test a single email address for deliverability.
testMultipleEmails(configs: EmailTestConfig[]): Promise<BatchTestResult>
Test multiple email addresses in batch.
validateEmails(emails: string[]): Promise<EmailValidationResult>
Validate multiple emails without sending test emails.
isAwsSesConfigured(): boolean
Check if AWS SES is properly configured.
setDefaultFromEmail(email: string): void
Set the default from email address.
Types
EmailTestConfig
interface EmailTestConfig {
email: string;
provider?: 'aws-ses' | 'smtp' | 'both';
smtpConfig?: SmtpConfig;
testMessage?: TestMessage;
skipActualDelivery?: boolean;
}
EmailTestResult
interface EmailTestResult {
email: string;
isValid: boolean;
domainExists: boolean;
mxRecords: MxRecord[];
spfRecord?: string;
dmarcRecord?: string;
deliverabilityTests: DeliveryTestResults;
recommendations: string[];
testDuration?: number;
}
SmtpConfig
interface SmtpConfig {
host: string;
port: number;
secure: boolean;
auth?: {
user: string;
pass: string;
};
}
๐ง Advanced Usage
Custom Email Service Integration
import { EmailDeliverabilityTester } from 'email-deliverability-tester';
class EnhancedEmailService {
private tester: EmailDeliverabilityTester;
constructor() {
this.tester = new EmailDeliverabilityTester();
}
async sendWithValidation(email: string, content: any) {
// Pre-validate email
const validation = await this.tester.testEmailDeliverability({
email,
skipActualDelivery: true
});
if (!validation.isValid || !validation.domainExists) {
throw new Error(`Invalid email: ${validation.recommendations.join(', ')}`);
}
// Proceed with sending email
return this.sendEmail(email, content);
}
private async sendEmail(email: string, content: any) {
// Your email sending logic here
console.log(`Sending email to ${email}`);
}
}
Bulk Email List Validation
import { EmailDeliverabilityTester } from 'email-deliverability-tester';
async function validateEmailList(emails: string[]) {
const tester = new EmailDeliverabilityTester();
console.log(`Validating ${emails.length} emails...`);
const result = await tester.validateEmails(emails);
console.log(`โ
Valid: ${result.validEmails.length}`);
console.log(`โ Invalid: ${result.invalidEmails.length}`);
// Log details for invalid emails
result.invalidEmails.forEach(item => {
console.log(`โ ${item.email}: ${item.issues.join(', ')}`);
});
return result.validEmails;
}
๐งช Testing
Run the test suite:
npm test
Run tests in watch mode:
npm run test:watch
๐ Examples
Check out the examples directory for more usage examples:
- Basic Usage - Simple validation and testing examples
- Advanced Usage - AWS SES integration and complex scenarios
Run examples:
npm run example:basic
npm run example:advanced
๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Issues
If you encounter any issues or have feature requests, please create an issue on GitHub.
๐ Changelog
See CHANGELOG.md for a list of changes and version history.
๐ Acknowledgments
- Built with Node.js and TypeScript
- Email delivery powered by AWS SES and Nodemailer
- DNS lookups using Node.js built-in
dns
module
Made with โค๏ธ for better email deliverability testing