@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.
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_IDandAWS_SECRET_ACCESS_KEYenvironment variables, a profile in the shared config, SSO, or the IAM role of the machine. That identity needs theses:SendEmailpermission. - The
fromaddress, or its domain, has to be a verified SES identity. While the account is in the SES sandbox, recipients have to be verified too. limitsis 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, andaws sesv2 get-accountreturns it asSendQuota.MaxSendRate. It's set per region, and in the sandbox it's 1 a second.
Options
| Option | Required | Notes |
|---|---|---|
from | yes | Default sender, a verified identity. A template may override it. |
limits | yes | Send rate, { limit, windowSeconds }. No default, since send rates differ from one account to the next. The constructor throws without it. |
region | no | The SES account's region. Without it the SDK reads AWS_REGION or the shared config. |
client | no | An 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. |
configurationSetName | no | SES configuration set to send with, such as one that publishes events. |
logger | no | A notifkit logger. |
Which template keys it reads
| Template key | Lands as |
|---|---|
subject | The subject line. Defaults to "Notification". |
text or body | The plain-text part. |
htmlBody or html | The HTML part. A text-only template gets one built from the escaped text. |
from | Overrides the constructor's sender, for this template only. |
replyTo | Sent 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 happened | Result |
|---|---|
| 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 exist | Fails, no retry |
Throttling (ThrottlingException, TooManyRequestsException, LimitExceededException), even when SES sends it as a 400 | Retried |
| 408, 429, 5xx, timeouts, network errors | Retried |
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.
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();