SendGrid

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

InstallationCopy Anchor Link

npm install @effect-kit/emails effect @sendgrid/mail@8.1.6

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

SetupCopy Anchor Link

SendGrid.layerConfig() reads these variables:

Example (Sending a Message With SendGrid)

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

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

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

SendGrid reports this in email.capabilities:

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

• More than one replyTo address (feature multipleReplyTo).
• An idempotencyKey (feature idempotency).

IdempotencyCopy Anchor Link

Not supported. A key fails with UnsupportedFeatureError before sending.

Provider notesCopy Anchor Link

• SendGrid takes one reply-to address. A second replyTo address fails before sending with feature multipleReplyTo.
• A send is accepted only on an HTTP 202 response. Any other success status fails with UnexpectedResponseError. The receipt's reference is the x-message-id response header, and references is empty when the header is missing.

Using your own clientCopy Anchor Link

layerClient takes any object with send(message), which the @sendgrid/mail mail service has. options is optional.

Example (Borrowing a SendGrid Client)

import sgMail from "@sendgrid/mail";
import * as SendGrid from "@effect-kit/emails/sendgrid";

sgMail.setApiKey("SG.fake_key");

const EmailLive = SendGrid.layerClient(sgMail);

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: "sendgrid" 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".