Messages

A message is a plain object. email.send validates it, checks it against the provider's capabilities, then submits it.

Example (Sending a Message With Names, Copies and Headers)

import { Effect } from "effect";
import { Email } from "@effect-kit/emails";

const program = Effect.gen(function* () {
  const email = yield* Email;
  const receipt = yield* email.send({
    from: { email: "hello@example.com", name: "Example Team" },
    to: [{ email: "ada@example.com", name: "Ada" }, "grace@example.com"],
    cc: "support@example.com",
    replyTo: "support@example.com",
    subject: "Your order has shipped",
    text: "Order 1042 is on its way.",
    html: "<p>Order 1042 is on its way.</p>",
    headers: { "X-Order-Id": "1042" },
  });
  return receipt.status;
          
Copy Text
const receipt: {
    readonly provider: string;
    readonly status: "accepted" | "partiallyAccepted";
    readonly references: readonly {
        readonly kind: "operationId" | "providerMessageId" | "smtpMessageId";
        readonly value: string;
    }[];
    readonly requestId?: string | undefined;
    readonly recipients?: ... | undefined;
}
});

FieldsCopy Anchor Link

These fields are the whole model. There are no tags, metadata, scheduling, template id or per-recipient data fields.

AddressesCopy Anchor Link

An address is either a bare email string or a Mailbox object with an email and an optional name. A string like "Ada <ada@example.com>" is invalid: put the display name in the name field.

The email must be ASCII, at most 254 characters, with a local part of at most 64. Internationalized domains and quoted local parts are not accepted.

to, cc, bcc and replyTo take one address or a non-empty list. Whether a provider accepts a display name or more than one reply-to depends on its capabilities.

HeadersCopy Anchor Link

Header names are unique ignoring case, and values cannot contain control characters. These names are reserved and rejected:

from, sender, to, cc, bcc, reply-to, subject, date, message-id, mime-version, return-path, received, authentication-results, dkim-signature, authorization, proxy-authorization, host, idempotency-key, x-smtpapi

Names that start with content-, resent-, resend-, x-ses-, x-mc-, x-mailgun-, x-mailin- or x-pm- are also rejected.

Send optionsCopy Anchor Link

email.send takes a second argument, SendOptions, whose only field is idempotencyKey. Only some providers support it, so check Choosing a provider.