📧 send-email-easy

A simple and flexible email service wrapper supporting multiple providers with built-in template engine

✨ Features

• 📤 Support multiple email providers (Gmail, SendGrid, Mailgun)
• 🎨 Built-in Handlebars template engine
• 💌 Easy-to-use API
• 🔒 Type-safe with TypeScript
• ✅ Email validation
• 📎 Attachment support
• 🚀 Production-ready

📦 Installation

npm install send-email-easy

🚀 Quick Start

Using Gmail

import { EmailService } from 'send-email-easy';

const emailService = new EmailService({
  provider: 'gmail',
  from: 'your-email@gmail.com',
  auth: {
    user: 'your-email@gmail.com',
    pass: 'your-app-password', // Use App Password, not regular password
  },
});

// Send a simple email
await emailService.send({
  to: 'recipient@example.com',
  subject: 'Hello',
  html: '<h1>Welcome!</h1>',
});

Using SendGrid

const emailService = new EmailService({
  provider: 'sendgrid',
  from: 'noreply@example.com',
  apiKey: 'your-sendgrid-api-key',
});

await emailService.send({
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Hello there!</p>',
});

Using Mailgun

const emailService = new EmailService({
  provider: 'mailgun',
  from: 'noreply@yourdomain.com',
  apiKey: 'your-mailgun-api-key',
  domain: 'yourdomain.com',
});

await emailService.send({
  to: 'user@example.com',
  subject: 'Hello',
  text: 'This is a test email',
});

📋 Email Options

interface EmailOptions {
  to: string | string[];           // Recipient email(s)
  cc?: string | string[];          // CC recipients
  bcc?: string | string[];         // BCC recipients
  subject: string;                 // Email subject
  html?: string;                   // HTML content
  text?: string;                   // Plain text content
  template?: string;               // Template name
  templateData?: Record<string, any>; // Data for template
  attachments?: Attachment[];      // Email attachments
  replyTo?: string;                // Reply-to address
  from?: string;                   // Sender (defaults to config.from)
}

🎨 Template Usage

Register a Template

const template = `
  <h1>Hello {{name}}!</h1>
  <p>Welcome to {{company}}</p>
  <p>Your account is ready to use.</p>
`;

emailService.registerTemplate('welcome', template);

await emailService.send({
  to: 'user@example.com',
  subject: 'Welcome',
  template: 'welcome',
  templateData: {
    name: 'John',
    company: 'Acme Corp',
  },
});

Load Templates from Directory

// Create templates directory with .hbs files
await emailService.loadTemplates('./templates');

await emailService.send({
  to: 'user@example.com',
  subject: 'Reset Password',
  template: 'password-reset',
  templateData: {
    resetLink: 'https://example.com/reset/123',
    expiresIn: '24 hours',
  },
});

📎 Attachments

await emailService.send({
  to: 'user@example.com',
  subject: 'Document',
  html: '<p>Please find the attached document.</p>',
  attachments: [
    {
      filename: 'document.pdf',
      path: './documents/file.pdf',
    },
    {
      filename: 'image.png',
      content: Buffer.from('...'),
    },
  ],
});

✅ Validation

const isValid = await emailService.validate();
if (isValid) {
  console.log('Email service is configured correctly');
}

🔄 Response

All send methods return a SendResult object:

interface SendResult {
  success: boolean;
  messageId?: string;  // Provider's message ID
  error?: string;      // Error message if failed
}

📚 Examples

Batch Emails

const emails = ['user1@example.com', 'user2@example.com'];

for (const email of emails) {
  const result = await emailService.send({
    to: email,
    subject: 'Newsletter',
    template: 'newsletter',
    templateData: { month: 'September' },
  });

  if (result.success) {
    console.log(`Email sent to ${email}`);
  } else {
    console.error(`Failed to send to ${email}: ${result.error}`);
  }
}

Error Handling

const result = await emailService.send({
  to: 'user@example.com',
  subject: 'Test',
  html: '<p>Test email</p>',
});

if (!result.success) {
  console.error('Email failed:', result.error);
  // Handle error appropriately
}

🔐 Environment Variables

It's recommended to use environment variables for sensitive data:

# .env file
EMAIL_PROVIDER=gmail
EMAIL_FROM=your-email@gmail.com
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

const emailService = new EmailService({
  provider: process.env.EMAIL_PROVIDER as 'gmail' | 'sendgrid' | 'mailgun',
  from: process.env.EMAIL_FROM!,
  auth: {
    user: process.env.EMAIL_USER,
    pass: process.env.EMAIL_PASSWORD,
  },
});

🤝 Contributing

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

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Support

If you found this helpful, please consider giving it a ⭐ on GitHub!

📞 Contact

Have questions? Open an issue on GitHub

---

Made with ❤️ by jwafaDev