beenvoice/docs/email-features.md

# Enhanced Email Sending Features

## Overview

The beenvoice application now includes a comprehensive email sending system with preview, rich text editing, and confirmation features. This enhancement provides a professional email experience for sending invoices to clients.

## Features

### 🎨 Rich Text Email Composer
- **Tiptap Editor Integration**: Professional rich text editing with formatting options
- **Text Formatting**: Bold, italic, strikethrough, and color options
- **Text Alignment**: Left, center, and right alignment
- **Lists**: Bullet points and numbered lists
- **Color Picker**: Choose from a variety of text colors
- **Real-time Preview**: See changes as you type

### 👁️ Email Preview
- **Visual Preview**: See exactly how your email will appear to recipients
- **Invoice Summary**: Displays key invoice details (number, date, amount)
- **Attachment Notice**: Shows PDF attachment information
- **Professional Styling**: Clean, branded email template
- **Responsive Design**: Optimized for all screen sizes with proper text wrapping
- **Mobile-First**: Touch-friendly interface with proper spacing

### ✅ Send Confirmation
- **Two-Step Process**: Compose ↔ Preview with Send Action
- **Action-Based Sending**: Send button available from sidebar and floating action bar
- **Status Updates**: Automatic status change from draft to sent
- **Error Handling**: Clear error messages with specific guidance
- **SSR Compatible**: Proper hydration handling for server-side rendering

### 📄 Smart Templates
- **Auto-Generated Content**: Professional email templates with proper paragraph spacing
- **Time-Based Greetings**: Morning, afternoon, or evening greetings
- **Invoice Details**: Automatically includes invoice number, date, and amount
- **Business Branding**: Uses your business name and contact information
- **Immediate Loading**: Content appears instantly in the editor without requiring tab switching

## Components

### EmailComposer
**Location**: `src/components/forms/email-composer.tsx`

A rich text editor component for composing emails with formatting options.

**Props**:
- `subject`: Email subject line
- `onSubjectChange`: Callback for subject changes
- `content`: Email content (HTML)
- `onContentChange`: Callback for content changes
- `fromEmail`: Sender email address
- `toEmail`: Recipient email address

### EmailPreview
**Location**: `src/components/forms/email-preview.tsx`

Displays a visual preview of how the email will appear to recipients.

**Props**:
- `subject`: Email subject line
- `fromEmail`: Sender email address
- `toEmail`: Recipient email address
- `content`: Email content (HTML)
- `invoice`: Invoice data for summary display

### SendEmailDialog
**Location**: `src/components/forms/send-email-dialog.tsx`

Main dialog component that combines composition, preview, and confirmation.

**Props**:
- `invoiceId`: ID of the invoice to send
- `trigger`: React element that opens the dialog
- `invoice`: Invoice data
- `onEmailSent`: Callback when email is successfully sent

### EnhancedSendInvoiceButton
**Location**: `src/components/forms/enhanced-send-invoice-button.tsx`

Enhanced button component that opens the email dialog.

**Props**:
- `invoiceId`: ID of the invoice to send
- `variant`: Button style variant
- `className`: Additional CSS classes
- `showResend`: Whether to show "Resend" text
- `size`: Button size

## API Enhancements

### Enhanced Email Router
**Location**: `src/server/api/routers/email.ts`

The email API has been enhanced to support custom content and HTML emails.

**New Parameters**:
- `customSubject`: Optional custom email subject
- `customContent`: Optional custom email content (HTML)
- `useHtml`: Boolean flag to send HTML email

**Features**:
- HTML email support with plain text fallback
- Custom subject lines
- Rich HTML content
- Automatic PDF attachment
- BCC to business email
- Comprehensive error handling

## Usage Examples

### Basic Usage
```tsx
import { EnhancedSendInvoiceButton } from "~/components/forms/enhanced-send-invoice-button";

// Replace existing send buttons
<EnhancedSendInvoiceButton
  invoiceId={invoice.id}
  className="w-full"
  showResend={invoice.status === "sent"}
/>
```

### Custom Dialog
```tsx
import { SendEmailDialog } from "~/components/forms/send-email-dialog";

<SendEmailDialog
  invoiceId={invoice.id}
  invoice={invoiceData}
  trigger={<Button>Send Custom Email</Button>}
  onEmailSent={() => console.log("Email sent!")}
/>
```

### Standalone Components
```tsx
import { EmailComposer } from "~/components/forms/email-composer";
import { EmailPreview } from "~/components/forms/email-preview";

// Use individual components for custom implementations
<EmailComposer
  subject={subject}
  onSubjectChange={setSubject}
  content={content}
  onContentChange={setContent}
  fromEmail="you@business.com"
  toEmail="client@company.com"
/>

<EmailPreview
  subject={subject}
  content={content}
  fromEmail="you@business.com"
  toEmail="client@company.com"
  invoice={invoiceData}
/>
```

## Technical Details

### Dependencies
- **@tiptap/react**: Rich text editor framework
- **@tiptap/starter-kit**: Basic editor functionality
- **@tiptap/extension-text-style**: Text styling support
- **@tiptap/extension-color**: Color picker support
- **@tiptap/extension-text-align**: Text alignment options

### Email Templates
The system generates professional HTML email templates with:
- Responsive design
- Brand colors (green theme)
- Invoice summary cards
- Proper typography
- Attachment indicators
- Footer branding

### Error Handling
Comprehensive error handling for:
- Invalid email addresses
- Missing client information
- Resend API issues
- Network connectivity problems
- Domain verification issues
- Rate limiting

## Usage in Application

The enhanced email functionality is integrated throughout the application:
- Invoice view pages with enhanced send buttons
- Full-page email composition interface
- Professional email templates with invoice integration
- Comprehensive preview and confirmation workflow

## Migration Guide

### From Basic Send Button
Replace existing `SendInvoiceButton` components with `EnhancedSendInvoiceButton`:

```tsx
// Before
import { SendInvoiceButton } from "../_components/send-invoice-button";
<SendInvoiceButton invoiceId={invoice.id} />

// After
import { EnhancedSendInvoiceButton } from "~/components/forms/enhanced-send-invoice-button";
<EnhancedSendInvoiceButton invoiceId={invoice.id} />
```

### API Compatibility
The enhanced email API is backward compatible with existing implementations. New features are opt-in through additional parameters.

## Security Considerations

- **Input Sanitization**: All user input is validated and sanitized
- **Email Validation**: Comprehensive email format validation
- **Rate Limiting**: Built-in protection against spam
- **Domain Verification**: Resend domain verification required
- **Authentication**: All email operations require valid authentication

## Performance

- **SSR Optimization**: Proper server-side rendering with hydration safeguards
- **Efficient Loading**: Content initializes immediately without requiring user interaction
- **Optimized Rendering**: Efficient React component updates with proper state management
- **Caching**: Proper query caching for invoice data
- **Error Boundaries**: Graceful error handling without crashes
- **Responsive Design**: Optimized layouts for all screen sizes with text overflow prevention

## Navigation

### Send Email Page
Access the email interface by clicking "Send Invoice" on any invoice:
- `/dashboard/invoices/[id]/send` - Full-page email composition
- Two-tab interface: Compose ↔ Preview
- Send action available from sidebar and floating action bar
- Fully responsive design with proper text wrapping and overflow handling
- Professional layout with sidebar containing:
  - Invoice summary (number, client, date, status)
  - Email details (from, to, subject, attachment info)
  - Context-aware action buttons
- Auto-filled message with proper HTML formatting and paragraph spacing
- Immediate content loading without requiring tab navigation

## Fixes and Improvements

Recent fixes and enhancements:
- **SSR Compatibility**: Fixed Tiptap hydration issues for reliable server-side rendering
- **Content Loading**: Improved email content initialization for immediate display
- **Responsive Design**: Enhanced text wrapping and overflow handling for all screen sizes
- **UI/UX**: Removed confirmation tab in favor of action-based sending approach
- **Performance**: Optimized state management for faster content loading

## Future Enhancements

Planned improvements include:
- Email templates library
- Scheduling email delivery
- Email tracking and read receipts
- Bulk email sending
- Custom email signatures
- Integration with email marketing tools

## Support

For issues or questions related to the email system:
1. Check the console for error messages
2. Verify Resend API configuration
3. Ensure client email addresses are valid
4. Review domain verification status
5. Check network connectivity

## Changelog

### Version 1.0.0
- Initial release of enhanced email system
- Rich text editor integration
- Email preview functionality
- Send confirmation workflow
- HTML email support
- Professional templates
- Demo page implementation