# Lockness Mail
Email sending library with fluent API and multiple driver support.
## Overview
@lockness/mail provides an expressive email builder with support for SMTP,
Resend, Console (dev), and Memory (testing) drivers. Full email features
including CC, BCC, Reply-To, attachments, and JSX templates.
## Installation
```typescript
import { configureMail, mail } from '@lockness/mail'
```
## Configuration
```typescript
configureMail({
driver: 'smtp', // 'smtp' | 'resend' | 'console' | 'memory'
from: { email: 'noreply@example.com', name: 'My App' },
smtp: {
host: 'smtp.example.com',
port: 587,
auth: { user: 'username', pass: 'password' },
},
resend: {
apiKey: 'your-api-key',
},
})
```
## Basic Usage
### Simple Email
```typescript
await mail()
.to('user@example.com')
.subject('Welcome!')
.html('Hello World!
')
.send()
```
### Full Example
```typescript
await mail()
.from('sender@example.com', 'Sender Name')
.to('recipient@example.com')
.cc('cc@example.com')
.bcc('bcc@example.com')
.replyTo('reply@example.com')
.subject('Test Email')
.text('Plain text version')
.html('HTML version')
.attach('file.txt', 'File content')
.send()
```
### With JSX Templates
```typescript
const EmailTemplate = ({ name }: { name: string }) => (
Welcome, {name}!
Thanks for joining our service.
)
await mail()
.to('user@example.com')
.subject('Welcome!')
.view()
.send()
```
## Drivers
### Console Driver (Development)
Prints emails to console instead of sending them.
```typescript
configureMail({ driver: 'console' })
```
### Memory Driver (Testing)
Stores emails in memory for testing.
```typescript
import { MemoryMailDriver } from '@lockness/mail'
configureMail({ driver: 'memory' })
// Send email
await mail().to('test@example.com').subject('Test').send()
// Get sent emails
const emails = MemoryMailDriver.getSentEmails()
const lastEmail = MemoryMailDriver.getLastEmail()
// Clear
MemoryMailDriver.clear()
```
### SMTP Driver
```typescript
configureMail({
driver: 'smtp',
smtp: {
host: 'smtp.gmail.com',
port: 587,
auth: {
user: 'your-email@gmail.com',
pass: 'your-password',
},
},
})
```
### Resend Driver
```typescript
configureMail({
driver: 'resend',
resend: {
apiKey: Deno.env.get('RESEND_API_KEY'),
},
})
```
## API Reference
### Mail Builder Methods
- `from(email, name?)` - Set sender
- `to(email, name?)` - Set recipient (can call multiple times)
- `cc(email, name?)` - Add CC recipient
- `bcc(email, name?)` - Add BCC recipient
- `replyTo(email)` - Set reply-to address
- `subject(subject)` - Set email subject
- `text(content)` - Set plain text content
- `html(content)` - Set HTML content
- `view(jsx)` - Set JSX template content
- `attach(filename, content)` - Add attachment
- `send()` - Send the email
## Common Use Cases
### Password Reset Email
```typescript
import { mail } from '@lockness/mail'
async function sendPasswordReset(user: User, resetToken: string) {
const resetUrl = `https://example.com/reset-password?token=${resetToken}`
await mail()
.to(user.email, user.name)
.subject('Reset Your Password')
.html(`
Password Reset Request
Click the link below to reset your password:
Reset Password
This link expires in 1 hour.
`)
.send()
}
```
### Welcome Email with Template
```typescript
const WelcomeEmail = (
{ name, verifyUrl }: { name: string; verifyUrl: string },
) => (
Welcome, {name}!
Thanks for signing up. Please verify your email:
Verify Email
)
await mail()
.to(user.email, user.name)
.subject('Welcome to Our App')
.view()
.send()
```
### Email with Attachments
```typescript
await mail()
.to('user@example.com')
.subject('Invoice')
.html('Your invoice is attached.
')
.attach('invoice.pdf', pdfBytes)
.attach('receipt.txt', 'Receipt content')
.send()
```
### Testing Emails
```typescript
import { MemoryMailDriver } from '@lockness/mail'
// Setup
configureMail({ driver: 'memory' })
// Your code sends email
await sendWelcomeEmail(user)
// Assert in tests
const emails = MemoryMailDriver.getSentEmails()
assertEquals(emails.length, 1)
assertEquals(emails[0].to[0].email, 'user@example.com')
assertEquals(emails[0].subject, 'Welcome!')
// Cleanup
MemoryMailDriver.clear()
```
## Best Practices
- Use Console driver in development to avoid accidental emails
- Use Memory driver in tests with MemoryMailDriver.clear() in afterEach
- Set default `from` address in configuration
- Use JSX templates for complex emails with consistent styling
- Always include both text and html content for best compatibility
- Store SMTP credentials and API keys in environment variables
- For bulk emails, consider implementing rate limiting
- Use proper error handling around mail.send() calls
## Environment Variables
```bash
# .env
MAIL_DRIVER=smtp
MAIL_FROM_EMAIL=noreply@example.com
MAIL_FROM_NAME="My App"
# SMTP
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
# Resend
RESEND_API_KEY=re_123456789
```