Star
Packages

@notifkit/provider-ses

Email through AWS SES, built on the AWS SDK's SESv2 client. Credentials come from the SDK's default chain, so it runs on an EC2, ECS or Lambda role with no keys in your config.

Sending only, for now

This package doesn't read SES bounce and complaint notifications yet, so notifkit doesn't suppress an address that bounced and will keep mailing it. SES reviews, and can pause, an account whose bounce or complaint rate climbs. Until bounce handling lands, keep the SES account-level suppression list on for bounces and complaints, so SES drops mail to those addresses itself: aws sesv2 put-account-suppression-attributes --suppressed-reasons BOUNCE COMPLAINT

npm install @notifkit/provider-ses
import { NotifkitServer } from "notifkit";
import { SesTransport } from "@notifkit/provider-ses";

const ses = new SesTransport({
  region: "eu-west-1",
  from: "Acme <[email protected]>",
  limits: { limit: 14, windowSeconds: 1 }, // your account's maximum send rate
});

const server = new NotifkitServer({
  services: ["all"],
  providers: [ses],
});

A recipient's email contact target is the destination, so it holds their address:

await notifkit.addContact("usr_123", { channel: "email", target: "[email protected]" });

AWS setup

  • Credentials come from the AWS SDK's default chain: the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, a profile in the shared config, SSO, or the IAM role of the machine. That identity needs the ses:SendEmail permission.
  • The from address, or its domain, has to be a verified SES identity. While the account is in the SES sandbox, recipients have to be verified too.
  • limits is your account's maximum send rate, so a burst waits its turn instead of being throttled. The SES console shows it under Sending limits on the Account dashboard, and aws sesv2 get-account returns it as SendQuota.MaxSendRate. It's set per region, and in the sandbox it's 1 a second.

Options

OptionRequiredNotes
fromyesDefault sender, a verified identity. A template may override it.
limitsyesSend rate, { limit, windowSeconds }. No default, since send rates differ from one account to the next. The constructor throws without it.
regionnoThe SES account's region. Without it the SDK reads AWS_REGION or the shared config.
clientnoAn SESv2Client you built yourself, for custom credentials or settings. It's used as is, so its retry and timeout settings are yours, and close() leaves it open.
configurationSetNamenoSES configuration set to send with, such as one that publishes events.
loggernoA notifkit logger.

Which template keys it reads

Template keyLands as
subjectThe subject line. Defaults to "Notification".
text or bodyThe plain-text part.
htmlBody or htmlThe HTML part. A text-only template gets one built from the escaped text.
fromOverrides the constructor's sender, for this template only.
replyToSent only when present.

The List-Unsubscribe headers notifkit adds to topic mail are passed through. SES's MessageId becomes the delivery's provider message ID.

Failures and retries

The transport decides from the error SES returns:

What happenedResult
A 4xx refusal: a rejected message, an unverified sender or MAIL FROM domain, a bad address, a paused or suspended account, a configuration set that doesn't existFails, no retry
Throttling (ThrottlingException, TooManyRequestsException, LimitExceededException), even when SES sends it as a 400Retried
408, 429, 5xx, timeouts, network errorsRetried

A retry gets past a short spike over the send rate, but not the daily quota, which resets over 24 hours. Keep your quota above your daily volume.

The client the transport builds has the SDK's own retries turned off, because notifkit already retries with backoff. Each send is cancelled when it reaches notifkit's send timeout, 10 seconds by default.

No idempotency

SES has no idempotency key. If SES accepts a message but its reply is lost, for example to a timeout, the retry sends the message a second time.

Shutting down

From notifkit 0.1.20, server.stop() closes the transport, which closes the connections of the client it built. On older versions, call close() yourself. A client you passed in stays open for you to close.

await server.stop();
ses.close();