Skip to content

Commit 86f6d72

Browse files
arunkpatraarunkpatra
authored
Update SES Docs (awspring#751)
Fixes awspring#749
1 parent 6ee5647 commit 86f6d72

File tree

6 files changed

+140
-8
lines changed

6 files changed

+140
-8
lines changed

‎docs/src/main/asciidoc/ses.adoc‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,22 @@ class MailSendingService {
5555
----
5656

5757

58-
=== Sending attachments
58+
=== Sending attachments and/or HTML e-mails
5959

60-
Sending attachments with e-mail requires MIME messages to be created and sent. In order to create MIME messages,
61-
the Java Mail dependency is required and has to be included in the classpath. Spring Cloud AWS will detect the
60+
Sending attachments with e-mail or HTML e-mails requires MIME messages to be created and sent. In order to create MIME messages,
61+
the Java Mail API dependency and an implementation need to be in the classpath. Spring Cloud AWS will detect the
6262
dependency and create a `org.springframework.mail.javamail.JavaMailSender` implementation that allows to create and
63-
build MIME messages and send them. A dependency configuration for the Java Mail API is the only change in the configuration
64-
which is shown below.
63+
build MIME messages and send them. Dependencies for the Java Mail API and an implementation are the only needed configuration changes as shown below.
6564

6665
[source,xml,indent=0]
6766
----
6867
<dependency>
69-
<groupId>javax.mail</groupId>
70-
<artifactId>mailapi</artifactId>
68+
<groupId>jakarta.mail</groupId>
69+
<artifactId>jakarta.mail-api</artifactId>
70+
</dependency>
71+
<dependency>
72+
<groupId>org.eclipse.angus</groupId>
73+
<artifactId>jakarta.mail</artifactId>
7174
</dependency>
7275
----
7376

‎spring-cloud-aws-samples/spring-cloud-aws-ses-sample/docker-compose.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
version: '3.8'
2+
3+
services:
4+
ses-sample-localstack:
5+
container_name: localstack
6+
environment:
7+
- DEBUG=1
8+
- LOCALSTACK_HOSTNAME=localhost
9+
- TEST_AWS_ACCOUNT_ID=000000000000
10+
- AWS_DEFAULT_REGION=us-east-1
11+
- SERVICES=ses
12+
- S3_MOUNT=/tmp
13+
image: localstack/localstack:latest
14+
ports:
15+
- "4566:4566"
16+
volumes:
17+
- /var/run/docker.sock:/var/run/docker.sock
18+

‎spring-cloud-aws-samples/spring-cloud-aws-ses-sample/pom.xml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,18 @@
1717
<groupId>io.awspring.cloud</groupId>
1818
<artifactId>spring-cloud-aws-starter-ses</artifactId>
1919
</dependency>
20+
<!-- This is needed only if you wish to send HTML emails or emails with attachments. This is the Java Mail API
21+
-->
22+
<dependency>
23+
<groupId>jakarta.mail</groupId>
24+
<artifactId>jakarta.mail-api</artifactId>
25+
</dependency>
26+
<!-- This is needed only if you wish to send HTML emails or emails with attachments. This is an implementation
27+
of the Java Mail API-->
28+
<dependency>
29+
<groupId>org.eclipse.angus</groupId>
30+
<artifactId>jakarta.mail</artifactId>
31+
</dependency>
2032
</dependencies>
2133

2234
<build>

‎spring-cloud-aws-samples/spring-cloud-aws-ses-sample/src/main/java/io/awspring/cloud/samples/ses/MailSendingApplication.java‎

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,40 @@
1515
*/
1616
package io.awspring.cloud.samples.ses;
1717

18+
import java.io.File;
1819
import org.springframework.boot.ApplicationRunner;
1920
import org.springframework.boot.SpringApplication;
2021
import org.springframework.boot.autoconfigure.SpringBootApplication;
2122
import org.springframework.context.annotation.Bean;
23+
import org.springframework.core.io.ClassPathResource;
2224
import org.springframework.mail.MailSender;
2325
import org.springframework.mail.SimpleMailMessage;
26+
import org.springframework.mail.javamail.JavaMailSender;
27+
import org.springframework.mail.javamail.MimeMessageHelper;
2428
import software.amazon.awssdk.services.ses.SesClient;
2529
import software.amazon.awssdk.services.ses.model.VerifyEmailAddressRequest;
2630

31+
/**
32+
* A sample application to demonstrate sending simple emails and emails with attachments.
33+
* <p>
34+
* To run this sample application, you need to do either of the following.
35+
* <ul>
36+
* <li>If you wish to send emails to a real email ID, you need to verify identities as mentioned in
37+
* <a href="https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html">the Amazon Simple Email Service
38+
* docs.</a> After you do that, simply update this sample app with email IDs that you have verified with AWS.</li>
39+
* <li>If you wish to just test out email sending capability in a test environment, you can do so by running localstack.
40+
* Just issue the following command from the root of the `spring-cloud-aws-ses-sample`:
41+
*
42+
* <pre>
43+
* docker-compose -f docker-compose.yml up -d
44+
* </pre>
45+
*
46+
* See more information on localstack see <a href="https://docs.localstack.cloud/getting-started/">here</a> and
47+
* <a href="https://docs.localstack.cloud/user-guide/aws/ses/">here</a>.</li>
48+
* </ul>
49+
* </p>
50+
*
51+
*/
2752
@SpringBootApplication
2853
public class MailSendingApplication {
2954
private static final String SENDER = "[email protected]";
@@ -37,7 +62,9 @@ public static void main(String[] args) {
3762
ApplicationRunner applicationRunner(MailSender mailSender, SesClient sesClient) {
3863
return args -> {
3964
sendAnEmail(mailSender, sesClient);
40-
// check localstack logs for sent email
65+
sendAnEmailWithAttachment(mailSender, sesClient);
66+
sendHtmlEmail(mailSender, sesClient);
67+
// check localstack logs for sent email, if you use localstack for running this sample
4168
};
4269
}
4370

@@ -56,4 +83,69 @@ public static void sendAnEmail(MailSender mailSender, SesClient sesClient) {
5683
mailSender.send(simpleMailMessage);
5784
}
5885

86+
/**
87+
* To send emails with attachments, you must provide the Java Mail API and an implementation of the API in the
88+
* classpath. See the dependencies provided in this sample app. If you don't provider an implementation of the Java
89+
* Mail API, you would get the following exception at runtime.
90+
*
91+
* <pre>
92+
* java.lang.IllegalStateException: Not provider of jakarta.mail.util.StreamProvider was found
93+
* </pre>
94+
*
95+
* @param mailSender A {@link JavaMailSender}.
96+
* @param sesClient An {@link SesClient}.
97+
*/
98+
public static void sendAnEmailWithAttachment(MailSender mailSender, SesClient sesClient) {
99+
// e-mail address has to verified before we email it. If it is not verified SES will return error.
100+
sesClient.verifyEmailAddress(VerifyEmailAddressRequest.builder().emailAddress(RECIPIENT).build());
101+
sesClient.verifyEmailAddress(VerifyEmailAddressRequest.builder().emailAddress(SENDER).build());
102+
103+
// A JavaMailSender is needed. Spring Cloud AWS SES automatically configures a JavaMailSender when it finds
104+
// the Java Mail API in the classpath. At runtime, an implementation of teh Java Mail API must also be
105+
// available.
106+
JavaMailSender javaMailSender = (JavaMailSender) mailSender;
107+
javaMailSender.send(mimeMessage -> {
108+
MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, true, "UTF-8");
109+
helper.addTo(RECIPIENT);
110+
helper.setFrom(SENDER);
111+
File resource = new ClassPathResource("answer.txt").getFile();
112+
helper.addAttachment("answer.txt", resource.getAbsoluteFile());
113+
helper.setSubject("What is the meaning of life, the universe, and everything?");
114+
helper.setText("Open the attached file for the answer you are seeking", false);
115+
});
116+
}
117+
118+
/**
119+
* To send HTML emails, you must provide the Java Mail API and an implementation of the API in the classpath. See
120+
* the dependencies provided in this sample app. If you don't provider an implementation of the Java Mail API, you
121+
* would get the following exception at runtime.
122+
*
123+
* <pre>
124+
* java.lang.IllegalStateException: Not provider of jakarta.mail.util.StreamProvider was found
125+
* </pre>
126+
*
127+
* @param mailSender A {@link JavaMailSender}.
128+
* @param sesClient An {@link SesClient}.
129+
*/
130+
public static void sendHtmlEmail(MailSender mailSender, SesClient sesClient) {
131+
// e-mail address has to verified before we email it. If it is not verified SES will return error.
132+
sesClient.verifyEmailAddress(VerifyEmailAddressRequest.builder().emailAddress(RECIPIENT).build());
133+
sesClient.verifyEmailAddress(VerifyEmailAddressRequest.builder().emailAddress(SENDER).build());
134+
135+
// A JavaMailSender is needed. Spring Cloud AWS SES automatically configures a JavaMailSender when it finds
136+
// the Java Mail API in the classpath. At runtime, an implementation of the Java Mail API must also be
137+
// available.
138+
JavaMailSender javaMailSender = (JavaMailSender) mailSender;
139+
javaMailSender.send(mimeMessage -> {
140+
MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, true, "UTF-8");
141+
helper.addTo(RECIPIENT);
142+
helper.setFrom(SENDER);
143+
helper.setSubject("What is the meaning of life, the universe, and everything?");
144+
String htmlMessage = """
145+
<h2>What is the meaning of life, the universe, and everything?</h2>
146+
<h3>42</h3>
147+
""";
148+
helper.setText(htmlMessage, true);
149+
});
150+
}
59151
}

‎spring-cloud-aws-samples/spring-cloud-aws-ses-sample/src/main/resources/answer.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Question to Spring Cloud AWS: What is the meaning of life, the universe, and everything?
2+
Answer from Spring Cloud AWS: 42

‎spring-cloud-aws-samples/spring-cloud-aws-ses-sample/src/main/resources/application.properties‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Localstack configuration
2+
spring.cloud.aws.endpoint=http://localhost:4566
3+
spring.cloud.aws.region.static=us-east-1
4+
spring.cloud.aws.credentials.access-key=noop
5+
spring.cloud.aws.credentials.secret-key=noop

0 commit comments

Comments
 (0)