emdash-aws-ses

A standalone, lightweight SMTP email transport plugin for EmDash CMS designed to route all system emails securely through Amazon SES (Simple Email Service).

By registering exclusively with EmDash’s mail delivery hooks, this plugin routes all native transactional emails (including passwordless magic links, collaborator invitations, and system notifications) through your AWS infrastructure.

Features

• Exclusive Email Routing: Intercepts the global EmDash email:deliver hook with exclusive: true to route all outgoing mail using secure SMTP transport powered by nodemailer.
• Interactive Block Kit UI: Provides a built-in, responsive configuration and test dashboard directly inside the EmDash administrative panel.
• Secure Database Persistence: Saves your SMTP credentials securely inside your active database (SQLite or PostgreSQL) via the native EmDash key-value (ctx.kv) store.
• Built-in Diagnostics: Validates SMTP server handshakes and sends HTML/plaintext test emails to any recipient directly from the visual test tab.

Prerequisites

Before installing the plugin, ensure you have configured your AWS environment:

1. Verified Identity: Confirm that your sender domain (e.g., your-domain.com) or specific email address (e.g., [email protected]) is verified in your Amazon SES console. Unverified identities will be rejected by AWS.
2. SMTP Credentials: Go to the SMTP Settings tab in your Amazon SES console and click Create SMTP Credentials to generate a dedicated IAM SMTP Username and SMTP Password.

Installation

Install the package into your main Astro + EmDash website directory:

From the public npm registry (Recommended):

npm install emdash-aws-ses

From a local development directory:

npm install ../path/to/emdash-aws-ses

Integration in Astro

To enable the plugin, import and register awsSesPlugin() inside the plugins array of the EmDash integration in your astro.config.mjs file:

// astro.config.mjs
import "dotenv/config";

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

// 1. Import the plugin
import { awsSesPlugin } from "emdash-aws-ses";

export default defineConfig({
	output: "server",
	adapter: node({
		mode: "standalone",
	}),
	image: {
		layout: "constrained",
		responsiveStyles: true,
	},
	integrations: [
		react(),
		emdash({
			database: sqlite({
				// Dynamic SQLite database resolution for Coolify
				url: process.env.NODE_ENV === "production"
					? "file:/app/data/data.db"
					: "file:./data.db",
			}),
			storage: local({
				// Dynamic persistent directory mapping for Coolify
				directory: process.env.NODE_ENV === "production"
					? "/app/data/uploads"
					: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
			// 2. Register your plugin here
			plugins: [
				awsSesPlugin(),
			],
		}),
	],
	devToolbar: { enabled: false },
});

Configuration & Usage

Once your application is running, navigate to your CMS admin panel at https://your-domain.com/_emdash/admin.

1. SMTP Settings Panel

Go to Settings -> Plugins -> AWS SES Settings and fill out the interactive configuration form:

| Field | Description | Example | | :--- | :--- | :--- | | SMTP Host | The SMTP endpoint host provided by Amazon SES. | email-smtp.us-east-1.amazonaws.com | | SMTP Port | The secure SMTP port (STARTTLS or SSL/TLS). | 587 (Recommended) or 465 | | SMTP Username | Your dedicated IAM SMTP Username generated in AWS. | AKIA... | | SMTP Password | Your dedicated IAM SMTP Password generated in AWS. | xxxXXXxxx | | AWS Region | The geographic AWS region where your SES is hosted. | us-east-1 | | Default From Address | A verified and authorized sender email address in AWS. | [email protected] | | From Name | The display name recipients will see. | Your Company | | Reply-To Address | An optional reply-to address for user responses. | [email protected] |

Click Save Settings to write your changes securely to the database.

2. Testing the Connection

Navigate to the Test & Status tab inside the plugin's dashboard to diagnose the pipeline:

• Click Test Connection to trigger an on-demand SMTP handshake validation.
• Type an email address in the Recipient Email field and click Send Test to send a test HTML and plaintext message.

Under the Hood (Developer Reference)

The plugin implements the standard SandboxedPlugin interface exposed by EmDash.

plugin:install Lifecycle Hook

Fires automatically when the plugin is registered in the CMS. It seeds default SMTP values (email-smtp.us-east-1.amazonaws.com on port 587) securely inside ctx.kv to ensure a smooth first-time startup.

email:deliver Event Handler

Registers with exclusive: true. This setting commands EmDash to bypass any default local SMTP transporters or falling-back configurations, sending the EmailDeliverEvent payload directly to the custom SES transport handler.

Local Development

If you want to contribute to this plugin, modify the source code, or test it locally, you must compile the TypeScript files into executable JavaScript:

1. Clone the repository and navigate to the directory:

   git clone https://github.com/ab6162/emdash-aws-ses.git
   cd emdash-aws-ses

2. Install the local development dependencies:

   npm install

3. Build the distribution files:

   npm run build

This will generate the /dist directory containing the ESM and CommonJS compiled outputs.

License

This project is licensed under the MIT License. See the LICENSE file for more details.