Azure Communication Services

The @effect-kit/emails/azure subpath sends messages through Azure Communication Services Email and provides the Email service.

InstallationCopy Anchor Link

npm install @effect-kit/emails effect @azure/communication-email@1.1.0

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

SetupCopy Anchor Link

Azure.layerConfig() reads these variables:

Example (Sending a Message With Azure Communication Services Email)

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

const EmailLive = Azure.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 Azure Communication Services Email account is allowed to send from.

OptionsCopy Anchor Link

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

CapabilitiesCopy Anchor Link

Azure Communication Services Email reports this in email.capabilities:

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

• A display name on from (feature senderName).
• An idempotencyKey (feature idempotency).

IdempotencyCopy Anchor Link

Not supported. A key fails with UnsupportedFeatureError before sending.

Provider notesCopy Anchor Link

• Azure sends are long-running operations. The Layer starts the operation, polls it every pollInterval and resolves when it finishes, so timeout covers the whole operation and defaults to 60 seconds.
• The send is accepted when the operation status is Succeeded. Failed or Canceled fails with MessageRejectedError and acceptance: "rejected". Any other final status fails with UnexpectedResponseError.
• The receipt's reference has kind operationId. Failures after the operation started carry that reference in references.
• Azure takes the sender address only. A display name on from fails before sending with feature senderName. Set the sender display name in Azure.
• The owned client is created with maxRetries: 0.

Using your own clientCopy Anchor Link

layerClient takes any object with beginSend(message, options) that returns a poller with pollUntilDone, stopPolling and getResult, which an EmailClient does. options is optional and accepts timeout and pollInterval.

Example (Borrowing a Azure Communication Services Email Client)

import { EmailClient } from "@azure/communication-email";
import * as Azure from "@effect-kit/emails/azure";

const client = new EmailClient("endpoint=https://example.communication.azure.com/;accesskey=fake");

const EmailLive = Azure.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

Layer construction fails with AzureConfigurationError, whose field names the bad option. layerClient fails with it for the client options.

REST errors use the HTTP status with the shared mapping. Once an operation id is known, the acceptance of a failure is unknown so you can reconcile it. Kept providerCode values are ServiceUnavailable and REQUEST_SEND_ERROR.