This is a test email
',\n attachments: [\n {\n filename: 'test.txt',\n content: 'This is a test file content',\n contentType: 'text/plain',\n encoding: 'utf8'\n }\n ],\n headers: {\n 'X-Custom-Header': 'value'\n }\n};\n\n// Multiple recipients with different formats\nconst multiRecipientEmail: EmailOptions = {\n from: 'sender@example.com',\n to: [\n 'to@example.com',\n { email: 'sender@example.com', name: 'Team Member' }\n ],\n cc: [\n 'cc@example.com',\n { email: 'cc2@example.com', name: 'CC Recipient' }\n ],\n bcc: [\n 'bcc@example.com',\n { email: 'bcc2@example.com', name: 'BCC Recipient' }\n ],\n subject: 'Multi-recipient Email',\n text: 'This email goes to multiple recipients'\n};\n\nconst result: SendResult = await postie.send(emailOptions);\n```\n\n### Template Emails\n\n```typescript\n// Template email with required fields\nconst templateEmail: TemplateEmailOptions = {\n from: 'sender@example.com',\n to: 'to@example.com',\n subject: 'Welcome',\n template: 'Hello {{name}}, welcome to {{company}}!',\n data: {\n name: 'John Doe',\n company: 'Example Inc'\n }\n};\n\nconst templateResult: SendResult = await postie.sendTemplate(templateEmail);\n```\n\n### Template Engine\n\n```typescript\nconst templateEngine: TemplateEngine = {\n compile: (template: string) => template,\n render: (compiled: unknown, data: RecordThis is a welcome email
',\n template: 'Hello {{name}}, welcome to {{company}}!',\n data: {\n company: 'Example Inc'\n },\n attachments: [\n {\n filename: 'welcome.pdf',\n path: '/path/to/welcome.pdf',\n contentType: 'application/pdf'\n }\n ],\n headers: {\n 'X-Custom-Header': 'value'\n }\n};\n\npostie.define('welcome', welcomeAlias);\n\n// Trigger with overrides\nconst result: SendResult = await postie.trigger('welcome', {\n to: 'newuser@example.com',\n data: {\n name: 'John Doe'\n }\n});\n```\n\n### Special Email Types\n\n```typescript\n// Notification with all available options\nconst notificationResult: SendResult = await postie.notify({\n from: 'sender@example.com',\n fromName: 'System',\n to: 'to@example.com',\n toName: 'Admin',\n subject: 'System Notification',\n text: 'This is a notification',\n html: 'This is a notification
',\n attachments: [\n {\n filename: 'log.txt',\n content: 'System logs',\n contentType: 'text/plain'\n }\n ],\n headers: {\n 'X-Priority': '1'\n }\n});\n\n// Alert with all available options\nconst alertResult: SendResult = await postie.alert({\n from: 'sender@example.com',\n fromName: 'Monitoring',\n to: 'to@example.com',\n toName: 'Admin',\n subject: 'System Alert',\n text: 'This is an alert',\n html: 'This is an alert
',\n attachments: [\n {\n filename: 'error.log',\n content: 'Error logs',\n contentType: 'text/plain'\n }\n ],\n headers: {\n 'X-Priority': '1'\n }\n});\n\n// Ping with all available options\nconst pingResult: SendResult = await postie.ping({\n from: 'sender@example.com',\n fromName: 'System',\n to: 'to@example.com',\n toName: 'Admin',\n subject: 'Ping Test',\n text: 'Ping!',\n html: 'Ping!
',\n attachments: [\n {\n filename: 'ping.log',\n content: 'Ping logs',\n contentType: 'text/plain'\n }\n ],\n headers: {\n 'X-Priority': '1'\n }\n});\n```\n\n### Error Handling\n\n```typescript\ntry {\n const result = await postie.send(emailOptions);\n console.log('Email sent successfully:', result);\n} catch (error) {\n console.error('Failed to send email:', error);\n // Error details include:\n // - SMTP response\n // - Connection status\n // - Retry attempts\n}\n```\n\n### Development Mode\n\n```typescript\n// Configure for development\npostie.configure({\n devMode: true,\n retryAttempts: 1,\n retryDelay: 100\n});\n\n// Send test email\nconst devResult: SendResult = await postie.send({\n to: 'test@example.com',\n subject: 'Test Email',\n text: 'This is a test email'\n});\n// Email will be logged but not sent\n```\n\n## š§ Basic Usage\n\n## āļø Configuration\n\nPostie provides flexible configuration options that can be set globally or per instance.\n\n### Global Configuration\n\n```javascript\n// Configure global settings\npostie.configure({\n devMode: false, // Enable development mode\n retryAttempts: 3, // Number of retry attempts\n retryDelay: 1000 // Delay between retries in milliseconds\n})\n```\n\n### SMTP Configuration\n\n```javascript\n// Configure SMTP settings\npostie.setTransporter({\n host: 'smtp.gmail.com',\n port: 587,\n secure: false,\n auth: {\n user: 'your-email@gmail.com',\n pass: 'your-app-password'\n }\n})\n```\n\n### Template Engine Configuration\n\n```javascript\n// Configure template engine\npostie.setTemplateEngine({\n render: (template, data) => {\n // Custom template rendering logic\n return renderedTemplate\n }\n})\n```\n\n## āļø Basic Setup\n\n```javascript\nconst Postie = require('@anishhs/postie')\nconst postie = new Postie()\n\n// Configure SMTP\npostie.setTransporter({\n host: 'smtp.gmail.com',\n port: 587,\n secure: false, // Use STARTTLS\n auth: {\n user: 'your-email@gmail.com',\n pass: 'your-app-password'\n }\n})\n\n// Optional: Configure retry settings\npostie.configure({\n retryAttempts: 3,\n retryDelay: 1000,\n devMode: false\n})\n```\n\n## š§ Core Methods\n\n### `setTransporter(config)`\nConfigures the SMTP transporter.\n\n```javascript\npostie.setTransporter({\n host: 'smtp.gmail.com',\n port: 587,\n secure: false,\n auth: {\n user: 'your-email@gmail.com',\n pass: 'your-app-password'\n }\n})\n```\n\n### `configure(config)`\nSets global configuration options.\n\n```javascript\npostie.configure({\n devMode: false, // Enable development mode\n retryAttempts: 3, // Number of retry attempts\n retryDelay: 1000 // Delay between retries in milliseconds\n})\n```\n\n### `testConnection()`\nTests the SMTP connection.\n\n```javascript\nconst success = await postie.testConnection()\nif (success) {\n console.log('SMTP connection successful')\n}\n```\n\n## šØ Email Sending\n\n### š Basic Email\n\n```javascript\nawait postie.send({\n from: 'sender@example.com',\n fromName: 'John Doe', // Optional\n to: 'recipient@example.com',\n toName: 'Jane Smith', // Optional\n subject: 'Hello',\n text: 'This is a test email'\n})\n```\n\n### š„ Multiple Recipients\n\n```javascript\nawait postie.send({\n from: 'sender@example.com',\n to: [\n 'recipient1@example.com',\n { email: 'recipient2@example.com', name: 'Recipient 2' }\n ],\n subject: 'Hello',\n text: 'This is a test email'\n})\n```\n\n### š HTML Email\n\n```javascript\nawait postie.send({\n from: 'sender@example.com',\n to: 'recipient@example.com',\n subject: 'Hello',\n html: 'This is an HTML email.
'\n})\n```\n\n### š With Attachments\n\n```javascript\nawait postie.send({\n from: 'sender@example.com',\n to: 'recipient@example.com',\n subject: 'Hello',\n text: 'This is a test email',\n attachments: [\n {\n filename: 'document.pdf',\n path: '/path/to/document.pdf'\n }\n ]\n})\n```\n\n### šÆ Special Methods\n\n#### `notify()`\nSends a notification email with a \"[NOTIFICATION]\" prefix.\n\n```javascript\nawait postie.notify({\n from: 'sender@example.com',\n to: 'recipient@example.com',\n subject: 'System Update',\n text: 'The system has been updated'\n})\n```\n\n#### `alert()`\nSends an alert email with an \"[ALERT]\" prefix.\n\n```javascript\nawait postie.alert({\n from: 'sender@example.com',\n to: 'recipient@example.com',\n subject: 'High CPU Usage',\n text: 'CPU usage is above 90%'\n})\n```\n\n#### `ping()`\nSends a simple ping email.\n\n```javascript\nawait postie.ping({\n from: 'sender@example.com',\n to: 'recipient@example.com'\n})\n```\n\n## š Template Support\n\n### Template Engine Setup\n\nPostie supports any template engine that follows the standard template engine interface. Here are examples for different template engines:\n\n#### Handlebars\n```javascript\nconst Handlebars = require('handlebars')\nconst handlebarsEngine = {\n compile: Handlebars.compile,\n render: (compiled, data) => compiled(data)\n}\npostie.setTemplateEngine(handlebarsEngine)\n```\n\n#### EJS\n```javascript\nconst ejs = require('ejs')\nconst ejsEngine = {\n compile: (template) => ejs.compile(template),\n render: (compiled, data) => compiled(data)\n}\npostie.setTemplateEngine(ejsEngine)\n```\n\n#### Custom Template Engine\nYou can create your own simple template engine:\n\n```javascript\nconst customEngine = {\n render: (template, data) => {\n return template.replace(/\\{\\{(\\w+)\\}\\}/g, (match, key) => data[key] || match)\n }\n}\npostie.setTemplateEngine(customEngine)\n```\n\n### Send Template Email\n\nYou can send template emails in two ways:\n\n1. Using a template string:\n```javascript\nawait postie.sendTemplate({\n from: 'sender@example.com',\n to: 'recipient@example.com',\n subject: 'Welcome',\n template: 'Hello {{name}}, Welcome to {{company}}!',\n data: {\n name: 'John Doe',\n company: 'Our Company'\n }\n})\n```\n\n2. Using a template file:\n```javascript\nawait postie.sendTemplate({\n from: 'sender@example.com',\n to: 'recipient@example.com',\n subject: 'Welcome',\n template: path.join(__dirname, 'templates/welcome.hbs'),\n data: {\n name: 'John Doe',\n company: 'Our Company',\n role: 'Developer'\n }\n})\n```\n\n### Template Engine Interface\n\nTo use a custom template engine, implement the following interface:\n\n```javascript\nconst customEngine = {\n // Required: Function to render the template with data\n render: (template, data) => {\n // Return the rendered template string\n return renderedTemplate\n },\n \n // Optional: Function to compile the template\n compile: (template) => {\n // Return a compiled template function\n return compiledTemplate\n }\n}\n```\n\n## š Middleware\n\nAdd middleware functions to modify email options before sending.\n\n```javascript\n// Add logging middleware\npostie.use((emailOptions, next) => {\n console.log('Sending email:', emailOptions)\n next()\n})\n\n// Add custom header middleware\npostie.use((emailOptions, next) => {\n emailOptions.headers = {\n ...emailOptions.headers,\n 'X-Custom-Header': 'value'\n }\n next()\n})\n```\n\n## š§ Email Triggering By Aliases\n\nPostie allows you to define reusable email configurations with aliases and trigger them with optional overrides. This is useful for setting up reusable email configurations.\n\n### Define an Alias\n\n```javascript\n// Define a welcome email alias\npostie.define('user-welcome', {\n from: 'welcome@example.com',\n subject: 'Welcome to Our Platform',\n template: 'Hello {{name}}, welcome to {{company}}!',\n data: {\n company: 'Example Inc'\n }\n})\n\n// Define a notification alias\npostie.define('system-update', {\n type: 'notify',\n from: 'system@example.com',\n subject: 'System Update',\n text: 'A new system update is available'\n})\n\n// Define an alert alias\npostie.define('high-usage', {\n type: 'alert',\n from: 'monitoring@example.com',\n subject: 'High Resource Usage',\n text: 'CPU usage is above 90%'\n})\n```\n\n### Trigger an Alias\n\n```javascript\n// Trigger welcome email with overrides\nawait postie.trigger('user-welcome', {\n to: 'john@example.com',\n data: {\n name: 'John Doe'\n }\n})\n\n// Trigger system update\nawait postie.trigger('system-update', {\n to: 'admin@example.com'\n})\n\n// Trigger alert with custom message\nawait postie.trigger('high-usage', {\n to: 'admin@example.com',\n text: 'Memory usage is above 95%'\n})\n```\n\n### Alias Configuration Options\n\nYou can use any of the following options in your alias configuration:\n\n- Basic email options (`from`, `to`, `subject`, `text`, `html`)\n- Template options (`template`, `data`)\n- Special types (`type: 'notify'`, `type: 'alert'`, `type: 'ping'`)\n- Attachments\n- Headers\n- Any other options supported by the email sending methods\n\nWhen triggering an alias, you can override any of these options by passing them in the `overrides` object.\n\n## š» CLI Usage\n\n### Configure SMTP\n\n```bash\npostie configure \\\n --host smtp.gmail.com \\\n --port 587 \\\n --user your-email@gmail.com \\\n --pass your-app-password \\\n --secure false\n```\n\n### Send Email\n\n```bash\n# Basic email\npostie send \\\n --from sender@example.com \\\n --to recipient@example.com \\\n --subject \"Hello\" \\\n --text \"This is a test email\"\n\n# Send with HTML\npostie send \\\n --from sender@example.com \\\n --to recipient@example.com \\\n --subject \"Hello\" \\\n --html template.html\n\n# Send with attachments\npostie send \\\n --from sender@example.com \\\n --to recipient@example.com \\\n --subject \"Hello\" \\\n --text \"This is a test email\" \\\n --attachments file1.pdf,file2.pdf\n```\n\n### Using CLI Aliases\n\nPostie supports predefined email configurations through CLI aliases in your `.postierc` file. These aliases use the event-based triggering system under the hood.\n\n```bash\n# Send a predefined notification\npostie send --alias notify-admin\n\n# Send a system alert\npostie send --alias system-alert\n```\n\nWhen you use a CLI alias:\n1. Postie looks up the alias configuration in your `.postierc` file\n2. It uses the event-based triggering system to send the email\n3. The email is sent using the configured SMTP settings\n\nYou can override any alias configuration with command-line arguments:\n```bash\n# Override the recipient for a predefined notification\npostie send --alias notify-admin --to \"different-admin@example.com\"\n\n# Override the subject for a system alert\npostie send --alias system-alert --subject \"Custom Alert\"\n```\n\n## š Configuration Files\n\n### Global Configuration (`~/.postie/config.json`)\n\n```json\n{\n \"devMode\": false,\n \"retryAttempts\": 3,\n \"retryDelay\": 1000,\n \"transporter\": {\n \"host\": \"smtp.gmail.com\",\n \"port\": 587,\n \"secure\": false,\n \"auth\": {\n \"user\": \"your-email@gmail.com\",\n \"pass\": \"your-app-password\"\n }\n }\n}\n```\n\n### Project Configuration (.postierc)\n\nYou can create a `.postierc` file in your project root to specify default options for that project. This is useful when you have project-specific email settings. The settings in `.postierc` will override the global configuration from `~/.postie/config.json`.\n\nExample `.postierc` file:\n```json\n{\n \"emailDefaults\": {\n // Basic email options\n \"from\": \"project@example.com\",\n \"fromName\": \"Project Team\",\n \"subject\": \"Default Subject\",\n \"text\": \"Default email content\",\n \"html\": \"