📧 Universal Email

A universal email library that supports multiple providers with a unified API. Send emails seamlessly across different services without changing your code.

✨ Features

• 🚀 Multiple Providers: Support for SendGrid, Mailgun, and UseSend
• 🔧 TypeScript First: Full TypeScript support with comprehensive type definitions
• 🎯 Unified API: Same interface across all providers
• ⚡ Zero Dependencies: Lightweight with minimal external dependencies
• 🔒 Environment Based: Easy configuration through environment variables
• 📦 Universal: Works in Node.js, Deno, and modern browsers

🚀 Quick Start

Installation

npm install universal-email
# or
pnpm add universal-email
# or
yarn add universal-email

Basic Usage

import { email } from 'universal-email';

// Send an email using the default provider
await email.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello World',
  text: 'Plain text content',
  html: '<h1>Hello World</h1>',
});

🔧 Configuration

Environment Variables

Create a .env file in your project root:

EMAIL_PROVIDER=sendgrid
SENDGRID_API_KEY=your_sendgrid_api_key
MAILGUN_API_KEY=your_mailgun_api_key
MAILGUN_DOMAIN=your_mailgun_domain
USESEND_API_KEY=your_usesend_api_key
USESEND_API_URL=https://app.usesend.com/api/v1

Provider-Specific Configuration

import { useEmail } from 'universal-email';

// Use a specific provider
const sendGrid = useEmail({ provider: 'sendgrid' });
const mailgun = useEmail({ provider: 'mailgun' });
const useSend = useEmail({ provider: 'usesend' });

// Send with specific provider
await sendGrid.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Sent via SendGrid',
  text: 'This email was sent using SendGrid!',
});

📚 Supported Providers

SendGrid

const sendGrid = useEmail({
  provider: 'sendgrid',
  apiKey: 'your_sendgrid_api_key',
});

Mailgun

const mailgun = useEmail({
  provider: 'mailgun',
  apiKey: 'your_mailgun_api_key',
  domain: 'your_mailgun_domain',
});

UseSend

const useSend = useEmail({
  provider: 'usesend',
  apiKey: 'your_usesend_api_key',
  baseUrl: 'your_usesend_api_url',
});

🎯 API Reference

useEmail(config?)it e packa

Creates an email provider instance.

Parameters:

• config.provider - Provider name ('sendgrid', 'mailgun', 'usesend')
• config.apiKey - API key for the provider
• config.domain - Domain (required for Mailgun)

Returns: EmailProvider instance

email.send(options)

Sends an email.

Parameters:

• options.from - Sender email address
• options.to - Recipient email address
• options.subject - Email subject
• options.text - Plain text content
• options.html - HTML content

Returns: Promise<void>

🛠️ Development

Prerequisites

• Node.js 18+
• pnpm (recommended)

Setup

# Clone the repository
git clone https://github.com/loickal/universal-email.git
cd universal-email

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys

Scripts

# Development
pnpm dev          # Start development server
pnpm play         # Run playground

# Building
pnpm build        # Build the library
pnpm clean        # Clean build artifacts

# Testing
pnpm test         # Run tests
pnpm test:watch   # Run tests in watch mode
pnpm test:coverage # Generate coverage report

# Code Quality
pnpm lint         # Run linter
pnpm lint:fix     # Fix linting issues
pnpm format       # Format code
pnpm typecheck    # Type check

# Release
pnpm release      # Build, test, and publish

📝 Examples

Basic Email

import { email } from 'universal-email';

await email.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome to MyApp!',
  text: "Welcome to MyApp! We're excited to have you.",
  html: "<h1>Welcome to MyApp!</h1><p>We're excited to have you.</p>",
});

Multiple Recipients

await email.send({
  from: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  subject: 'Newsletter',
  text: 'Check out our latest newsletter!',
  html: '<h1>Newsletter</h1><p>Check out our latest newsletter!</p>',
});

Error Handling

import { email } from 'universal-email';

try {
  await email.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Test Email',
    text: 'This is a test email',
  });
  console.log('Email sent successfully!');
} catch (error) {
  console.error('Failed to send email:', error);
}

🤝 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/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• SendGrid for their email API
• Mailgun for their email service
• UseSend for their email platform