@geekmidas/emailkit

Type-safe email client with SMTP support and React templates.

Features

- Type-Safe Templates: Templates are provided at construction time with full TypeScript inference for both template names and their corresponding props
- SMTP Support: Works with any SMTP server via nodemailer configuration
- React Templates: Uses react-dom/server to render React components to HTML

Installation

``bash
pnpm add @geekmidas/emailkit
`

Quick Start

`typescript
import { createEmailClient } from '@geekmidas/emailkit';

// Define your templates with props
const WelcomeEmail = ({ name, confirmationUrl }: {
name: string;
confirmationUrl?: string;
}) => (


// Send email with full type safety
await client.sendTemplate('welcome', {
from: 'welcome@example.com',
to: 'user@example.com',
subject: 'Welcome to our service!',
props: {
name: 'John Doe',
confirmationUrl: 'https://example.com/confirm/123',
},
});
`

API Reference

$3

Creates a new email client with type-safe template support.

#### Configuration

`typescript
interface EmailClientConfig {
smtp: SMTPConfig;
templates: T;
defaults?: {
from?: string | Address;
replyTo?: string | Address;
};
}

interface SMTPConfig {
host: string;
port: number;
secure?: boolean;
auth?: {
user: string;
pass: string;
};
tls?: {
rejectUnauthorized?: boolean;
servername?: string;
};
pool?: boolean;
maxConnections?: number;
maxMessages?: number;
rateLimit?: number;
logger?: boolean;
debug?: boolean;
}
`

$3

#### send(options: PlainEmailOptions): Promise

Send a plain text or HTML email.

`typescript
await client.send({
from: 'info@example.com',
to: 'user@example.com',
subject: 'Plain email',
text: 'This is a plain text email',
html: '

This is an HTML email

#### sendTemplate(template: K, options): Promise

Send an email using a React template with type-safe props.

`typescript
await client.sendTemplate('welcome', {
from: 'welcome@example.com',
to: 'user@example.com',
subject: 'Welcome!',
props: { name: 'John', confirmationUrl: 'https://...' },
});
`

#### verify(): Promise

Verify the SMTP connection.

#### close(): Promise

Close the SMTP connection.

#### getTemplateNames(): string[]

Get available template names.

Built-in Template Examples

$3

`tsx
interface WelcomeEmailProps {
name: string;
confirmationUrl?: string;
}

const WelcomeEmail = ({ name, confirmationUrl }: WelcomeEmailProps) => (









`tsx
interface PasswordResetEmailProps {
name: string;
resetUrl: string;
expiresIn: string;
}

const PasswordResetEmail = ({ name, resetUrl, expiresIn }: PasswordResetEmailProps) => (









`tsx
interface NotificationEmailProps {
name: string;
title: string;
message: string;
actionUrl?: string;
actionText?: string;
}

const NotificationEmail = ({
name,
title,
message,
actionUrl,
actionText = 'View Details'
}: NotificationEmailProps) => (









`typescript
import { createEmailClient } from '@geekmidas/emailkit';

const templates = {
welcome: WelcomeEmail,
passwordReset: PasswordResetEmail,
notification: NotificationEmail,
};

const client = createEmailClient({
smtp: {
host: 'smtp.example.com',
port: 587,
auth: {
user: 'user@example.com',
pass: 'password',
},
},
templates,
defaults: {
from: 'noreply@example.com',
},
});

// All template names and props are fully type-safe
await client.sendTemplate('welcome', {
from: 'welcome@example.com',
to: 'user@example.com',
subject: 'Welcome to our service!',
props: { name: 'John Doe', confirmationUrl: 'https://example.com/confirm/123' },
});

await client.sendTemplate('passwordReset', {
from: 'security@example.com',
to: 'user@example.com',
subject: 'Reset your password',
props: { name: 'John Doe', resetUrl: 'https://example.com/reset/456', expiresIn: '24 hours' },
});

await client.sendTemplate('notification', {
from: 'notifications@example.com',
to: 'user@example.com',
subject: 'Important notification',
props: {
name: 'John Doe',
title: 'Account Update',
message: 'Your account settings have been updated.',
actionUrl: 'https://example.com/settings',
actionText: 'View Settings'
},
});
``

TypeScript Support

The library provides full TypeScript support with:

- Template name inference - Only valid template names are accepted
- Props type checking - Props are validated based on the template's prop types
- Autocomplete support - IDE autocomplete for template names and props
- Compile-time safety - Catch template and prop errors at build time

License

MIT