#483: Enhancement: add native support for overriding envelope-level receiver(s)

Author: bbottema

modules/core-module/src/main/java/org/simplejavamail/api/email/Email.java

@@ -166,12 +166,17 @@ public class Email implements Serializable {
 	 */
 	@Nullable
 	private final Boolean useReturnReceiptTo;
-	
+
 	/**
 	 * @see EmailPopulatingBuilder#withReturnReceiptTo()
 	 * @see EmailPopulatingBuilder#withReturnReceiptTo(Recipient)
 	 */
 	private final Recipient returnReceiptTo;
+
+	/**
+	 * @see EmailPopulatingBuilder#withOverrideReceivers(Recipient...)
+	 */
+	private final List<Recipient> overrideReceivers;
 
 	/**
 	 * @see EmailStartingBuilder#forwarding(MimeMessage)
@@ -265,6 +270,7 @@ public Email(@NotNull final EmailPopulatingBuilder builder) {
 		dispositionNotificationTo = builder.getDispositionNotificationTo();
 		useReturnReceiptTo = builder.getUseReturnReceiptTo();
 		returnReceiptTo = builder.getReturnReceiptTo();
+		overrideReceivers = builder.getOverrideReceivers();
 		emailToForward = builder.getEmailToForward();
 		originalSmimeDetails = builder.getOriginalSmimeDetails();
 		sentDate = builder.getSentDate();
@@ -309,6 +315,10 @@ public String toString() {
 			s += ",\n\tuseReturnReceiptTo=" + true +
 					",\n\t\treturnReceiptTo=" + returnReceiptTo;
 		}
+		if (!overrideReceivers.isEmpty()) {
+			s += ",\n\toverrideReceivers=" + true +
+					",\n\t\toverrideReceivers=" + overrideReceivers;
+		}
 		if (!headers.isEmpty()) {
 			s += ",\n\theaders=" + headers;
 		}
@@ -442,7 +452,7 @@ public Boolean getUseDispositionNotificationTo() {
 	public Recipient getDispositionNotificationTo() {
 		return dispositionNotificationTo;
 	}
-	
+
 	/**
 	 * @see EmailPopulatingBuilder#withReturnReceiptTo()
 	 * @see EmailPopulatingBuilder#withReturnReceiptTo(Recipient)
@@ -451,6 +461,14 @@ public Recipient getDispositionNotificationTo() {
 	public Boolean getUseReturnReceiptTo() {
 		return useReturnReceiptTo;
 	}
+
+	/**
+	 * @see EmailPopulatingBuilder#withOverrideReceivers(Recipient...)
+	 */
+	@NotNull
+	public List<Recipient> getOverrideReceivers() {
+		return overrideReceivers;
+	}
 
 	/**
 	 * @see EmailPopulatingBuilder#withReturnReceiptTo()

modules/core-module/src/main/java/org/simplejavamail/api/email/EmailPopulatingBuilder.java

@@ -1,6 +1,7 @@
 package org.simplejavamail.api.email;
 
 import jakarta.activation.DataSource;
+import jakarta.mail.Address;
 import jakarta.mail.Message;
 import jakarta.mail.internet.InternetAddress;
 import jakarta.mail.internet.MimeMessage;
@@ -1453,6 +1454,18 @@ public interface EmailPopulatingBuilder {
 	 */
 	EmailPopulatingBuilder withReturnReceiptTo(@NotNull Recipient recipient);
 
+	/**
+	 * Delegates to {@link #withOverrideReceivers(List<Recipient>)}.
+	 */
+	EmailPopulatingBuilder withOverrideReceivers(@NotNull Recipient ...recipients);
+
+	/**
+	 * When provided, Simple Java Mail will ignore all recipients set on the email and instead send to the provided recipients only (when calling
+	 * {@link jakarta.mail.Transport#sendMessage(Message, Address[])}). The actual Message will still contain the original recipients, but won't receive a
+	 * copy. This is useful for testing purposes.
+	 */
+	EmailPopulatingBuilder withOverrideReceivers(@NotNull List<Recipient> recipients);
+
 	/**
 	 * When an email is sent it is converted to a MimeMessage at which time the sent-date is filled with the current date. With this method
 	 * this can be fixed to a date of choice.
@@ -1746,13 +1759,19 @@ public interface EmailPopulatingBuilder {
 	 */
 	@Nullable
 	Boolean getUseReturnReceiptTo();
-	
+
 	/**
 	 * @see #withReturnReceiptTo()
 	 * @see #withReturnReceiptTo(Recipient)
 	 */
 	@Nullable
 	Recipient getReturnReceiptTo();
+
+	/**
+	 * @see #withOverrideReceivers(Recipient...)
+	 */
+	@NotNull
+	List<Recipient> getOverrideReceivers();
 
 	/**
 	 * @see EmailStartingBuilder#forwarding(MimeMessage)

modules/core-module/src/main/java/org/simplejavamail/internal/config/EmailProperty.java

@@ -36,6 +36,7 @@ public enum EmailProperty {
     TO_RECIPIENTS(Email::getToRecipients, true),
     CC_RECIPIENTS(Email::getCcRecipients, true),
     BCC_RECIPIENTS(Email::getBccRecipients, true),
+    OVERRIDE_RECEIVERS(Email::getOverrideReceivers, true),
     SMIME_SIGNING_CONFIG(Email::getPkcs12ConfigForSmimeSigning, false),
     SMIME_ENCRYPTION_CONFIG(Email::getX509CertificateForSmimeEncryption, false),
     DKIM_SIGNING_CONFIG(Email::getDkimConfig, false),

modules/core-module/src/main/java/org/simplejavamail/internal/util/MiscUtil.java

@@ -35,6 +35,7 @@
 import java.util.Map;
 import java.util.Random;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 
 import static java.lang.Integer.toHexString;
 import static java.lang.String.format;
@@ -451,4 +452,17 @@ public static void assignToInstanceField(Object subject, String fieldName, Objec
 		field.setAccessible(true);
 		field.set(subject, newValue);
 	}
+
+	@NotNull
+	public static List<InternetAddress> asInternetAddresses(@NotNull List<Recipient> recipient, @NotNull Charset charset) {
+		return recipient.stream()
+				.map(r -> asInternetAddress(r, charset))
+				.collect(Collectors.toList());
+	}
+
+	@NotNull
+	@SneakyThrows
+	public static InternetAddress asInternetAddress(@NotNull Recipient recipient, @NotNull Charset charset) {
+		return new InternetAddress(recipient.getAddress(), recipient.getName(), charset.name());
+	}
 }

modules/simple-java-mail/src/main/java/org/simplejavamail/converter/internal/mimemessage/MimeMessageHelper.java

@@ -25,13 +25,15 @@
 import org.simplejavamail.internal.util.NamedDataSource;
 
 import java.io.UnsupportedEncodingException;
+import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.util.Collection;
 import java.util.Map;
 import java.util.UUID;
 
 import static java.lang.Boolean.TRUE;
 import static java.lang.String.format;
+import static java.nio.charset.StandardCharsets.UTF_8;
 import static java.util.Objects.requireNonNull;
 import static java.util.Optional.ofNullable;
 import static org.simplejavamail.internal.util.MiscUtil.valueNullOrEmpty;
@@ -45,22 +47,18 @@ public class MimeMessageHelper {
 	/**
 	 * Encoding used for setting body text, email address, headers, reply-to fields etc. ({@link StandardCharsets#UTF_8}).
 	 */
-	private static final String CHARACTER_ENCODING = StandardCharsets.UTF_8.name();
+	private static final Charset CHARACTER_ENCODING = UTF_8;
 
 	private static final String HEADER_CONTENT_TRANSFER_ENCODING = "Content-Transfer-Encoding";
 
-	private MimeMessageHelper() {
-
-	}
-
 	static void setSubject(@NotNull final Email email, final MimeMessage message) throws MessagingException {
-		message.setSubject(email.getSubject(), CHARACTER_ENCODING);
+		message.setSubject(email.getSubject(), CHARACTER_ENCODING.name());
 	}
 
-	static void setFrom(@NotNull final Email email, final MimeMessage message) throws UnsupportedEncodingException, MessagingException {
+	static void setFrom(@NotNull final Email email, final MimeMessage message) throws MessagingException {
 		val fromRecipient = email.getFromRecipient();
 		if (fromRecipient != null) {
-			message.setFrom(new InternetAddress(fromRecipient.getAddress(), fromRecipient.getName(), CHARACTER_ENCODING));
+			message.setFrom(MiscUtil.asInternetAddress(fromRecipient, CHARACTER_ENCODING));
 		}
 	}
 
@@ -69,13 +67,12 @@ static void setFrom(@NotNull final Email email, final MimeMessage message) throw
 	 *
 	 * @param email   The message in which the recipients are defined.
 	 * @param message The javax message that needs to be filled with recipients.
-	 * @throws UnsupportedEncodingException See {@link InternetAddress#InternetAddress(String, String)}.
 	 * @throws MessagingException           See {@link Message#addRecipient(Message.RecipientType, Address)}
 	 */
 	static void setRecipients(final Email email, final Message message)
-			throws UnsupportedEncodingException, MessagingException {
+			throws MessagingException {
 		for (final Recipient recipient : email.getRecipients()) {
-				message.addRecipient(recipient.getType(), new InternetAddress(recipient.getAddress(), recipient.getName(), CHARACTER_ENCODING));
+			message.addRecipient(recipient.getType(), MiscUtil.asInternetAddress(recipient, CHARACTER_ENCODING));
 		}
 	}
 
@@ -84,16 +81,15 @@ static void setRecipients(final Email email, final Message message)
 	 *
 	 * @param email   The message in which the recipients are defined.
 	 * @param message The javax message that needs to be filled with reply-to addresses.
-	 * @throws UnsupportedEncodingException See {@link InternetAddress#InternetAddress(String, String)}.
 	 * @throws MessagingException           See {@link Message#setReplyTo(Address[])}
 	 */
 	static void setReplyTo(@NotNull final Email email, final Message message)
-			throws UnsupportedEncodingException, MessagingException {
+			throws MessagingException {
 		if (!email.getReplyToRecipients().isEmpty()) {
 			val replyToAddresses = new Address[email.getReplyToRecipients().size()];
 			int i = 0;
 			for (val replyToRecipient : email.getReplyToRecipients()) {
-				replyToAddresses[i++] = new InternetAddress(replyToRecipient.getAddress(), replyToRecipient.getName(), CHARACTER_ENCODING);
+				replyToAddresses[i++] = MiscUtil.asInternetAddress(replyToRecipient, CHARACTER_ENCODING);
 			}
 			message.setReplyTo(replyToAddresses);
 		}
@@ -110,20 +106,20 @@ static void setTexts(@NotNull final Email email, final MimeMultipart multipartAl
 			throws MessagingException {
 		if (email.getPlainText() != null) {
 			val messagePart = new MimeBodyPart();
-			messagePart.setText(email.getPlainText(), CHARACTER_ENCODING);
+			messagePart.setText(email.getPlainText(), CHARACTER_ENCODING.name());
 			messagePart.addHeader(HEADER_CONTENT_TRANSFER_ENCODING, determineContentTransferEncoder(email));
 			multipartAlternativeMessages.addBodyPart(messagePart);
 		}
 		if (email.getHTMLText() != null) {
 			val messagePartHTML = new MimeBodyPart();
-			messagePartHTML.setContent(email.getHTMLText(), format("text/html; charset=\"%s\"", CHARACTER_ENCODING));
+			messagePartHTML.setContent(email.getHTMLText(), format("text/html; charset=\"%s\"", CHARACTER_ENCODING.name()));
 			messagePartHTML.addHeader(HEADER_CONTENT_TRANSFER_ENCODING, determineContentTransferEncoder(email));
 			multipartAlternativeMessages.addBodyPart(messagePartHTML);
 		}
 		if (email.getCalendarText() != null) {
 			val calendarMethod = requireNonNull(email.getCalendarMethod(), "calendarMethod is required when calendarText is set");
 			val messagePartCalendar = new MimeBodyPart();
-			messagePartCalendar.setContent(email.getCalendarText(), format("text/calendar; charset=\"%s\"; method=\"%s\"", CHARACTER_ENCODING, calendarMethod));
+			messagePartCalendar.setContent(email.getCalendarText(), format("text/calendar; charset=\"%s\"; method=\"%s\"", CHARACTER_ENCODING.name(), calendarMethod));
 			messagePartCalendar.addHeader(HEADER_CONTENT_TRANSFER_ENCODING, determineContentTransferEncoder(email));
 			multipartAlternativeMessages.addBodyPart(messagePartCalendar);
 		}
@@ -146,14 +142,14 @@ private static String determineContentTransferEncoder(@NotNull Email email) {
 	static void setTexts(@NotNull final Email email, final MimePart messagePart)
 			throws MessagingException {
 		if (email.getPlainText() != null) {
-			messagePart.setText(email.getPlainText(), CHARACTER_ENCODING);
+			messagePart.setText(email.getPlainText(), CHARACTER_ENCODING.name());
 		}
 		if (email.getHTMLText() != null) {
-			messagePart.setContent(email.getHTMLText(), format("text/html; charset=\"%s\"", CHARACTER_ENCODING));
+			messagePart.setContent(email.getHTMLText(), format("text/html; charset=\"%s\"", CHARACTER_ENCODING.name()));
 		}
 		if (email.getCalendarText() != null) {
 			val calendarMethod = requireNonNull(email.getCalendarMethod(), "CalendarMethod must be set when CalendarText is set");
-			messagePart.setContent(email.getCalendarText(), format("text/calendar; charset=\"%s\"; method=\"%s\"", CHARACTER_ENCODING, calendarMethod));
+			messagePart.setContent(email.getCalendarText(), format("text/calendar; charset=\"%s\"; method=\"%s\"", CHARACTER_ENCODING.name(), calendarMethod));
 		}
 		messagePart.addHeader(HEADER_CONTENT_TRANSFER_ENCODING, determineContentTransferEncoder(email));
 	}
@@ -225,21 +221,21 @@ static void setHeaders(@NotNull final Email email, final Message message)
 
 		if (TRUE.equals(email.getUseDispositionNotificationTo())) {
 			final Recipient dispositionTo = checkNonEmptyArgument(email.getDispositionNotificationTo(), "dispositionNotificationTo");
-			final Address address = new InternetAddress(dispositionTo.getAddress(), dispositionTo.getName(), CHARACTER_ENCODING);
+			final Address address = MiscUtil.asInternetAddress(dispositionTo, CHARACTER_ENCODING);
 			message.setHeader("Disposition-Notification-To", address.toString());
 		}
 
 		if (TRUE.equals(email.getUseReturnReceiptTo())) {
 			final Recipient returnReceiptTo = checkNonEmptyArgument(email.getReturnReceiptTo(), "returnReceiptTo");
-			final Address address = new InternetAddress(returnReceiptTo.getAddress(), returnReceiptTo.getName(), CHARACTER_ENCODING);
+			final Address address = MiscUtil.asInternetAddress(returnReceiptTo, CHARACTER_ENCODING);
 			message.setHeader("Return-Receipt-To", address.toString());
 		}
 	}
 
 	private static void setHeader(Message message, Map.Entry<String, Collection<String>> header) throws UnsupportedEncodingException, MessagingException {
 		for (final String headerValue : header.getValue()) {
 			final String headerName = header.getKey();
-			final String headerValueEncoded = MimeUtility.encodeText(headerValue, CHARACTER_ENCODING, null);
+			final String headerValueEncoded = MimeUtility.encodeText(headerValue, CHARACTER_ENCODING.name(), null);
 			final String foldedHeaderValue = MimeUtility.fold(headerName.length() + 2, headerValueEncoded);
 			message.addHeader(header.getKey(), foldedHeaderValue);
 		}

modules/simple-java-mail/src/main/java/org/simplejavamail/email/internal/EmailPopulatingBuilderImpl.java

@@ -310,6 +310,11 @@ public class EmailPopulatingBuilderImpl implements InternalEmailPopulatingBuilde
 	@Nullable
 	private Recipient returnReceiptTo;
 
+	/**
+	 * @see #withOverrideReceivers(Recipient...)
+	 */
+	private final List<Recipient> overrideReceivers = new ArrayList<>();
+
 	/**
 	 * @see EmailBuilder#forwarding(MimeMessage)
 	 */
@@ -2079,6 +2084,25 @@ public EmailPopulatingBuilder withReturnReceiptTo(@NotNull final Recipient recip
 		return this;
 	}
 
+	/**
+	 * @see EmailPopulatingBuilder#withReturnReceiptTo(Recipient)
+	 */
+	@Override
+	public EmailPopulatingBuilder withOverrideReceivers(@NotNull Recipient ...recipients) {
+		checkNonEmptyArgument(recipients, "recipients");
+		return withOverrideReceivers(asList(recipients));
+	}
+
+	/**
+	 * @see EmailPopulatingBuilder#withOverrideReceivers(List)
+	 */
+	@Override
+	public EmailPopulatingBuilder withOverrideReceivers(@NotNull List<Recipient> recipients) {
+		checkNonEmptyArgument(recipients, "recipients");
+		this.overrideReceivers.addAll(recipients);
+		return this;
+	}
+
 	/**
 	 * @see EmailPopulatingBuilder#getOriginalSmimeDetails()
 	 */
@@ -2524,7 +2548,7 @@ public Recipient getDispositionNotificationTo() {
 	public Boolean getUseReturnReceiptTo() {
 		return useReturnReceiptTo;
 	}
-	
+
 	/**
 	 * @see EmailPopulatingBuilder#getReturnReceiptTo()
 	 */
@@ -2533,6 +2557,15 @@ public Boolean getUseReturnReceiptTo() {
 	public Recipient getReturnReceiptTo() {
 		return returnReceiptTo;
 	}
+
+	/**
+	 * @see EmailPopulatingBuilder#getOverrideReceivers()
+	 */
+	@Override
+	@NotNull
+	public List<Recipient> getOverrideReceivers() {
+		return overrideReceivers;
+	}
 
 	/**
 	 * @see EmailPopulatingBuilder#getEmailToForward()

modules/simple-java-mail/src/main/java/org/simplejavamail/mailer/internal/EmailGovernanceImpl.java

@@ -240,6 +240,10 @@ public Email produceEmailApplyingDefaultsAndOverrides(@Nullable Email provided)
 			}
 		}
 
+		val overrideReceivers = this.<Recipient>resolveEmailCollectionProperty(provided, EmailProperty.OVERRIDE_RECEIVERS);
+		if (!overrideReceivers.isEmpty()) {
+			builder.withOverrideReceivers(overrideReceivers);
+		}
 		ofNullable(this.<ContentTransferEncoding>resolveEmailProperty(provided, EmailProperty.CONTENT_TRANSFER_ENCODING)).ifPresent(builder::withContentTransferEncoding);
 		ofNullable(this.<Pkcs12Config>resolveEmailProperty(provided, EmailProperty.SMIME_SIGNING_CONFIG)).ifPresent(builder::signWithSmime);
 		ofNullable(this.<X509Certificate>resolveEmailProperty(provided, EmailProperty.SMIME_ENCRYPTION_CONFIG)).ifPresent(builder::encryptWithSmime);

modules/simple-java-mail/src/main/java/org/simplejavamail/mailer/internal/util/TransportRunner.java

@@ -3,17 +3,20 @@
 import jakarta.mail.MessagingException;
 import jakarta.mail.Session;
 import jakarta.mail.Transport;
+import jakarta.mail.internet.InternetAddress;
 import lombok.val;
 import org.jetbrains.annotations.NotNull;
 import org.simplejavamail.api.email.Email;
 import org.simplejavamail.api.internal.batchsupport.LifecycleDelegatingTransport;
 import org.simplejavamail.internal.moduleloader.ModuleLoader;
 import org.simplejavamail.internal.modules.BatchModule;
+import org.simplejavamail.internal.util.MiscUtil;
 import org.simplejavamail.mailer.internal.SessionBasedEmailToMimeMessageConverter;
 import org.slf4j.Logger;
 
 import java.util.UUID;
 
+import static java.nio.charset.StandardCharsets.UTF_8;
 import static org.slf4j.LoggerFactory.getLogger;
 
 /**
@@ -37,7 +40,10 @@ public static void sendMessage(@NotNull final UUID clusterKey, final Session ses
 			throws MessagingException {
 		runOnSessionTransport(clusterKey, session, false, (transport, actualSessionUsed) -> {
 			val message = SessionBasedEmailToMimeMessageConverter.convertAndLogMimeMessage(actualSessionUsed, email);
-			transport.sendMessage(message, message.getAllRecipients());
+			val actualRecipients = email.getOverrideReceivers().isEmpty()
+					? message.getAllRecipients()
+					: MiscUtil.asInternetAddresses(email.getOverrideReceivers(), UTF_8).toArray(new InternetAddress[0]);
+			transport.sendMessage(message, actualRecipients);
 			LOGGER.trace("...email sent");
 		});
 	}