SES

Lightweight, dependency-free fake of AWS SES (Simple Email Service, the classic v1 API) that speaks the real SES AWS Query wire protocol (form-encoded requests, XML responses, API version 2010-12-01), so application code using @aws-sdk/client-ses can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { SesServer } from "./services/ses/src/server.js";

const server = new SesServer(4570);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  SESClient,
  VerifyEmailIdentityCommand,
  SendEmailCommand,
} from "@aws-sdk/client-ses";

const ses = new SESClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4570",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

// Verify a sender (auto-verified in the fake)
await ses.send(new VerifyEmailIdentityCommand({ EmailAddress: "sender@example.com" }));

// Send an email
const { MessageId } = await ses.send(
  new SendEmailCommand({
    Source: "sender@example.com",
    Destination: { ToAddresses: ["dest@example.com"] },
    Message: {
      Subject: { Data: "Hello" },
      Body: { Text: { Data: "World" } },
    },
  }),
);

Implemented operations

All 71 operations exposed by @aws-sdk/client-ses are implemented.

Identities & verification

• VerifyEmailAddress (legacy) — auto-verifies an email
• VerifyEmailIdentity — auto-verifies an email
• VerifyDomainIdentity — returns a VerificationToken
• VerifyDomainDkim — returns 3 deterministic DkimTokens
• DeleteIdentity
• DeleteVerifiedEmailAddress (legacy)
• ListIdentities — supports IdentityType, MaxItems, NextToken
• ListVerifiedEmailAddresses (legacy)
• GetIdentityVerificationAttributes
• GetIdentityDkimAttributes
• SetIdentityDkimEnabled
• GetIdentityMailFromDomainAttributes
• SetIdentityMailFromDomain
• GetIdentityNotificationAttributes
• SetIdentityNotificationTopic
• SetIdentityFeedbackForwardingEnabled
• SetIdentityHeadersInNotificationsEnabled

Identity policies

• PutIdentityPolicy
• GetIdentityPolicies
• ListIdentityPolicies
• DeleteIdentityPolicy

Sending

• SendEmail — enforces verified Source, requires recipients + subject/body
• SendRawEmail — extracts From: for verification when Source is omitted
• SendTemplatedEmail — requires an existing template, validates TemplateData JSON
• SendBulkTemplatedEmail — returns per-destination Status
• SendCustomVerificationEmail
• SendBounce

Account & statistics

• GetSendQuota — Max24HourSend, MaxSendRate, SentLast24Hours
• GetSendStatistics
• GetAccountSendingEnabled
• UpdateAccountSendingEnabled — pausing blocks all Send* calls

Email templates

• CreateTemplate
• GetTemplate
• UpdateTemplate
• DeleteTemplate (idempotent)
• ListTemplates
• TestRenderTemplate — {{placeholder}} substitution, errors on missing data

Custom verification email templates

• CreateCustomVerificationEmailTemplate
• GetCustomVerificationEmailTemplate
• UpdateCustomVerificationEmailTemplate
• DeleteCustomVerificationEmailTemplate
• ListCustomVerificationEmailTemplates

Configuration sets

• CreateConfigurationSet
• DescribeConfigurationSet — honors ConfigurationSetAttributeNames
• DeleteConfigurationSet
• ListConfigurationSets
• PutConfigurationSetDeliveryOptions
• UpdateConfigurationSetReputationMetricsEnabled
• UpdateConfigurationSetSendingEnabled

Configuration set event destinations

• CreateConfigurationSetEventDestination
• UpdateConfigurationSetEventDestination
• DeleteConfigurationSetEventDestination

Configuration set tracking options

• CreateConfigurationSetTrackingOptions
• UpdateConfigurationSetTrackingOptions
• DeleteConfigurationSetTrackingOptions

Receipt rule sets & rules

• CreateReceiptRuleSet
• DeleteReceiptRuleSet — refuses to delete the active set
• DescribeReceiptRuleSet
• ListReceiptRuleSets
• CloneReceiptRuleSet
• DescribeActiveReceiptRuleSet
• SetActiveReceiptRuleSet
• ReorderReceiptRuleSet
• CreateReceiptRule — supports After positioning
• UpdateReceiptRule
• DeleteReceiptRule
• DescribeReceiptRule
• SetReceiptRulePosition

Receipt filters

• CreateReceiptFilter
• DeleteReceiptFilter
• ListReceiptFilters

Internal (non-SES) endpoints

server.reset() resets all state in-process as well.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors are returned as standard AWS Query XML with a non-2xx status:

<?xml version="1.0"?>
<ErrorResponse xmlns="http://ses.amazonaws.com/doc/2010-12-01/">
  <Error>
    <Type>Sender</Type>
    <Code>MessageRejected</Code>
    <Message>Email address is not verified. ...</Message>
  </Error>
  <RequestId>...</RequestId>
</ErrorResponse>

Type is Sender for 4xx (client fault) and Receiver for 5xx (server fault). Common codes:

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SES=http://parlel-bridge:4570
AWS_ENDPOINT_URL=http://parlel-bridge:4570