Remove email outbox collection and process job; refactor email templates with rich text support and slug generation

2025-12-10 16:23:23 +00:00 · 2025-09-13 12:11:35 +02:00
parent ed9d979d3e
commit 3868e74770
34 changed files with 2674 additions and 374 deletions
--- a/dev/README.md
+++ b/dev/README.md
@@ -0,0 +1,208 @@
+# PayloadCMS Mailing Plugin - Development Setup
+
+This directory contains a complete PayloadCMS application for testing and developing the mailing plugin.
+
+## Quick Start
+
+1. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+2. **Start development server (with in-memory MongoDB):**
+   ```bash
+   npm run dev
+   ```
+   
+   **Alternative startup methods:**
+   ```bash
+   # Force in-memory database (from root directory)
+   npm run dev:memory
+   
+   # With startup script and helpful info
+   npm run dev:start
+   
+   # From dev directory
+   cd dev && npm run dev
+   ```
+
+3. **Optional: Set up environment file:**
+   ```bash
+   cp ../.env.example .env
+   # Edit .env if you want to use external MongoDB
+   ```
+
+4. **Access the application:**
+   - Admin Panel: http://localhost:3000/admin
+   - Mailing Test Page: http://localhost:3000/mailing-test
+   - GraphQL Playground: http://localhost:3000/api/graphql-playground
+
+## Features Included
+
+### ✅ **Mailing Plugin Integration**
+- Configured with test email transport
+- Example email templates automatically created
+- Collections: `email-templates` and `email-outbox`
+
+### ✅ **Test Interface**
+- Web UI at `/mailing-test` for testing emails
+- Send emails immediately or schedule for later
+- View outbox status and email history
+- Process outbox manually
+
+### ✅ **API Endpoints**
+- `POST /api/test-email` - Send/schedule test emails
+- `GET /api/test-email` - Get templates and outbox status
+- `POST /api/process-outbox` - Manually process outbox
+- `GET /api/process-outbox` - Get outbox statistics
+
+### ✅ **Example Templates**
+1. **Welcome Email** - New user onboarding
+2. **Order Confirmation** - E-commerce order receipt
+3. **Password Reset** - Security password reset
+
+## Email Testing
+
+### Option 1: MailHog (Recommended)
+```bash
+# Install MailHog
+go install github.com/mailhog/MailHog@latest
+
+# Run MailHog
+MailHog
+```
+- SMTP: localhost:1025 (configured in dev)
+- Web UI: http://localhost:8025
+
+### Option 2: Console Logs
+The dev environment uses `testEmailAdapter` which logs emails to console.
+
+## Testing the Plugin
+
+1. **Via Web Interface:**
+   - Go to http://localhost:3000/mailing-test
+   - Select a template
+   - Fill in variables
+   - Send or schedule email
+
+2. **Via Admin Panel:**
+   - Go to http://localhost:3000/admin
+   - Navigate to "Mailing > Email Templates" 
+   - Create/edit templates
+   - Navigate to "Mailing > Email Outbox"
+   - View scheduled/sent emails
+
+3. **Via API:**
+   ```bash
+   # Send welcome email
+   curl -X POST http://localhost:3000/api/test-email \\
+     -H "Content-Type: application/json" \\
+     -d '{
+       "type": "send",
+       "templateId": "TEMPLATE_ID",
+       "to": "test@example.com",
+       "variables": {
+         "firstName": "John",
+         "siteName": "Test Site"
+       }
+     }'
+   ```
+
+## Development Workflow
+
+1. **Make changes to plugin source** (`../src/`)
+2. **Rebuild plugin:** `npm run build` (in root)
+3. **Restart dev server:** The dev server watches for changes
+4. **Test changes** via web interface or API
+
+## Database Configuration
+
+The development setup automatically uses **MongoDB in-memory database** by default - no MongoDB installation required!
+
+### 🚀 **In-Memory MongoDB (Default)**
+- ✅ **Zero setup** - Works out of the box
+- ✅ **No installation** required
+- ✅ **Fast startup** - Ready in seconds  
+- ⚠️ **Data resets** on server restart
+- 💾 **Perfect for development** and testing
+
+### 🔧 **Database Options**
+
+1. **In-Memory (Recommended for Development):**
+   ```bash
+   # Automatic - just start the server
+   npm run dev
+   
+   # Or explicitly enable
+   USE_MEMORY_DB=true npm run dev
+   ```
+
+2. **Local MongoDB:**
+   ```bash
+   # Install MongoDB locally, then:
+   DATABASE_URI=mongodb://localhost:27017/payload-mailing-dev npm run dev
+   ```
+
+3. **Remote MongoDB:**
+   ```bash
+   # Set your connection string:
+   DATABASE_URI=mongodb+srv://user:pass@cluster.mongodb.net/dbname npm run dev
+   ```
+
+### 💡 **Database Startup Messages**
+When you start the dev server, you'll see helpful messages:
+```
+🚀 Starting MongoDB in-memory database...
+✅ MongoDB in-memory database started  
+📊 Database URI: mongodb://***@localhost:port/payload-mailing-dev
+```
+
+## Jobs Processing
+
+The plugin automatically processes the outbox every 5 minutes and retries failed emails every 30 minutes. You can also trigger manual processing via:
+- Web interface "Process Outbox" button  
+- API endpoint `POST /api/process-outbox`
+
+## Troubleshooting
+
+### Email not sending:
+1. Check MailHog is running on port 1025
+2. Check console logs for errors
+3. Verify template variables are correct
+4. Check outbox collection for error messages
+
+### Plugin not loading:
+1. Ensure plugin is built: `npm run build` in root
+2. Check console for initialization message
+3. Verify plugin configuration in `payload.config.ts`
+
+### Templates not appearing:
+1. Check seed function ran successfully
+2. Verify database connection
+3. Check admin panel collections
+
+## Plugin API Usage
+
+```javascript
+import { sendEmail, scheduleEmail } from '@xtr-dev/payload-mailing'
+
+// Send immediate email
+const emailId = await sendEmail(payload, {
+  templateId: 'welcome-template-id',
+  to: 'user@example.com',
+  variables: {
+    firstName: 'John',
+    siteName: 'My App'
+  }
+})
+
+// Schedule email
+const scheduledId = await scheduleEmail(payload, {
+  templateId: 'reminder-template-id', 
+  to: 'user@example.com',
+  scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
+  variables: {
+    eventName: 'Product Launch'
+  }
+})
+```