AWS SES email provider for Cloudflare Workers (full source) — and why the form working does not mean the CMS can send

[marks-zyz]

We run three client sites on EmDash + Cloudflare Workers. All of them need email that actually leaves the building: magic-link login, user invites, and form notifications. On Workers there was no provider we could use, so we wrote one for AWS SES and it has been in production since yesterday. Sharing the whole thing here because I could not find a single SES discussion in this repo, and #1770 / #1431 / #245 all circle the same gap.

Why not the existing options

• cloudflareEmail() needs domain onboarding in Cloudflare Email Sending, and cloudflareEmail() provider never calls binding.send() — magic-link email silently not delivered #2253 reports it never calling binding.send().
• The console provider is a dev stub.
• npm has emdash-plugin-resend and emdash-smtp, but we were already on SES for the rest of our stack and wanted one sender identity, one bounce/complaint dashboard, one DKIM setup.

The one thing that cost us a day

The failure mode is silent and it is not obvious from the error. Our contact form had been delivering through SES for weeks with the same AWS_* secrets in the Worker, so we assumed the CMS would use them too. It does not. The form endpoint was our own code calling SES directly; the CMS delivers through the email:deliver hook, and that hook is empty until a plugin registers for it. Same credentials, same Worker, two completely separate paths. The login page just says "Email is not configured", which is accurate but does not point at the cause.

Second gotcha, smaller: hooks run outside the request context, so Astro.locals.runtime.env is not available. The env has to come from import("cloudflare:workers"), which works both deployed and under astro dev with the adapter.

Wiring

astro.config.mjs:

import emdash from 'emdash/astro';
import { d1, r2 } from '@emdash-cms/cloudflare';
import { sesEmail } from './src/cms/plugins/ses-email.ts';

emdash({
  database: d1({ binding: 'DB' }),
  storage: r2({ binding: 'MEDIA' }),
  plugins: [sesEmail()],
})

Secrets (wrangler secret put), never in code:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION              # same region as the verified identity
AWS_SES_FROM_EMAIL      # must be a verified SES identity
CONTACT_TO_EMAIL        # optional, becomes Reply-To

Then select it once, in Settings > Email, or over the API:

curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  --data '{"pluginId":"ses-email"}' \
  "https://your-site/_emdash/api/admin/hooks/exclusive/email:deliver"

Note the hook name goes raw in the URL. Percent-encoding the colon returns "Invalid hook name format".

Proof it works, since the HTTP response is deliberately generic:

curl -s -X POST -H 'Content-Type: application/json' \
  --data '{"email":"you@example.com"}' https://your-site/_emdash/api/auth/magic-link/send
npx wrangler tail your-worker --format pretty
# [plugin:ses-email] email delivered via AWS SES

Also worth knowing: the route is /auth/magic-link/send, not /request (that 404s quietly).

The plugin

Single file, no build step, no package to install beyond aws4fetch (~4 kB, fetch + SubtleCrypto, made for Workers). The AWS SDK does not fit: Node built-ins and a much bigger bundle.

// src/cms/plugins/ses-email.ts
//
// AWS SES v2 email provider for EmDash, as a LOCAL native plugin.
// Runs on Cloudflare Workers: SigV4 is signed with aws4fetch (fetch + SubtleCrypto only).
// The AWS SDK does not fit here — it pulls Node built-ins and inflates the bundle.
//
// Secrets are read from the Worker env at delivery time. Nothing is hardcoded.
//   AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_SES_FROM_EMAIL
//   CONTACT_TO_EMAIL (optional, used as Reply-To)

import type { PluginContext, PluginDescriptor, ResolvedPlugin } from 'emdash';
import { definePlugin } from 'emdash';
import type { EmailDeliverEvent } from 'emdash/plugin';
import { AwsClient } from 'aws4fetch';

export interface SesEmailConfig {
  /** Sender. Defaults to AWS_SES_FROM_EMAIL. Must be a verified identity in the same region. */
  from?: string | { email: string; name?: string };
  /** Reply-To. Defaults to CONTACT_TO_EMAIL. */
  replyTo?: string;
  /** SES region. Defaults to AWS_REGION, then us-east-1. */
  region?: string;
  /** Optional SES Configuration Set (metrics, suppression list). */
  configurationSet?: string;
}

/**
 * Hooks run outside the request context, so the env cannot come from `Astro.locals.runtime`.
 * `cloudflare:workers` exposes the same env to any code bundled into the Worker, including
 * under `astro dev` with the Cloudflare adapter.
 */
async function loadWorkerEnv(): Promise<Record<string, unknown>> {
  try {
    const mod = await import('cloudflare:workers');
    return mod.env as unknown as Record<string, unknown>;
  } catch {
    throw new Error('[ses-email] cloudflare:workers unavailable: this provider only runs on the Workers runtime.');
  }
}

function readString(env: Record<string, unknown>, name: string): string | undefined {
  const v = env[name];
  return typeof v === 'string' && v.length > 0 ? v : undefined;
}

function formatFrom(from: NonNullable<SesEmailConfig['from']>): string {
  if (typeof from === 'string') return from;
  return from.name ? `${from.name} <${from.email}>` : from.email;
}

/** Exported for tests; production goes through {@link sesEmail}. */
export function createSesEmailDeliver(
  config: SesEmailConfig,
  loadEnv: () => Promise<Record<string, unknown>> = loadWorkerEnv,
): (event: EmailDeliverEvent, ctx: PluginContext) => Promise<void> {
  return async (event, ctx) => {
    const { message } = event;
    const env = await loadEnv();

    const accessKeyId = readString(env, 'AWS_ACCESS_KEY_ID');
    const secretAccessKey = readString(env, 'AWS_SECRET_ACCESS_KEY');
    const region = config.region ?? readString(env, 'AWS_REGION') ?? 'us-east-1';
    if (!accessKeyId) throw new Error('[ses-email] missing secret AWS_ACCESS_KEY_ID');
    if (!secretAccessKey) throw new Error('[ses-email] missing secret AWS_SECRET_ACCESS_KEY');

    const fromEnv = readString(env, 'AWS_SES_FROM_EMAIL');
    const from = config.from ?? fromEnv;
    const fromEmail = typeof from === 'string' ? from : from?.email;
    if (!from || !fromEmail?.includes('@')) {
      throw new Error('[ses-email] no sender: set AWS_SES_FROM_EMAIL or sesEmail({ from }). Must be a verified SES identity.');
    }

    const aws = new AwsClient({ accessKeyId, secretAccessKey, service: 'ses', region });
    const to = Array.isArray(message.to) ? message.to : [message.to];
    const replyTo = config.replyTo ?? readString(env, 'CONTACT_TO_EMAIL');

    const body: Record<string, unknown> = {
      FromEmailAddress: formatFrom(from),
      Destination: { ToAddresses: to },
      Content: {
        Simple: {
          Subject: { Data: message.subject, Charset: 'UTF-8' },
          Body: {
            ...(message.html ? { Html: { Data: message.html, Charset: 'UTF-8' } } : {}),
            ...(message.text ? { Text: { Data: message.text, Charset: 'UTF-8' } } : {}),
          },
        },
      },
    };
    if (replyTo) body.ReplyToAddresses = [replyTo];
    if (config.configurationSet) body.ConfigurationSetName = config.configurationSet;

    const response = await aws.fetch(`https://email.${region}.amazonaws.com/v2/email/outbound-emails`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      // The SES error body names the cause: unverified identity, sandbox, throttling.
      const detail = await response.text().catch(() => '');
      throw new Error(`[ses-email] SES returned ${response.status}: ${detail.slice(0, 500)}`);
    }
    const result = (await response.json().catch(() => ({}))) as { MessageId?: string };
    ctx.log.info('email delivered via AWS SES', { to: message.to, subject: message.subject, messageId: result?.MessageId });
  };
}

/** Called by the `virtual:emdash/plugins` module with the descriptor options. */
export function createPlugin(config: SesEmailConfig = {}): ResolvedPlugin {
  return definePlugin({
    id: 'ses-email',
    version: '1.0.0',
    capabilities: ['hooks.email-transport:register'],
    hooks: {
      'email:deliver': { exclusive: true, handler: createSesEmailDeliver(config) },
    },
  });
}

/** Descriptor for the `plugins` array of the emdash() integration. */
export function sesEmail(config: SesEmailConfig = {}): PluginDescriptor<SesEmailConfig> {
  return {
    id: 'ses-email',
    version: '1.0.0',
    entrypoint: '/src/cms/plugins/ses-email.ts', // project-root path: how Vite resolves it
    format: 'native',
    options: config,
    capabilities: ['hooks.email-transport:register'],
  };
}

export default sesEmail;

Notes from production

• Sandbox: a fresh SES account only delivers to verified addresses. With a CMS, every site depends on email from day one, because it is the login. Check this before launch, not after.
• SPF, DKIM and DMARC on the sender domain, or Gmail files the magic link under spam and the client tells you "the link never arrives".
• The SES error body names the cause (unverified identity, sandbox, throttling), so it is worth surfacing it in the thrown error rather than swallowing it — that is the detail.slice(0, 500) above.
• retries are not handled here: email:deliver is exclusive and a throw surfaces to the caller. Idempotency keys (Add optional idempotency keys to plugin email sends #2484) would help.

Happy to turn this into a published package if there is interest, or to send it as an official @emdash-cms/plugin-ses PR if the maintainers would rather have it in the box alongside the Cloudflare provider. Either way, the code above is MIT — take it.