Mailgun

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

InstallationCopy Anchor Link

npm install @effect-kit/emails effect mailgun.js@14.1.0 form-data@4.0.5

Both packages are pinned peers and optional until you import this subpath.

SetupCopy Anchor Link

Mailgun.layerConfig() reads these variables:

Example (Sending a Message With Mailgun)

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

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

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

Mailgun 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

• region: "eu" uses https://api.eu.mailgun.net and region: "us" uses https://api.mailgun.net. endpoint replaces both.
• Mailgun has no inline image support here. Every attachment goes out as a regular attachment, so a contentId fails before sending with feature inlineAttachments.
• Install form-data next to mailgun.js. Both are pinned peers.

Using your own clientCopy Anchor Link

layerClient takes any object with messages.create(domain, message), which a mailgun.js client has. Unlike most providers its options are required, because they carry the domain.

Example (Borrowing a Mailgun Client)

import FormData from "form-data";
import Mailgun from "mailgun.js";
import * as MailgunEmail from "@effect-kit/emails/mailgun";

const client = new Mailgun(FormData).client({ username: "api", key: "fake-key" });

const EmailLive = MailgunEmail.layerClient(client, { domain: "mg.example.com" });

You own a borrowed client. The Layer never closes it, and the client keeps its own retry, timeout and logging policy. The client is created with its own region and URL, so layerClient does not take a region.

ErrorsCopy Anchor Link

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

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