ses.adoc 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. = SES Integration
  2. Spring has a built-in support to send e-mails based on the https://www.oracle.com/technetwork/java/javamail/index.html[Java Mail API]
  3. to avoid any static method calls while using the Java Mail API and thus supporting the testability of an application.
  4. Spring Cloud AWS supports the https://aws.amazon.com/de/ses/[Amazon SES] as an implementation of the Spring Mail abstraction.
  5. As a result Spring Cloud AWS users can decide to use the Spring Cloud AWS implementation of the Amazon SES service or
  6. use the standard Java Mail API based implementation that sends e-mails via SMTP to Amazon SES.
  7. [TIP]
  8. ====
  9. It is preferred to use the Spring Cloud AWS implementation instead of SMTP mainly for performance reasons.
  10. Spring Cloud AWS uses one API call to send a mail message, while the SMTP protocol makes multiple requests (EHLO, MAIL FROM, RCPT TO, DATA, QUIT)
  11. until it sends an e-mail.
  12. ====
  13. A Spring Boot starter is provided to auto-configure SES integration beans.
  14. Maven coordinates, using <<index.adoc#bill-of-materials, Spring Cloud AWS BOM>>:
  15. [source,xml]
  16. ----
  17. <dependency>
  18. <groupId>io.awspring.cloud</groupId>
  19. <artifactId>spring-cloud-aws-starter-ses</artifactId>
  20. </dependency>
  21. ----
  22. == Sending simple mails
  23. Application developers can inject the `MailSender` into their application code and directly send simple text based e-mail
  24. messages. The sample below demonstrates the creation of a simple mail message.
  25. [source,java,indent=0]
  26. ----
  27. import org.springframework.mail.MailSender;
  28. import org.springframework.mail.SimpleMailMessage;
  29. class MailSendingService {
  30. private final MailSender mailSender;
  31. public MailSendingService(MailSender mailSender) {
  32. this.mailSender = mailSender;
  33. }
  34. public void sendMailMessage() {
  35. SimpleMailMessage simpleMailMessage = new SimpleMailMessage();
  36. simpleMailMessage.setFrom("foo@bar.com");
  37. simpleMailMessage.setTo("bar@baz.com");
  38. simpleMailMessage.setSubject("test subject");
  39. simpleMailMessage.setText("test content");
  40. this.mailSender.send(simpleMailMessage);
  41. }
  42. }
  43. ----
  44. == Sending attachments and/or HTML e-mails
  45. Sending attachments with e-mail or HTML e-mails requires MIME messages to be created and sent. In order to create MIME messages,
  46. the Java Mail API dependency and an implementation need to be in the classpath. Spring Cloud AWS will detect the
  47. dependency and create a `org.springframework.mail.javamail.JavaMailSender` implementation that allows to create and
  48. build MIME messages and send them. Dependencies for the Java Mail API and an implementation are the only needed configuration changes as shown below.
  49. [source,xml,indent=0]
  50. ----
  51. <dependency>
  52. <groupId>jakarta.mail</groupId>
  53. <artifactId>jakarta.mail-api</artifactId>
  54. </dependency>
  55. <dependency>
  56. <groupId>org.eclipse.angus</groupId>
  57. <artifactId>jakarta.mail</artifactId>
  58. </dependency>
  59. ----
  60. [NOTE]
  61. ====
  62. Even though there is a dependency to the Java Mail API there is still the Amazon SES API used underneath to send mail
  63. messages. There is no https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html[SMTP setup] required
  64. on the Amazon AWS side.
  65. ====
  66. Sending the mail requires the application developer to use the `JavaMailSender` to send an e-mail as shown in the example
  67. below.
  68. [source,java,indent=0]
  69. ----
  70. import org.springframework.mail.javamail.JavaMailSender;
  71. import org.springframework.mail.javamail.MimeMessageHelper;
  72. import org.springframework.mail.javamail.MimeMessagePreparator;
  73. class MailSendingService {
  74. private final JavaMailSender mailSender;
  75. public MailSendingService(JavaMailSender mailSender) {
  76. this.mailSender = mailSender;
  77. }
  78. public void sendMailMessage() {
  79. this.mailSender.send(new MimeMessagePreparator() {
  80. @Override
  81. public void prepare(MimeMessage mimeMessage) throws Exception {
  82. MimeMessageHelper helper =
  83. new MimeMessageHelper(mimeMessage, true, "UTF-8");
  84. helper.addTo("foo@bar.com");
  85. helper.setFrom("bar@baz.com");
  86. helper.addAttachment("test.txt", ...);
  87. helper.setSubject("test subject with attachment");
  88. helper.setText("mime body", false);
  89. }
  90. });
  91. }
  92. }
  93. ----
  94. == Authenticating e-mails
  95. To avoid any spam attacks on the Amazon SES mail service, applications without production access must
  96. https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html[verify] each
  97. e-mail receiver otherwise the mail sender will throw a `software.amazon.awssdk.services.ses.model.MessageRejectedException`.
  98. https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html[Production access] can be requested
  99. and will disable the need for mail address verification.
  100. == Configuration
  101. The Spring Boot Starter for SES provides the following configuration options:
  102. [cols="3,3,1,1"]
  103. |===
  104. | Name | Description | Required | Default value
  105. | `spring.cloud.aws.ses.enabled` | Enables the SES integration. | No | `true`
  106. | `spring.cloud.aws.ses.endpoint` | Configures endpoint used by `SesClient`. | No |
  107. | `spring.cloud.aws.ses.region` | Configures region used by `SesClient`. | No |
  108. | `spring.cloud.aws.ses.sourceArn` | Configures source ARN, used only for sending authorization. | No |
  109. |===
  110. Amazon SES is not available in all https://docs.aws.amazon.com/ses/latest/DeveloperGuide/regions.html[regions] of the
  111. Amazon Web Services cloud. Therefore, an application hosted and operated in a region that does not support the mail
  112. service will produce an error while using the mail service. Therefore, the region must be overridden for the mail
  113. sender configuration. The example below shows a typical combination of a region (`EU-CENTRAL-1`) that does not provide
  114. an SES service where the client is overridden to use a valid region (`EU-WEST-1`).
  115. `sourceArn` is the ARN of the identity that is associated with the sending authorization policy. For information about when to use this parameter, see the
  116. description see https://docs.aws.amazon.com/ses/latest/dg/sending-authorization-delegate-sender-tasks-email.html[Amazon SES Developer Guide].
  117. [source,properties,indent=0]
  118. ----
  119. spring.cloud.aws.ses.region=eu-west-1
  120. spring.cloud.aws.ses.sourceArn=arn:aws:ses:eu-west-1:123456789012:identity/example.com
  121. ----
  122. == IAM Permissions
  123. Following IAM permissions are required by Spring Cloud AWS:
  124. [cols="2"]
  125. |===
  126. | Send e-mail without attachment
  127. | `ses:SendEmail`
  128. | Send e-mail with attachment
  129. | `ses:SendRawEmail`
  130. |===
  131. Sample IAM policy granting access to SES:
  132. [source,json,indent=0]
  133. ----
  134. {
  135. "Version": "2012-10-17",
  136. "Statement": [
  137. {
  138. "Effect": "Allow",
  139. "Action": [
  140. "ses:SendEmail",
  141. "ses:SendRawEmail"
  142. ],
  143. "Resource": "arn:aws:ses:your:arn"
  144. }
  145. ]
  146. }
  147. ----