com.commercetools.sunrise.email

Interface EmailSender

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface EmailSender

A service for sending e-mails.

Instances of the e-mail service are created with a configuration such that they can later send messages without requiring further credentials or configuration of servers.

The service API is based on the Java Mail API. Note that implementations of this service might choose not to send e-mails using the (default implementation of the) Java Mail API but to merely accept messages created using the Java Mail API. You may want to consult the samples, JavaDocs and specification of the Java Mail API.

Method Summary

Modifier and Type	Method and Description
java.util.concurrent.CompletionStage<java.lang.String>	send(MessageEditor messageEditor) Create a completion stage that asynchronously sends an e-mail using the configuration of this e-mail service.

Method Detail

send

@Nonnull
java.util.concurrent.CompletionStage<java.lang.String> send(@Nonnull
                                                                     MessageEditor messageEditor)

Create a completion stage that asynchronously sends an e-mail using the configuration of this e-mail service. Before this method returns, the MessageEditor passed to this method is invoked with an empty MimeMessage that the EmailSender created. The MessageEditor shall prepare the message so it can be sent. Sending will happen asynchronously, though.

Usage

Refer to the Java Mail JavaDoc and the Java Mail Specification on how to configure instances of MimeMessage. The following code shows a simple example.

 CompletionStage<String> completionStage = emailSender.send(msg -> {
      msg.setFrom("foo@domain.com");
      msg.setSubject("Subject, "UTF-8");
      msg.setText("Text", "UTF-8");
      msg.setSentDate(new Date());
      msg.setRecipients(Message.RecipientType.TO, "bar@domain.com");
 });
 

The CompletionStage returned by this method may be combined with further completion stages. To directly send the email and get its message ID, obtain a completable future as in the following example.

 String messageID = completionStage.toCompletableFuture().join();
 

Exception handling

Exceptions that occur while sending the email are instances of EmailDeliveryException that are contained in the CompletionStage returned by this method. (Note that it is possible that other RuntimeExceptions or Errors besides EmailDeliveryException may be contained in the CompletionStage.) If CompletableFuture.join() is invoked like in above snippet, any EmailDeliveryException raised while sending the email is wrapped in a CompletionException thrown by CompletableFuture.join().

Exceptions that occur while creating an email are instances of EmailCreationException that are thrown by send(MessageEditor).

If desired, both kinds of exceptions can be handled like in the following snippet, without requiring the use CompletableFuture.join().

 try {
      emailSender.send(...)
          .exceptionally(throwable -> {
              if (throwable instanceof EmailDeliveryException) {
                  // handle the EmailDeliveryException
              }
              ...
          });
 } catch (EmailCreationException e) {
      // handle the EmailCreationException
 }
 

A note to implementors

Implementations of this method need to apply timeouts that may be configured when creating the EmailSender instance. The timeouts avoid denial of service by too many connections waiting for stalled I/O.

Parameters:

messageEditor - the email sender passes an empty message to the message editor that the editor shall fill. Note that MimeMessage instances are not immutable. Messages passed to the editor must only be used by that editor instance and must not be passed elsewhere.

Returns:

A completion stage containing a string identifying the delivered email, or a EmailDeliveryException if the email could not be sent successfully. (Note that it is possible that other RuntimeExceptions or Errors besides EmailDeliveryException may be contained in the CompletionStage.)

Throws:

EmailCreationException - if there was an error while creating or filling the message. Note that in contrast EmailDeliveryExceptions raised while sending the e-mail are accessible via the returned CompletionStage. Also see above note on exceptions.