Amazon SES

The @effect-kit/emails/ses subpath sends messages through Amazon SES and provides the Email service.

InstallationCopy Anchor Link

npm install @effect-kit/emails effect @aws-sdk/client-sesv2@3.1157.0

The SDK is a pinned optional peer. It is needed only when you import this subpath.

SetupCopy Anchor Link

Ses.layerConfig() reads these variables:

Credentials are not read by layerConfig. They come from the AWS SDK default credential chain.

Example (Sending a Message With Amazon SES)

import { ConfigProvider, Effect, Layer } from "effect";
import { Email } from "@effect-kit/emails";
import * as Ses from "@effect-kit/emails/ses";

const EmailLive = Ses.layerConfig().pipe(
  Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnv())),
);

const program = Effect.gen(function* () {
  const email = yield* Email;
  return yield* email.send({
    from: "hello@example.com",
    to: "ada@example.com",
    subject: "Welcome",
    text: "Your account is ready.",
  });
});

Effect.runPromise(program.pipe(Effect.provide(EmailLive)));

Use a from address your Amazon SES account is allowed to send from.

OptionsCopy Anchor Link

Ses.layer takes these options. layerConfig builds the same object from a Config.

CapabilitiesCopy Anchor Link

Amazon SES reports this in email.capabilities:

These fail with UnsupportedFeatureError and acceptance: "notSubmitted" before any request:

• An idempotencyKey (feature idempotency).

IdempotencyCopy Anchor Link

Not supported. A key fails with UnsupportedFeatureError before sending.

Provider notesCopy Anchor Link

• layerConfig reads only AWS_REGION. Credentials resolve through the AWS SDK default chain (environment, shared files, instance or task roles). To pass keys yourself, use layer with credentials.
• The owned client is built with maxAttempts: 1, so the AWS SDK never retries a send. The Layer destroys it when its scope closes.
• Messages go out as SES v2 Simple content. Attachments with a contentId are sent with ContentDisposition: INLINE.
• The receipt's reference is the SES MessageId, and requestId comes from the SDK response metadata.

Using your own clientCopy Anchor Link

layerClient takes any object with send(command, { abortSignal }), which an SESv2Client has. options is optional and accepts timeout and configurationSetName.

Example (Borrowing a Amazon SES Client)

import { SESv2Client } from "@aws-sdk/client-sesv2";
import * as Ses from "@effect-kit/emails/ses";

const client = new SESv2Client({ region: "eu-west-1", maxAttempts: 1 });

const EmailLive = Ses.layerClient(client, { configurationSetName: "transactional" });

You own a borrowed client. The Layer never closes it, and the client keeps its own retry, timeout and logging policy. Set maxAttempts: 1 on a client you own if you want the same no-retry behavior as the owned client.

ErrorsCopy Anchor Link

Layer construction fails with SesConfigurationError, whose field names the bad option. layerClient fails with it for the client options.

The SES error name is kept as providerCode. CredentialsProviderError and TokenProviderError are acceptance: "notSubmitted" because no request was made. For other errors acceptance follows the HTTP status: rejected for a 4xx other than 409, unknown otherwise.

Any other HTTP status uses the shared mapping: 401 is AuthenticationError, 403 PermissionDeniedError, 429 RateLimitedError, 400 and 422 InvalidMessageError, 5xx ProviderUnavailableError, and anything else ProviderError. acceptance is rejected for a 4xx status other than 409 and unknown otherwise. See Errors.