Java Spring Boot에서 템플릿을 설정하고 이메일 발송하기

2025년 11월 27일에 작성되었고, 블로그를 이전하며 옮겨온 포스트입니다.
여기에서 원본을 확인할 수 있습니다.

Gmail 설정하기

만약 이미 2단게 인증 설정을 완료했고, 앱 비밀번호를 발급 받았다면 3단계로 건너뛰면 된다.

1. 2단계 인증 설정

Gmail을 통해 메일을 발송하려면, 계정의 2단계 인증이 활성화 상태여야 한다. Google 계정 페이지의 좌측 사이드 바에서 보안 및 로그인 메뉴를 탭하고, 하단 2단계 인증을 활성화 시켜준다.

2. 앱 비밀번호 설정

Google 계정 앱 비밀번호 페이지에서 앱 비밀번호를 설정해준다.

위 스크린샷 화면에서 아래 앱 이름 입력 란에 앱 이름을 입력해준다. 이후, 만들기 버튼이 활성화되면 클릭한다.

앱 비밀번호를 생성하면 위 화면과 같이 생성된 앱 비밀번호 Modal이 표시되는데, 이 비밀번호를 application.yml에서 사용할 것이기에 미리 다른 곳에 옮겨 적어준다.

3. POP/IMAP 설정

Google Gmail 설정 페이지에서 전달 및 POP/IMAP 설정 메뉴로 이동한다. 만약 설정 페이지로 바로가지지 않는다면 Gmail 좌측 사이드 바에서 라벨 관리를 탭하여 설정 페이지로 이동한다.

위 메뉴에서 아래의 내용을 설정한다.

POP 다운로드 → 모든 메일에 POP 사용하기 활성화
POP 다운로드 → POP로 메시지를 여는 경우 → Gmail 사본을 받은편지함에 보관하기
IMAP 액세스 → 자동 삭제 사용 안 함
IMAP 액세스 → 메일 보관(기본값)
IMAP 액세스 → 폴더 크기 제한 → IMAP 폴더에서 메일 수를 제한하지 않습니다(기본값).

위 사항을 모두 설정했다면 변경사항 저장 버튼을 눌러 변경한 모든 사항에 대해 설정해준다.

Spring Boot 의존성 추가 및 설정

Spring Boot에서는 Java Mail Sender 인터페이스를 활용해 이메일을 전송할 수 있다. 아래에서 추가하는 spring-boot-starter-mail 의존성은 Java Mail Sender 인터페이스를 직접적으로 활용할 수 있도록 도와주는 의존성이다.

1. 의존성 추가

build.gradle 파일의 dependencies에 아래의 의존성을 추가해 준다.

dependencies {
	...
	implementation 'org.springframework.boot:spring-boot-starter-mail'
	implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
	...
}

2. application.yml 설정

application.yml 파일에 아래와 같은 설정을 추가한다.

spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: (발신자 이메일 주소)
    password: (발급받은 앱 비밀번호)
    properties:
      mail:
        smtp:
          auth: true
          timeout: 5000
          starttls:
            enable: true

Spring Boot에서 이메일을 발송하도록 구현하기

1. MailController.java

src/java/(packages)/mail/controller/MailController.java

@RestController
@RequestMapping("/api/v1/mail")
@RequiredArgsConstructor
public class MailController {
    private final MailService mailService;

    @PostMapping("/test")
    public void test(@RequestParam String email) {
        mailService.sendMail(email);
    }
}

/api/v1/mail/test에 POST 요청으로 Parameter 값에 email , 즉 이메일 주소를 보내면 mailService의 sendMail() 함수가 실행되게 구현했다.

2. MailService.java

src/java/(packages)/mail/service/MailService.java

@Service
@Slf4j
@RequiredArgsConstructor
public class MailService {
    private final JavaMailSender mailSender;
    private final SpringTemplateEngine templateEngine;

    public void sendMail(String email) {
        try {
            MimeMessage mimeMessage = mailSender.createMimeMessage();

            MimeMessageHelper mimeMessageHelper = new MimeMessageHelper(mimeMessage, false, "UTF-8");
            mimeMessageHelper.setTo(email);
            mimeMessageHelper.setSubject("정보 처리 오류 안내");
            mimeMessageHelper.setText(setContext("test", LocalDateTime.now().toString()), true);

            mailSender.send(mimeMessage);

            log.info("[MailService] 메일 전송 성공: {}", email);
        } catch (MessagingException e) {
            log.error("[MailService] 메일 전송 실패: {}", e.getMessage());
            throw new RuntimeException(e);
        }
    }

    private String setContext(String type, String code) {
        Context context = new Context();
        context.setVariable("code", code);
        return templateEngine.process(type, context);
    }
}

sendMail()
1. JavaMailSender가 실제로 보내지는 이메일 내용을 담는 MimeMessage 객체를 생성한다.
2. 이후, MimeMessage를 더 쉽게 구현할 수 있는 MimeMessageHelper 객체를 생성한다.
  1. 이 때 new MimeMessageHelper(mimeMessage, false, "UTF-8") 는, 차례대로, MimeMessage 객체, MultiPart 사용 여부(첨부파일), 텍스트 인코딩이다.
3. 그리고 받는 사람, 이메일 제목, 본문을 설정한다. setText() 가장 마지막에 있는 파라미터 true 는 HTML 템플릿을 적용한다는 뜻이다.
  1. 가장 앞에 있는 test는 이메일 본문 템플릿의 파일 명이다. test.html이기에 test 로 설정해 주었다.
4. 마지막으로 JavaMailSender를 이용해 이메일을 보내고, 성공 로그를 남긴다.
setContext()
1. Context는 Thymeleaf에서 사용할 변수들을 담는 객체
2. 이후, 템플릿 파일에서 ${code}를 사용할 수 있도록 값을 주입한다.
3. SpringTemplateEngine을 이용해 템플릿을 렌더링하고, 값을 주입하고 HTML로 변환 해 반환한다

3. test.html

resources/templates/test.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
    <body>
        <div style="margin:100px;">
            <h1>이메일 전송 테스트</h1>
            <p>이 이메일은 이메일 전송 테스트 목적으로 발송되었습니다.</p>
            <br />
            <p style="font-size:130%" th:text="${code}"></p>
            <br/>
        </div>
    </body>
</html>

API에 요청을 보내 테스트하기

http://localhost:8080/api/v1/mail/test?email=${이메일주소}

위와 같이 만든 API의 파라미터 값에 이메일 주소를 넣고 요청을 보냈다. 그러면 아래 사진과 같이 코드에서 작성 했던 LocalDateTime.now() 값과 test.html 에 구현했던 템플릿을 이용해 이메일이 잘 발송했음을 확인할 수 있다.

마무리

Spring Boot에서 Google Gmail을 이용해 이메일을 발송하는 방법에 대해 정리해봤다. 현재는 개인 도메인으로 설정된 이메일 서버가 없지만, 이후 메일 서버를 구축한다면 Gmail과 동일하게 설정하여 이메일을 발송할 수 있게 구현하고 싶다는 생각이 들고, 이메일을 전송하기 전에 email 값이 이메일 주소 형식인지 검증하는 로직을 추가한다면 오류 발생이 더 줄어들 것이라고 생각하고 이 부분을 서비스에 구현하려고 한다.

'Backend > Java' 카테고리의 다른 글

(Spring Boot) Elasticsearch를 활용해 1,000만 개 데이터에서의 검색 속도 개선해보기 (0)	2026.08.23
AWS 탈탈 털리고, Amazon Lightsail을 이용해 안전하게 파일 업로드 해보기 (Spring Boot) (0)	2026.08.23
값이 반드시 유효해야 할 때: Spring Boot에서 Validation 처리하기 (0)	2026.08.22
[Spring Boot / JPA] @CreationTimestamp / @UpdateTimeStamp (0)	2026.08.22
Spring Boot와 ELK를 활용한 서비스 로그 수집 및 모니터링 (0)	2026.08.22