@flink-app/email-plugin 1.0.0 → 2.0.0-alpha.100

package/readme.md

@@ -1,6 +1,6 @@
 # Email Plugin
 
-A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, and Flowmailer.
+A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, AWS SES, and Postmark.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm install @flink-app/email-plugin
 
 ## Configuration
 
-The email plugin supports three different email providers through a unified client interface:
+The email plugin supports five different email providers through a unified client interface:
 
 ### Option 1: SendGrid
 
@@ -118,15 +118,114 @@ interface flowmailerClientOptions {
 }
 ```
 
+### Option 4: AWS SES
+
+Configure the plugin with AWS Simple Email Service (SESv2):
+
+```typescript
+import { emailPlugin, sesClient } from "@flink-app/email-plugin";
+
+function start() {
+  new FlinkApp<AppContext>({
+    name: "My app",
+    plugins: [
+      emailPlugin({
+        client: new sesClient({
+          region: "eu-north-1",
+          defaultFrom: "noreply@example.com",
+          configurationSet: "my-tracking-set",  // optional
+        })
+      })
+    ],
+  }).start();
+}
+```
+
+**SES Client Options:**
+
+```typescript
+interface sesClientOptions {
+  region?: string;          // AWS region (defaults to AWS_REGION env var)
+  credentials?: {           // Explicit credentials (defaults to AWS credential chain)
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+  defaultFrom?: string;     // Default sender address
+  configurationSet?: string; // Default SES configuration set for tracking
+}
+```
+
+Credentials are resolved in this order:
+1. Explicit `credentials` option
+2. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+3. IAM instance profile / ECS task role
+4. AWS SSO / credential file
+
+### Option 5: Postmark
+
+Configure the plugin with [Postmark](https://postmarkapp.com/):
+
+```typescript
+import { emailPlugin, postmarkClient } from "@flink-app/email-plugin";
+
+function start() {
+  new FlinkApp<AppContext>({
+    name: "My app",
+    plugins: [
+      emailPlugin({
+        client: new postmarkClient({
+          serverToken: process.env.POSTMARK_SERVER_TOKEN!,
+          defaultMessageStream: "outbound", // optional
+        })
+      })
+    ],
+  }).start();
+}
+```
+
+**Postmark Client Options:**
+
+```typescript
+interface postmarkClientOptions {
+  serverToken: string;             // Postmark server token
+  defaultMessageStream?: string;   // Defaults to "outbound"
+}
+```
+
+**Postmark Email Type:**
+
+```typescript
+type emailPostmark = {
+  from: string;
+  to: string[];
+  replyTo?: string;
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  messageStream?: string;            // Overrides defaultMessageStream
+  tag?: string;                      // Postmark tag for categorization
+  metadata?: Record<string, string>; // Custom metadata
+  attachments?: PostmarkAttachment[];
+} & ({ text: string } | { html: string } | { text: string; html: string });
+
+interface PostmarkAttachment {
+  content: string;       // Base64 encoded
+  filename: string;
+  contentType?: string;  // Defaults to "application/octet-stream"
+  contentId?: string;    // For inline images, e.g. "cid:image1"
+}
+```
+
 ## TypeScript Setup
 
 Add the plugin context to your app's context type (usually in `Ctx.ts`):
 
 ```typescript
 import { FlinkContext } from "@flink-app/flink";
-import { emailPluginContext } from "@flink-app/email-plugin";
+import { EmailPluginContext } from "@flink-app/email-plugin";
 
-export interface Ctx extends FlinkContext<emailPluginContext> {
+export interface Ctx extends FlinkContext<EmailPluginContext> {
   // Your other context properties
 }
 ```
@@ -134,7 +233,7 @@ export interface Ctx extends FlinkContext<emailPluginContext> {
 **Plugin Context Interface:**
 
 ```typescript
-interface emailPluginContext {
+interface EmailPluginContext {
   emailPlugin: {
     client: client;  // Unified email client interface
   };
@@ -306,7 +405,7 @@ All email clients implement this unified interface:
 
 ```typescript
 interface client {
-  send(email: email | emailSendgrid | emailFlowmailer): Promise<boolean>;
+  send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark): Promise<boolean>;
 }
 ```
 
@@ -400,11 +499,163 @@ if (!success) {
 }
 ```
 
+## AWS SES — Extended Features
+
+The SES client supports additional features beyond the basic `send()` interface. Access them by casting the client to `sesClient`:
+
+```typescript
+import { sesClient } from "@flink-app/email-plugin";
+const ses = ctx.plugins.emailPlugin.client as sesClient;
+```
+
+### Rich Send Results
+
+Use `sendEmail()` instead of `send()` for detailed results:
+
+```typescript
+const result = await ses.sendEmail({
+  from: "noreply@example.com",
+  to: ["user@example.com"],
+  subject: "Hello",
+  html: "<h1>Welcome</h1>",
+  tags: { campaign: "welcome", env: "prod" },
+});
+
+if (result.success) {
+  console.log("Sent:", result.messageId);
+} else {
+  console.error(`Failed: ${result.error?.code} - ${result.error?.message}`);
+}
+```
+
+### Templated Emails
+
+Send emails using SES templates:
+
+```typescript
+const result = await ses.sendTemplated({
+  to: ["user@example.com"],
+  template: "WelcomeEmail",
+  templateData: { name: "Joel", company: "Frost" },
+});
+```
+
+### Bulk Email
+
+Send to many recipients using a single SES template:
+
+```typescript
+const result = await ses.sendBulk({
+  template: "Newsletter",
+  defaultTemplateData: { company: "Frost" },
+  destinations: [
+    { to: ["alice@example.com"], templateData: { name: "Alice" } },
+    { to: ["bob@example.com"], templateData: { name: "Bob" } },
+  ],
+});
+
+console.log(`Sent: ${result.successCount}, Failed: ${result.failureCount}`);
+
+// Check individual results
+for (const r of result.results) {
+  if (!r.success) {
+    console.error(`Failed: ${r.error?.code}`);
+  }
+}
+```
+
+### Verify Setup
+
+Check that your SES credentials and configuration are working:
+
+```typescript
+const status = await ses.verifySetup();
+console.log(status);
+// { verified: true, sendingEnabled: true, region: "eu-north-1" }
+```
+
+`sendingEnabled: false` means the account is still in the SES sandbox (can only send to verified addresses).
+
+### SES Email Type
+
+```typescript
+type emailSes = {
+  from: string;
+  to: string[];
+  replyTo?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: SesAttachment[];
+  configurationSet?: string;   // Override default config set
+  tags?: Record<string, string>; // Event tracking tags
+};
+```
+
+## AWS SES Setup Guide
+
+### 1. Verify your sending domain
+
+```bash
+# Verify a domain (recommended for production)
+aws sesv2 create-email-identity --email-identity example.com --region eu-north-1
+
+# Or verify a single email address (for testing)
+aws sesv2 create-email-identity --email-identity sender@example.com --region eu-north-1
+```
+
+### 2. Check verification status
+
+```bash
+aws sesv2 get-email-identity --email-identity example.com --region eu-north-1
+```
+
+For domain verification, add the DKIM CNAME records shown in the response to your DNS.
+
+### 3. Check account status
+
+```bash
+aws sesv2 get-account --region eu-north-1
+```
+
+Look for `"ProductionAccessEnabled": true`. If `false`, you're in the sandbox.
+
+### 4. Request production access (exit sandbox)
+
+```bash
+aws sesv2 put-account-details \
+  --production-access-enabled \
+  --mail-type TRANSACTIONAL \
+  --website-url "https://example.com" \
+  --use-case-description "Sending transactional emails (order confirmations, password resets)" \
+  --region eu-north-1
+```
+
+### 5. Send a test email
+
+```bash
+aws sesv2 send-email \
+  --from-email-address sender@example.com \
+  --destination '{"ToAddresses":["recipient@example.com"]}' \
+  --content '{"Simple":{"Subject":{"Data":"Test"},"Body":{"Text":{"Data":"Hello from SES"}}}}' \
+  --region eu-north-1
+```
+
+### 6. Create a configuration set (optional, for tracking)
+
+```bash
+aws sesv2 create-configuration-set --configuration-set-name my-tracking-set --region eu-north-1
+```
+
 ## Notes
 
 - Either `text` or `html` must be provided (not both required, but at least one)
-- All clients return a boolean indicating success/failure
+- All clients return a boolean indicating success/failure via the `send()` interface
+- The SES client additionally offers `sendEmail()`, `sendTemplated()`, `sendBulk()`, and `verifySetup()` with richer return types
 - Flowmailer automatically handles OAuth token refresh
 - SendGrid attachments must be base64 encoded
 - SMTP client uses nodemailer internally
+- Postmark attachments must be base64 encoded; supports `messageStream`, `tag`, and `metadata` Postmark-specific fields
 - Multiple recipients are supported by all clients