https://github.com/srttk/email
Type safe/maintainable Email + Template solution 📬
https://github.com/srttk/email
email node-mailer nodejs smtp tempaltes
Last synced: 4 months ago
JSON representation
Type safe/maintainable Email + Template solution 📬
- Host: GitHub
- URL: https://github.com/srttk/email
- Owner: srttk
- License: mit
- Created: 2024-12-05T05:12:44.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-25T12:57:26.000Z (about 1 year ago)
- Last Synced: 2025-10-03T23:29:32.904Z (4 months ago)
- Topics: email, node-mailer, nodejs, smtp, tempaltes
- Language: TypeScript
- Homepage:
- Size: 68.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# @srttk/email 📬
A type-safe email templating and sending solution for Node.js applications. This package helps you manage email templates and send emails with proper TypeScript support.
## Features
- 🔒 Type-safe email templates
- 📝 Support for HTML and plain text emails
- 🎨 Template compilation with data binding
- ⚡ Built-in HTML to text conversion
- 🛠️ Customizable template engine settings
## Installation
```bash
npm install @srttk/email nodemailer
```
## Quick Start
### 1. Define Email Templates
Create type-safe email templates with full TypeScript support:
```typescript
import { IEmailTemplateRecord } from "@srttk/email";
// Define a template with typed data requirements
const welcome: IEmailTemplateRecord<{ name: string }> = {
subject: "Welcome to Our Platform",
body: (data) => `
Welcome ${data.name}!
We're excited to have you on board.
`,
};
// Create a template collection
const templates = new EmailTemplateCollection({ welcome });
```
### 2. Set Up the Mailer
Configure your email transport settings:
```typescript
import { Mailer } from "@srttk/email";
const mailer = new Mailer({
templates: templates,
config: {
frommail: "noreply@yourcompany.com",
fromname: "Your Company",
host: "smtp.yourprovider.com",
port: 587,
username: "your-username",
password: "your-password",
},
});
```
### 3. Send Emails
Send emails using your templates:
```typescript
// Using templates
await mailer
.useTemplate("welcome", { name: "John Doe" })
.send({ to: "john@example.com" });
// Or create without sending
const emailData = mailer
.useTemplate("welcome", { name: "John Doe" })
.create({ to: "john@example.com" });
```
## Advanced Usage
### Custom Template Files
You can use external template files:
```typescript
const passwordReset: IEmailTemplateRecord<{ resetLink: string }> = {
subject: "Password Reset Request",
body: { path: "./templates/password-reset.html" },
};
```
### Template Collection Options
Configure template collection settings:
```typescript
const templates = new EmailTemplateCollection(
{ welcome },
{
templatePath: "./email-templates",
defaultExtension: ".html",
htmlToText: customHtmlToTextParser, // Optional custom parser
}
);
```
### Custom Transport
Use a custom nodemailer transport:
```typescript
const customTransport = createTransport({
// Your custom transport configuration
});
mailer.setTransport(customTransport);
```
### Test Connection
Verify your email configuration:
```typescript
const isConnected = await mailer.testConnection();
if (isConnected) {
console.log("Email service is ready!");
}
```
## API Reference
### `EmailTemplateCollection`
- `constructor(templates, options?)`: Create a new template collection
- `compile(name, data?)`: Compile a template with data
- `setHtmlToText(parser)`: Set custom HTML to text parser
### `Mailer`
- `constructor(settings?)`: Create a new mailer instance
- `setup(config)`: Configure SMTP settings
- `testConnection()`: Test SMTP connection
- `send(options)`: Send an email
- `useTemplate(name, data?)`: Use a template for sending
- `setTransport(transport)`: Set custom nodemailer transport
## Type Definitions
```typescript
interface IEmailTemplateRecord {
subject: string | ((data: T) => string);
body: string | ((data: T) => string) | { path: string };
}
interface SetupOptions {
host: string;
port: string | number;
secure?: boolean;
username: string;
password: string;
fromname?: string;
frommail?: string;
}
```
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.