@upyo/smtp 0.6.0-dev.305 → 0.6.0-dev.306

package/README.md

@@ -219,13 +219,50 @@ structure.
 [RFC 3463]: https://www.rfc-editor.org/rfc/rfc3463
 
 
+Envelope overrides
+------------------
+
+Use the `envelope` send option when the SMTP reverse-path or recipients must
+differ from the visible message headers:
+
+~~~~ typescript
+const receipt = await transport.send(message, {
+  envelope: {
+    from: "bounces+customer-42@bounce.example.com",
+    to: ["delivery@example.net"],
+  },
+});
+~~~~
+
+Omitting `from` or `to` keeps the value derived from the message.  Set `from`
+to `null` to send `MAIL FROM:<>`.  The override changes only `MAIL FROM` and
+`RCPT TO`; the From, To, Cc, Bcc, and Reply-To message fields remain unchanged.
+
+For bulk VERP delivery, pass a resolver that returns an override for each
+message:
+
+~~~~ typescript
+for await (const receipt of transport.sendMany(messages, {
+  envelope: (_message, index) => ({
+    from: `bounces+${index}@bounce.example.com`,
+  }),
+})) {
+  console.log(receipt);
+}
+~~~~
+
+A plain override applies to every message passed to `sendMany()`.  Invalid
+addresses and empty recipient lists return a non-retryable failed receipt with
+the code `smtp.envelope-invalid` before `MAIL FROM` is sent.
+
+
 Internationalized addresses
 ---------------------------
 
-The transport automatically negotiates [RFC 6531] SMTPUTF8 when any sender,
-recipient, or reply-to mailbox contains a non-ASCII character.  A supporting
-server must advertise both `SMTPUTF8` and `8BITMIME`; Upyo then sends
-`BODY=8BITMIME SMTPUTF8` on `MAIL FROM`.
+The transport automatically negotiates [RFC 6531] SMTPUTF8 when the effective
+SMTP envelope or a visible message-header mailbox contains a non-ASCII
+character.  A supporting server must advertise both `SMTPUTF8` and `8BITMIME`;
+Upyo then sends `BODY=8BITMIME SMTPUTF8` on `MAIL FROM`.
 
 If either capability is missing, delivery returns a non-retryable failed
 receipt with the code `smtp.smtputf8-unsupported` before the mail transaction
@@ -258,9 +295,10 @@ const receipt = await transport.send(message, {
 
 `envelopeId` and `return` become `ENVID` and `RET` parameters on `MAIL FROM`.
 Each recipient's `notify` and `originalRecipient` values become `NOTIFY` and
-`ORCPT` parameters on its `RCPT TO` command.  Upyo validates and `xtext`-escapes
-the values without adding them to the message headers.  `envelopeId` must not
-be empty, and `originalRecipient` must exactly match its envelope recipient.
+`ORCPT` parameters on its `RCPT TO` command.  Upyo validates them against the
+effective envelope, including any override, and `xtext`-escapes the values
+without adding them to the message headers.  `envelopeId` must not be empty,
+and `originalRecipient` must exactly match its envelope recipient.
 
 If the server does not advertise `DSN`, the transport returns a non-retryable
 failed receipt with the code `smtp.dsn-unsupported` before sending `MAIL FROM`.

package/dist/index.cjs

@@ -65,14 +65,14 @@ const NOTIFICATION_CONDITIONS = new Set([
 /**
 * Validates and serializes the RFC 3461 envelope parameters for a message.
 *
-* @param message The message whose SMTP envelope will carry the parameters.
+* @param envelope The effective SMTP envelope that will carry the parameters.
 * @param dsn The caller-supplied delivery status notification settings.
 * @returns Serialized parameters, or `undefined` when none were requested.
 * @throws {SmtpDsnValidationError} If any setting violates RFC 3461 or does
 * not correspond to the message envelope.
 * @internal
 */
-function resolveSmtpDsn(message, dsn) {
+function resolveSmtpDsn(envelope, dsn) {
 	if (dsn == null) return void 0;
 	if (typeof dsn !== "object" || Array.isArray(dsn)) throw new SmtpDsnValidationError("DSN options must be an object.");
 	const mailParameters = [];
@@ -87,11 +87,7 @@ function resolveSmtpDsn(message, dsn) {
 		assertParameterLength(parameter, 100, "ENVID");
 		mailParameters.push(parameter);
 	}
-	const envelopeRecipients = [
-		...message.recipients.map((recipient) => recipient.address),
-		...message.ccRecipients.map((recipient) => recipient.address),
-		...message.bccRecipients.map((recipient) => recipient.address)
-	];
+	const envelopeRecipients = envelope.to;
 	const envelopeRecipientSet = new Set(envelopeRecipients);
 	const configuredRecipients = dsn.recipients;
 	if (configuredRecipients != null && (typeof configuredRecipients !== "object" || Array.isArray(configuredRecipients))) throw new SmtpDsnValidationError("DSN recipient options must be an object.");
@@ -1075,7 +1071,7 @@ var SmtpConnection = class {
 		const dsn = message.envelope.dsn;
 		if (dsn != null && !this.capabilities.some((capability) => /^DSN[ \t]*$/i.test(capability))) throw new SmtpDsnUnsupportedError();
 		const mailDsnParameters = dsn == null || dsn.mailParameters.length === 0 ? "" : ` ${dsn.mailParameters.join(" ")}`;
-		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
+		const mailCommand = `MAIL FROM:<${message.envelope.from ?? ""}>${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
 		const recipientCommands = message.envelope.to.map((recipient, index) => {
 			const parameters = dsn?.recipientParameters[index] ?? [];
 			const suffix = parameters.length === 0 ? "" : ` ${parameters.join(" ")}`;
@@ -1227,6 +1223,52 @@ function decodeOAuth2Challenge(message) {
 	}
 }
 
+//#endregion
+//#region src/envelope.ts
+/**
+* Error produced when an effective SMTP envelope is invalid.
+*
+* @since 0.6.0
+*/
+var SmtpEnvelopeValidationError = class extends TypeError {
+	/**
+	* Creates an SMTP envelope validation error.
+	*
+	* @param message A description of the invalid envelope.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "SmtpEnvelopeValidationError";
+	}
+};
+/**
+* Resolves and validates the SMTP envelope for a message.
+*
+* @param message The message that supplies fields without an override.
+* @param override Optional sender and recipient overrides.
+* @returns The validated effective SMTP envelope.
+* @throws {SmtpEnvelopeValidationError} If the override or any effective
+* address is invalid, or if the effective recipient list is empty.
+* @internal
+*/
+function resolveSmtpEnvelope(message, override) {
+	if (override !== void 0 && (override === null || typeof override !== "object" || Array.isArray(override))) throw new SmtpEnvelopeValidationError("SMTP envelope options must be an object.");
+	const from = override?.from === void 0 ? message.sender.address : override.from;
+	if (from !== null && !(0, __upyo_core.isEmailAddress)(from)) throw new SmtpEnvelopeValidationError("SMTP envelope sender must be a valid email address or null.");
+	const recipients = override?.to === void 0 ? [
+		...message.recipients.map((recipient) => recipient.address),
+		...message.ccRecipients.map((recipient) => recipient.address),
+		...message.bccRecipients.map((recipient) => recipient.address)
+	] : override.to;
+	if (!Array.isArray(recipients)) throw new SmtpEnvelopeValidationError("SMTP envelope recipients must be an array.");
+	if (recipients.length === 0) throw new SmtpEnvelopeValidationError("SMTP envelope must contain at least one recipient.");
+	for (const [index, recipient] of recipients.entries()) if (!(0, __upyo_core.isEmailAddress)(recipient)) throw new SmtpEnvelopeValidationError(`SMTP envelope recipient at index ${index} must be a valid email address.`);
+	return {
+		from,
+		to: [...recipients]
+	};
+}
+
 //#endregion
 //#region src/dkim/canonicalize.ts
 /**
@@ -1512,27 +1554,24 @@ function arrayBufferToBase64(buffer) {
 * @param message The message to convert.
 * @param dkimConfig Optional DKIM signing configuration.
 * @param dsn Optional validated SMTP delivery status notification parameters.
+* @param resolvedEnvelope The validated effective SMTP envelope.
 * @returns The converted SMTP message.
 * @throws {RangeError} If a header contains a token that cannot be folded
 * within the RFC 5322 hard line-length limit.
 */
-async function convertMessage(message, dkimConfig, dsn) {
+async function convertMessage(message, dkimConfig, dsn, resolvedEnvelope = resolveSmtpEnvelope(message)) {
 	const envelope = {
-		from: message.sender.address,
-		to: [
-			...message.recipients.map((r) => r.address),
-			...message.ccRecipients.map((r) => r.address),
-			...message.bccRecipients.map((r) => r.address)
-		],
+		...resolvedEnvelope,
 		dsn
 	};
-	const requiresSmtpUtf8 = [
-		message.sender,
-		...message.recipients,
-		...message.ccRecipients,
-		...message.bccRecipients,
-		...message.replyRecipients
-	].some((address) => Array.from(address.address).some((character) => (character.codePointAt(0) ?? 0) > 127));
+	const headerAddresses = [
+		message.sender.address,
+		...message.recipients.map((address) => address.address),
+		...message.ccRecipients.map((address) => address.address),
+		...message.replyRecipients.map((address) => address.address)
+	];
+	const envelopeAddresses = [...envelope.from == null ? [] : [envelope.from], ...envelope.to];
+	const requiresSmtpUtf8 = [...headerAddresses, ...envelopeAddresses].some((address) => Array.from(address).some((character) => (character.codePointAt(0) ?? 0) > 127));
 	let raw = await buildRawMessage(message);
 	if (dkimConfig) try {
 		for (const sig of dkimConfig.signatures) {
@@ -1835,8 +1874,8 @@ var SmtpTransport = class {
 	* ```
 	*
 	* @param message The email message to send.
-	* @param options Optional transport options including `AbortSignal` for
-	*                cancellation.
+	* @param options Optional SMTP envelope, delivery status, and cancellation
+	*                settings.
 	* @returns A promise that resolves to a receipt indicating success or
 	*          failure.
 	* @throws {DOMException} If the operation is aborted through
@@ -1846,10 +1885,11 @@ var SmtpTransport = class {
 		options?.signal?.throwIfAborted();
 		let connection;
 		try {
-			const dsn = resolveSmtpDsn(message, options?.dsn);
+			const envelope = resolveEnvelopeOption(message, options?.envelope, 0);
+			const dsn = resolveSmtpDsn(envelope, options?.dsn);
 			connection = await this.getConnection(options?.signal);
 			options?.signal?.throwIfAborted();
-			const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
+			const smtpMessage = await convertMessage(message, this.config.dkim, dsn, envelope);
 			options?.signal?.throwIfAborted();
 			const result = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
@@ -1890,8 +1930,8 @@ var SmtpTransport = class {
 	* ```
 	*
 	* @param messages An iterable or async iterable of messages to send.
-	* @param options Optional transport options including `AbortSignal` for
-	*                cancellation.
+	* @param options Optional SMTP envelope, delivery status, and cancellation
+	*                settings.
 	* @returns An async iterable of receipts, one for each message.
 	* @throws {DOMException} If the operation is aborted through
 	*                        `options.signal`.
@@ -1913,50 +1953,57 @@ var SmtpTransport = class {
 		let connectionValid = true;
 		try {
 			const isAsyncIterable = Symbol.asyncIterator in messages;
-			if (isAsyncIterable) for await (const message of messages) {
-				options?.signal?.throwIfAborted();
-				if (!connectionValid) {
-					yield createSmtpFailure("Connection is no longer valid");
-					continue;
-				}
-				try {
-					const dsn = resolveSmtpDsn(message, options?.dsn);
-					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
+			if (isAsyncIterable) {
+				let index = 0;
+				for await (const message of messages) {
 					options?.signal?.throwIfAborted();
-					const result = await connection.sendMessage(smtpMessage, options?.signal);
-					yield {
-						successful: true,
-						messageId: result.messageId,
-						provider: "smtp",
-						rejectedRecipients: result.rejectedRecipients
-					};
-				} catch (error) {
-					options?.signal?.throwIfAborted();
-					if (!isReusableLocalFailure(error)) connectionValid = false;
-					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
-				}
-			}
-			else for (const message of messages) {
-				options?.signal?.throwIfAborted();
-				if (!connectionValid) {
-					yield createSmtpFailure("Connection is no longer valid");
-					continue;
+					if (!connectionValid) {
+						yield createSmtpFailure("Connection is no longer valid");
+						continue;
+					}
+					try {
+						const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+						const dsn = resolveSmtpDsn(envelope, options?.dsn);
+						const smtpMessage = await convertMessage(message, this.config.dkim, dsn, envelope);
+						options?.signal?.throwIfAborted();
+						const result = await connection.sendMessage(smtpMessage, options?.signal);
+						yield {
+							successful: true,
+							messageId: result.messageId,
+							provider: "smtp",
+							rejectedRecipients: result.rejectedRecipients
+						};
+					} catch (error) {
+						options?.signal?.throwIfAborted();
+						if (!isReusableLocalFailure(error)) connectionValid = false;
+						yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+					}
 				}
-				try {
-					const dsn = resolveSmtpDsn(message, options?.dsn);
-					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
+			} else {
+				let index = 0;
+				for (const message of messages) {
 					options?.signal?.throwIfAborted();
-					const result = await connection.sendMessage(smtpMessage, options?.signal);
-					yield {
-						successful: true,
-						messageId: result.messageId,
-						provider: "smtp",
-						rejectedRecipients: result.rejectedRecipients
-					};
-				} catch (error) {
-					options?.signal?.throwIfAborted();
-					if (!isReusableLocalFailure(error)) connectionValid = false;
-					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+					if (!connectionValid) {
+						yield createSmtpFailure("Connection is no longer valid");
+						continue;
+					}
+					try {
+						const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+						const dsn = resolveSmtpDsn(envelope, options?.dsn);
+						const smtpMessage = await convertMessage(message, this.config.dkim, dsn, envelope);
+						options?.signal?.throwIfAborted();
+						const result = await connection.sendMessage(smtpMessage, options?.signal);
+						yield {
+							successful: true,
+							messageId: result.messageId,
+							provider: "smtp",
+							rejectedRecipients: result.rejectedRecipients
+						};
+					} catch (error) {
+						options?.signal?.throwIfAborted();
+						if (!isReusableLocalFailure(error)) connectionValid = false;
+						yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+					}
 				}
 			}
 			if (connectionValid) await this.returnConnection(connection);
@@ -2050,6 +2097,13 @@ var SmtpTransport = class {
 	}
 };
 function createSmtpFailure(message, error) {
+	if (error instanceof SmtpEnvelopeValidationError) return (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "smtp",
+		code: "smtp.envelope-invalid",
+		category: "validation",
+		retryable: false,
+		attempts: 1
+	});
 	if (error instanceof SmtpDsnValidationError) return (0, __upyo_core.createFailedReceipt)(message, {
 		provider: "smtp",
 		code: "smtp.dsn-invalid",
@@ -2106,7 +2160,19 @@ function createSmtpFailure(message, error) {
 	});
 }
 function isReusableLocalFailure(error) {
-	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpEnvelopeValidationError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+}
+function resolveEnvelopeOption(message, option, index) {
+	let override;
+	if (typeof option === "function") try {
+		override = option(message, index);
+	} catch (error) {
+		const failure = new SmtpEnvelopeValidationError(`SMTP envelope resolver failed: ${error instanceof Error ? error.message : String(error)}`);
+		failure.cause = error;
+		throw failure;
+	}
+	else override = option;
+	return resolveSmtpEnvelope(message, override);
 }
 function classifySmtpReply(code, enhancedStatusCode) {
 	const retryable = enhancedStatusCode == null ? code >= 400 && code < 500 : enhancedStatusCode.class === 4;
@@ -2149,5 +2215,6 @@ function isSmtpResponseProviderDetails(value) {
 exports.SmtpAuthError = SmtpAuthError;
 exports.SmtpDsnUnsupportedError = SmtpDsnUnsupportedError;
 exports.SmtpDsnValidationError = SmtpDsnValidationError;
+exports.SmtpEnvelopeValidationError = SmtpEnvelopeValidationError;
 exports.SmtpTransport = SmtpTransport;
 exports.isSmtpResponseProviderDetails = isSmtpResponseProviderDetails;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+import { EmailAddress, Message, Receipt, Transport, TransportOptions } from "@upyo/core";
 
 //#region src/dkim/types.d.ts
 
@@ -417,6 +417,54 @@ interface SmtpTlsOptions {
  * used internally by the SMTP transport implementation.
  */
 //#endregion
+//#region src/envelope.d.ts
+/**
+ * Overrides for the SMTP envelope of one message.
+ *
+ * Omitted fields are derived from the corresponding message fields.  A `null`
+ * sender produces the null reverse-path used for delivery notifications.
+ *
+ * @since 0.6.0
+ */
+interface SmtpEnvelopeOptions {
+  /**
+   * The address for `MAIL FROM`, or `null` for `MAIL FROM:<>`.
+   *
+   * When omitted, the message sender is used.
+   */
+  readonly from?: EmailAddress | null;
+  /**
+   * The addresses for `RCPT TO`.
+   *
+   * When omitted, the message's To, Cc, and Bcc addresses are used.
+   */
+  readonly to?: readonly EmailAddress[];
+}
+/**
+ * Resolves an SMTP envelope override for one message in a batch.
+ *
+ * @param message The message whose envelope is being resolved.
+ * @param index The zero-based position of the message in the send operation.
+ * @returns The envelope override, or `undefined` to derive the envelope from
+ * the message.
+ * @since 0.6.0
+ */
+type SmtpEnvelopeResolver = (message: Message, index: number) => SmtpEnvelopeOptions | undefined;
+/**
+ * Error produced when an effective SMTP envelope is invalid.
+ *
+ * @since 0.6.0
+ */
+declare class SmtpEnvelopeValidationError extends TypeError {
+  /**
+   * Creates an SMTP envelope validation error.
+   *
+   * @param message A description of the invalid envelope.
+   */
+  constructor(message: string);
+}
+/** @internal */
+//#endregion
 //#region src/delivery-status.d.ts
 /**
  * A condition under which an SMTP server should issue a delivery status
@@ -481,6 +529,13 @@ interface SmtpDsnOptions {
  * @since 0.6.0
  */
 interface SmtpTransportOptions extends TransportOptions {
+  /**
+   * SMTP envelope overrides for this send operation.
+   *
+   * A resolver can return a different envelope for each message passed to
+   * {@link SmtpTransport.sendMany}.
+   */
+  readonly envelope?: SmtpEnvelopeOptions | SmtpEnvelopeResolver;
   /** Delivery status notification settings for this SMTP transaction. */
   readonly dsn?: SmtpDsnOptions;
 }
@@ -694,8 +749,8 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * ```
    *
    * @param message The email message to send.
-   * @param options Optional transport options including `AbortSignal` for
-   *                cancellation.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
    * @returns A promise that resolves to a receipt indicating success or
    *          failure.
    * @throws {DOMException} If the operation is aborted through
@@ -726,8 +781,8 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * ```
    *
    * @param messages An iterable or async iterable of messages to send.
-   * @param options Optional transport options including `AbortSignal` for
-   *                cancellation.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
    * @returns An async iterable of receipts, one for each message.
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
@@ -797,4 +852,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnhancedStatusCode, SmtpMessageSizeProviderDetails, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpProviderDetails, SmtpReceipt, SmtpRejectedRecipient, SmtpResponseProviderDetails, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth, SmtpUtf8ProviderDetails, isSmtpResponseProviderDetails };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnhancedStatusCode, SmtpEnvelopeOptions, SmtpEnvelopeResolver, SmtpEnvelopeValidationError, SmtpMessageSizeProviderDetails, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpProviderDetails, SmtpReceipt, SmtpRejectedRecipient, SmtpResponseProviderDetails, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth, SmtpUtf8ProviderDetails, isSmtpResponseProviderDetails };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+import { EmailAddress, Message, Receipt, Transport, TransportOptions } from "@upyo/core";
 
 //#region src/dkim/types.d.ts
 
@@ -417,6 +417,54 @@ interface SmtpTlsOptions {
  * used internally by the SMTP transport implementation.
  */
 //#endregion
+//#region src/envelope.d.ts
+/**
+ * Overrides for the SMTP envelope of one message.
+ *
+ * Omitted fields are derived from the corresponding message fields.  A `null`
+ * sender produces the null reverse-path used for delivery notifications.
+ *
+ * @since 0.6.0
+ */
+interface SmtpEnvelopeOptions {
+  /**
+   * The address for `MAIL FROM`, or `null` for `MAIL FROM:<>`.
+   *
+   * When omitted, the message sender is used.
+   */
+  readonly from?: EmailAddress | null;
+  /**
+   * The addresses for `RCPT TO`.
+   *
+   * When omitted, the message's To, Cc, and Bcc addresses are used.
+   */
+  readonly to?: readonly EmailAddress[];
+}
+/**
+ * Resolves an SMTP envelope override for one message in a batch.
+ *
+ * @param message The message whose envelope is being resolved.
+ * @param index The zero-based position of the message in the send operation.
+ * @returns The envelope override, or `undefined` to derive the envelope from
+ * the message.
+ * @since 0.6.0
+ */
+type SmtpEnvelopeResolver = (message: Message, index: number) => SmtpEnvelopeOptions | undefined;
+/**
+ * Error produced when an effective SMTP envelope is invalid.
+ *
+ * @since 0.6.0
+ */
+declare class SmtpEnvelopeValidationError extends TypeError {
+  /**
+   * Creates an SMTP envelope validation error.
+   *
+   * @param message A description of the invalid envelope.
+   */
+  constructor(message: string);
+}
+/** @internal */
+//#endregion
 //#region src/delivery-status.d.ts
 /**
  * A condition under which an SMTP server should issue a delivery status
@@ -481,6 +529,13 @@ interface SmtpDsnOptions {
  * @since 0.6.0
  */
 interface SmtpTransportOptions extends TransportOptions {
+  /**
+   * SMTP envelope overrides for this send operation.
+   *
+   * A resolver can return a different envelope for each message passed to
+   * {@link SmtpTransport.sendMany}.
+   */
+  readonly envelope?: SmtpEnvelopeOptions | SmtpEnvelopeResolver;
   /** Delivery status notification settings for this SMTP transaction. */
   readonly dsn?: SmtpDsnOptions;
 }
@@ -694,8 +749,8 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * ```
    *
    * @param message The email message to send.
-   * @param options Optional transport options including `AbortSignal` for
-   *                cancellation.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
    * @returns A promise that resolves to a receipt indicating success or
    *          failure.
    * @throws {DOMException} If the operation is aborted through
@@ -726,8 +781,8 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * ```
    *
    * @param messages An iterable or async iterable of messages to send.
-   * @param options Optional transport options including `AbortSignal` for
-   *                cancellation.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
    * @returns An async iterable of receipts, one for each message.
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
@@ -797,4 +852,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnhancedStatusCode, SmtpMessageSizeProviderDetails, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpProviderDetails, SmtpReceipt, SmtpRejectedRecipient, SmtpResponseProviderDetails, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth, SmtpUtf8ProviderDetails, isSmtpResponseProviderDetails };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpDsnNotification, SmtpDsnOptions, SmtpDsnRecipientOptions, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnhancedStatusCode, SmtpEnvelopeOptions, SmtpEnvelopeResolver, SmtpEnvelopeValidationError, SmtpMessageSizeProviderDetails, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpProviderDetails, SmtpReceipt, SmtpRejectedRecipient, SmtpResponseProviderDetails, SmtpTlsOptions, SmtpTransport, SmtpTransportOptions, SmtpUserPassAuth, SmtpUtf8ProviderDetails, isSmtpResponseProviderDetails };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createFailedReceipt } from "@upyo/core";
+import { createFailedReceipt, isEmailAddress } from "@upyo/core";
 import { Buffer } from "node:buffer";
 import { Socket } from "node:net";
 import { TLSSocket, connect } from "node:tls";
@@ -42,14 +42,14 @@ const NOTIFICATION_CONDITIONS = new Set([
 /**
 * Validates and serializes the RFC 3461 envelope parameters for a message.
 *
-* @param message The message whose SMTP envelope will carry the parameters.
+* @param envelope The effective SMTP envelope that will carry the parameters.
 * @param dsn The caller-supplied delivery status notification settings.
 * @returns Serialized parameters, or `undefined` when none were requested.
 * @throws {SmtpDsnValidationError} If any setting violates RFC 3461 or does
 * not correspond to the message envelope.
 * @internal
 */
-function resolveSmtpDsn(message, dsn) {
+function resolveSmtpDsn(envelope, dsn) {
 	if (dsn == null) return void 0;
 	if (typeof dsn !== "object" || Array.isArray(dsn)) throw new SmtpDsnValidationError("DSN options must be an object.");
 	const mailParameters = [];
@@ -64,11 +64,7 @@ function resolveSmtpDsn(message, dsn) {
 		assertParameterLength(parameter, 100, "ENVID");
 		mailParameters.push(parameter);
 	}
-	const envelopeRecipients = [
-		...message.recipients.map((recipient) => recipient.address),
-		...message.ccRecipients.map((recipient) => recipient.address),
-		...message.bccRecipients.map((recipient) => recipient.address)
-	];
+	const envelopeRecipients = envelope.to;
 	const envelopeRecipientSet = new Set(envelopeRecipients);
 	const configuredRecipients = dsn.recipients;
 	if (configuredRecipients != null && (typeof configuredRecipients !== "object" || Array.isArray(configuredRecipients))) throw new SmtpDsnValidationError("DSN recipient options must be an object.");
@@ -1052,7 +1048,7 @@ var SmtpConnection = class {
 		const dsn = message.envelope.dsn;
 		if (dsn != null && !this.capabilities.some((capability) => /^DSN[ \t]*$/i.test(capability))) throw new SmtpDsnUnsupportedError();
 		const mailDsnParameters = dsn == null || dsn.mailParameters.length === 0 ? "" : ` ${dsn.mailParameters.join(" ")}`;
-		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
+		const mailCommand = `MAIL FROM:<${message.envelope.from ?? ""}>${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
 		const recipientCommands = message.envelope.to.map((recipient, index) => {
 			const parameters = dsn?.recipientParameters[index] ?? [];
 			const suffix = parameters.length === 0 ? "" : ` ${parameters.join(" ")}`;
@@ -1204,6 +1200,52 @@ function decodeOAuth2Challenge(message) {
 	}
 }
 
+//#endregion
+//#region src/envelope.ts
+/**
+* Error produced when an effective SMTP envelope is invalid.
+*
+* @since 0.6.0
+*/
+var SmtpEnvelopeValidationError = class extends TypeError {
+	/**
+	* Creates an SMTP envelope validation error.
+	*
+	* @param message A description of the invalid envelope.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "SmtpEnvelopeValidationError";
+	}
+};
+/**
+* Resolves and validates the SMTP envelope for a message.
+*
+* @param message The message that supplies fields without an override.
+* @param override Optional sender and recipient overrides.
+* @returns The validated effective SMTP envelope.
+* @throws {SmtpEnvelopeValidationError} If the override or any effective
+* address is invalid, or if the effective recipient list is empty.
+* @internal
+*/
+function resolveSmtpEnvelope(message, override) {
+	if (override !== void 0 && (override === null || typeof override !== "object" || Array.isArray(override))) throw new SmtpEnvelopeValidationError("SMTP envelope options must be an object.");
+	const from = override?.from === void 0 ? message.sender.address : override.from;
+	if (from !== null && !isEmailAddress(from)) throw new SmtpEnvelopeValidationError("SMTP envelope sender must be a valid email address or null.");
+	const recipients = override?.to === void 0 ? [
+		...message.recipients.map((recipient) => recipient.address),
+		...message.ccRecipients.map((recipient) => recipient.address),
+		...message.bccRecipients.map((recipient) => recipient.address)
+	] : override.to;
+	if (!Array.isArray(recipients)) throw new SmtpEnvelopeValidationError("SMTP envelope recipients must be an array.");
+	if (recipients.length === 0) throw new SmtpEnvelopeValidationError("SMTP envelope must contain at least one recipient.");
+	for (const [index, recipient] of recipients.entries()) if (!isEmailAddress(recipient)) throw new SmtpEnvelopeValidationError(`SMTP envelope recipient at index ${index} must be a valid email address.`);
+	return {
+		from,
+		to: [...recipients]
+	};
+}
+
 //#endregion
 //#region src/dkim/canonicalize.ts
 /**
@@ -1489,27 +1531,24 @@ function arrayBufferToBase64(buffer) {
 * @param message The message to convert.
 * @param dkimConfig Optional DKIM signing configuration.
 * @param dsn Optional validated SMTP delivery status notification parameters.
+* @param resolvedEnvelope The validated effective SMTP envelope.
 * @returns The converted SMTP message.
 * @throws {RangeError} If a header contains a token that cannot be folded
 * within the RFC 5322 hard line-length limit.
 */
-async function convertMessage(message, dkimConfig, dsn) {
+async function convertMessage(message, dkimConfig, dsn, resolvedEnvelope = resolveSmtpEnvelope(message)) {
 	const envelope = {
-		from: message.sender.address,
-		to: [
-			...message.recipients.map((r) => r.address),
-			...message.ccRecipients.map((r) => r.address),
-			...message.bccRecipients.map((r) => r.address)
-		],
+		...resolvedEnvelope,
 		dsn
 	};
-	const requiresSmtpUtf8 = [
-		message.sender,
-		...message.recipients,
-		...message.ccRecipients,
-		...message.bccRecipients,
-		...message.replyRecipients
-	].some((address) => Array.from(address.address).some((character) => (character.codePointAt(0) ?? 0) > 127));
+	const headerAddresses = [
+		message.sender.address,
+		...message.recipients.map((address) => address.address),
+		...message.ccRecipients.map((address) => address.address),
+		...message.replyRecipients.map((address) => address.address)
+	];
+	const envelopeAddresses = [...envelope.from == null ? [] : [envelope.from], ...envelope.to];
+	const requiresSmtpUtf8 = [...headerAddresses, ...envelopeAddresses].some((address) => Array.from(address).some((character) => (character.codePointAt(0) ?? 0) > 127));
 	let raw = await buildRawMessage(message);
 	if (dkimConfig) try {
 		for (const sig of dkimConfig.signatures) {
@@ -1812,8 +1851,8 @@ var SmtpTransport = class {
 	* ```
 	*
 	* @param message The email message to send.
-	* @param options Optional transport options including `AbortSignal` for
-	*                cancellation.
+	* @param options Optional SMTP envelope, delivery status, and cancellation
+	*                settings.
 	* @returns A promise that resolves to a receipt indicating success or
 	*          failure.
 	* @throws {DOMException} If the operation is aborted through
@@ -1823,10 +1862,11 @@ var SmtpTransport = class {
 		options?.signal?.throwIfAborted();
 		let connection;
 		try {
-			const dsn = resolveSmtpDsn(message, options?.dsn);
+			const envelope = resolveEnvelopeOption(message, options?.envelope, 0);
+			const dsn = resolveSmtpDsn(envelope, options?.dsn);
 			connection = await this.getConnection(options?.signal);
 			options?.signal?.throwIfAborted();
-			const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
+			const smtpMessage = await convertMessage(message, this.config.dkim, dsn, envelope);
 			options?.signal?.throwIfAborted();
 			const result = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
@@ -1867,8 +1907,8 @@ var SmtpTransport = class {
 	* ```
 	*
 	* @param messages An iterable or async iterable of messages to send.
-	* @param options Optional transport options including `AbortSignal` for
-	*                cancellation.
+	* @param options Optional SMTP envelope, delivery status, and cancellation
+	*                settings.
 	* @returns An async iterable of receipts, one for each message.
 	* @throws {DOMException} If the operation is aborted through
 	*                        `options.signal`.
@@ -1890,50 +1930,57 @@ var SmtpTransport = class {
 		let connectionValid = true;
 		try {
 			const isAsyncIterable = Symbol.asyncIterator in messages;
-			if (isAsyncIterable) for await (const message of messages) {
-				options?.signal?.throwIfAborted();
-				if (!connectionValid) {
-					yield createSmtpFailure("Connection is no longer valid");
-					continue;
-				}
-				try {
-					const dsn = resolveSmtpDsn(message, options?.dsn);
-					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
+			if (isAsyncIterable) {
+				let index = 0;
+				for await (const message of messages) {
 					options?.signal?.throwIfAborted();
-					const result = await connection.sendMessage(smtpMessage, options?.signal);
-					yield {
-						successful: true,
-						messageId: result.messageId,
-						provider: "smtp",
-						rejectedRecipients: result.rejectedRecipients
-					};
-				} catch (error) {
-					options?.signal?.throwIfAborted();
-					if (!isReusableLocalFailure(error)) connectionValid = false;
-					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
-				}
-			}
-			else for (const message of messages) {
-				options?.signal?.throwIfAborted();
-				if (!connectionValid) {
-					yield createSmtpFailure("Connection is no longer valid");
-					continue;
+					if (!connectionValid) {
+						yield createSmtpFailure("Connection is no longer valid");
+						continue;
+					}
+					try {
+						const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+						const dsn = resolveSmtpDsn(envelope, options?.dsn);
+						const smtpMessage = await convertMessage(message, this.config.dkim, dsn, envelope);
+						options?.signal?.throwIfAborted();
+						const result = await connection.sendMessage(smtpMessage, options?.signal);
+						yield {
+							successful: true,
+							messageId: result.messageId,
+							provider: "smtp",
+							rejectedRecipients: result.rejectedRecipients
+						};
+					} catch (error) {
+						options?.signal?.throwIfAborted();
+						if (!isReusableLocalFailure(error)) connectionValid = false;
+						yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+					}
 				}
-				try {
-					const dsn = resolveSmtpDsn(message, options?.dsn);
-					const smtpMessage = await convertMessage(message, this.config.dkim, dsn);
+			} else {
+				let index = 0;
+				for (const message of messages) {
 					options?.signal?.throwIfAborted();
-					const result = await connection.sendMessage(smtpMessage, options?.signal);
-					yield {
-						successful: true,
-						messageId: result.messageId,
-						provider: "smtp",
-						rejectedRecipients: result.rejectedRecipients
-					};
-				} catch (error) {
-					options?.signal?.throwIfAborted();
-					if (!isReusableLocalFailure(error)) connectionValid = false;
-					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+					if (!connectionValid) {
+						yield createSmtpFailure("Connection is no longer valid");
+						continue;
+					}
+					try {
+						const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+						const dsn = resolveSmtpDsn(envelope, options?.dsn);
+						const smtpMessage = await convertMessage(message, this.config.dkim, dsn, envelope);
+						options?.signal?.throwIfAborted();
+						const result = await connection.sendMessage(smtpMessage, options?.signal);
+						yield {
+							successful: true,
+							messageId: result.messageId,
+							provider: "smtp",
+							rejectedRecipients: result.rejectedRecipients
+						};
+					} catch (error) {
+						options?.signal?.throwIfAborted();
+						if (!isReusableLocalFailure(error)) connectionValid = false;
+						yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+					}
 				}
 			}
 			if (connectionValid) await this.returnConnection(connection);
@@ -2027,6 +2074,13 @@ var SmtpTransport = class {
 	}
 };
 function createSmtpFailure(message, error) {
+	if (error instanceof SmtpEnvelopeValidationError) return createFailedReceipt(message, {
+		provider: "smtp",
+		code: "smtp.envelope-invalid",
+		category: "validation",
+		retryable: false,
+		attempts: 1
+	});
 	if (error instanceof SmtpDsnValidationError) return createFailedReceipt(message, {
 		provider: "smtp",
 		code: "smtp.dsn-invalid",
@@ -2083,7 +2137,19 @@ function createSmtpFailure(message, error) {
 	});
 }
 function isReusableLocalFailure(error) {
-	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+	return error instanceof SmtpMessageSizeError || error instanceof SmtpUtf8UnsupportedError || error instanceof SmtpEnvelopeValidationError || error instanceof SmtpDsnValidationError || error instanceof SmtpDsnUnsupportedError;
+}
+function resolveEnvelopeOption(message, option, index) {
+	let override;
+	if (typeof option === "function") try {
+		override = option(message, index);
+	} catch (error) {
+		const failure = new SmtpEnvelopeValidationError(`SMTP envelope resolver failed: ${error instanceof Error ? error.message : String(error)}`);
+		failure.cause = error;
+		throw failure;
+	}
+	else override = option;
+	return resolveSmtpEnvelope(message, override);
 }
 function classifySmtpReply(code, enhancedStatusCode) {
 	const retryable = enhancedStatusCode == null ? code >= 400 && code < 500 : enhancedStatusCode.class === 4;
@@ -2123,4 +2189,4 @@ function isSmtpResponseProviderDetails(value) {
 }
 
 //#endregion
-export { SmtpAuthError, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpTransport, isSmtpResponseProviderDetails };
+export { SmtpAuthError, SmtpDsnUnsupportedError, SmtpDsnValidationError, SmtpEnvelopeValidationError, SmtpTransport, isSmtpResponseProviderDetails };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.6.0-dev.305",
+  "version": "0.6.0-dev.306",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.6.0-dev.305+7db15a6d"
+    "@upyo/core": "0.6.0-dev.306+6bd78f36"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",