Mailchimp Transactional

The @effect-kit/emails/mailchimp-transactional subpath sends messages through Mailchimp Transactional and provides the Email service.

InstallationCopy Anchor Link

npm install @effect-kit/emails effect @mailchimp/mailchimp_transactional@1.4.1

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

SetupCopy Anchor Link

MailchimpTransactional.layerConfig() reads these variables:

Example (Sending a Message With Mailchimp Transactional)

import { ConfigProvider, Effect, Layer } from "effect";
import { Email } from "@effect-kit/emails";
import * as MailchimpTransactional from "@effect-kit/emails/mailchimp-transactional";

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

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

Mailchimp Transactional reports this in email.capabilities:

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

• An attachment with a contentId (feature inlineAttachments).
• An idempotencyKey (feature idempotency).

IdempotencyCopy Anchor Link

Not supported. A key fails with UnsupportedFeatureError before sending.

Provider notesCopy Anchor Link

• Recipients are sent with preserve_recipients: true, so every to, cc and bcc recipient is listed in the message headers each recipient sees.
• Mailchimp answers per recipient. The statuses sent, queued and scheduled count as accepted, and rejected and invalid as rejected. Any other status fails with UnexpectedResponseError.
• When some recipients are rejected the receipt is partiallyAccepted with one outcome per recipient. When all are rejected the send fails with MessageRejectedError. A hard_bounce reject reason is kept as rejectionCode.

Using your own clientCopy Anchor Link

layerClient takes any object with messages.send(body), which the client returned by the SDK has. options is optional.

Example (Borrowing a Mailchimp Transactional Client)

import mailchimp from "@mailchimp/mailchimp_transactional";
import * as MailchimpTransactional from "@effect-kit/emails/mailchimp-transactional";

const client = mailchimp("fake-key");

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

Other status: "error" responses fail with ProviderError and acceptance: "rejected". The error name is kept as providerCode only for the two names above.

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