Postmark

The @effect-kit/emails/postmark subpath sends messages through Postmark and provides the Email service.

InstallationCopy Anchor Link

npm install @effect-kit/emails effect postmark@5.1.0

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

SetupCopy Anchor Link

Postmark.layerConfig() reads these variables:

Example (Sending a Message With Postmark)

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

const EmailLive = Postmark.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 Postmark account is allowed to send from.

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

Postmark 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

• Set messageStream to send through a stream other than the server's default. It is sent as MessageStream on every message, so it also applies to layerClient through options.
• A Postmark ErrorCode other than 0 in a successful response fails the send with acceptance: "rejected".

Using your own clientCopy Anchor Link

layerClient takes any object with sendEmail(message), which a ServerClient has. options is optional and accepts timeout and messageStream.

Example (Borrowing a Postmark Client)

import { ServerClient } from "postmark";
import * as Postmark from "@effect-kit/emails/postmark";

const client = new ServerClient("fake-server-token");

const EmailLive = Postmark.layerClient(client, { messageStream: "outbound" });

You own a borrowed client. The Layer never closes it, and the client keeps its own retry, timeout and logging policy.

ErrorsCopy Anchor Link

ProviderConfigurationError carries provider: "postmark" and a field naming the bad option. Layer construction fails with it, and layerClient fails with it for the client options.

The SDK error's statusCode and code become statusCode and providerCode. Postmark codes kept as providerCode are 0, 10, 401, 406 and 429.

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.