Plunk

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

InstallationCopy Anchor Link

npm install @effect-kit/emails effect @plunk/node@3.0.3

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

SetupCopy Anchor Link

Plunk.layerConfig() reads these variables:

Example (Sending a Message With Plunk)

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

const EmailLive = Plunk.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",
    html: "<p>Your account is ready.</p>",
  });
});

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

Use a from address your Plunk account is allowed to send from.

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

Plunk reports this in email.capabilities:

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

• A text body (feature text).
• A cc list (feature cc).
• A bcc list (feature bcc).
• Any replyTo address (feature replyTo).
• Any custom header (feature headers).
• Any attachment (feature attachments).
• An idempotencyKey (feature idempotency).

IdempotencyCopy Anchor Link

Not supported. A key fails with UnsupportedFeatureError before sending.

Provider notesCopy Anchor Link

• Plunk is HTML only. A message needs html and exactly one to address without a name. A text-only message fails the capability check, and a message without html or with a named or second recipient fails with InvalidMessageError (path to).
• Only from, the sender name, to, subject and the HTML body are sent. Anything else fails the capability check first: text, cc, bcc, replyTo, headers and attachments.
• The @plunk/node package is marked as no longer supported on npm. Pin it to the version above.
• A send is accepted when Plunk reports the recipient as queued. The status throttled or skipped fails with MessageRejectedError. The receipt's single reference is the recipient address.

Using your own clientCopy Anchor Link

layerClient takes any object with emails.send({ to, from, name, subject, body }), which a Plunk client has. options is optional.

Example (Borrowing a Plunk Client)

import Plunk from "@plunk/node";
import * as PlunkEmail from "@effect-kit/emails/plunk";

const client = new Plunk("sk_fake_key");

const EmailLive = PlunkEmail.layerClient(client);

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: "plunk" and a field naming the bad option. Layer construction fails with it, and layerClient fails with it for the client options.

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. A network failure with no status is TransportError, and ETIMEDOUT or ECONNABORTED is TimeoutError, both with acceptance: "unknown".