spring boot email 전송 (spring-boot-starter-mail, mailjet)

Spring Boot Email 전송하기 (+ Mailjet)

spring boot email 전송하기

해당 포스팅은 스프링 부트에서 'spring-boot-starter-mail' 의존성을 사용하여 이메일을 전송하는 코드 예시입니다.

전체 코드는 포스팅 맨 하단에 github 주소를 링크해 두었으니 참고해 주시면 좋을 것 같습니다.

(아래 이메일 발송 코드는 spring boot 3.1.4 환경에서 작업되었습니다.)

 

---

SMTP

SMTP는 'Simple Mail Transfer Protocol'의 약자로 인터넷을 통해 이메일을 보내고 받는 데 사용되는 통신 프로토콜인데요.

SMTP 서버는 SMTP 프로토콜(Simple Mail Transfer Protocol)을 사용하여 메일을 보내는 메일 서버의 구성 요소를 말하며, 이메일 발신 작업에만 사용되기 때문에 '발신 이메일 서버'라고도 합니다.

 

해당 이메일 발송 예시에서는 SMTP 서버로 'Mailjet'을 사용했으며, Mailjet과 관련된 부분은 아래 이어지는 내용을 통해 살펴볼 수 있습니다.

 

 

---

Mailjet 계정 생성 및 API Key 발급

mailjet account information

Mailjet을 SMTP 서버로 사용하기 위해서는 Mailjet 계정 생성 및 API Key 발급 과정이 필요한데요.

계정 생성의 경우 이메일 인증 과정이 포함되어 있으며, 무료 등급의 경우 30일간 사용할 수 있고 신용카드 등록이 따로 필요하지 않습니다.

(2023년 10월 기준)

 

계정 생성 후 위 이미지의 Account information 페이지에서 우측 'API Key Management' 부분을 통해 API Key, Secret Key를 발급할 수 있으며, 좌측의 'Add a Sender Domain or Address' 부분을 통해 보내는 주소를 추가하거나 noreply@company.com 계정을 위한 도메인 인증을 할 수 있습니다.

 

 

mailjet api key, secret key

API KEY와 SECRET KEY는 properties(또는 yml)에서 각각 username, password로 사용됩니다.

 

 

---

application.yml 설정

spring:
  mail:
    host: in-v3.mailjet.com
    port: 587
    username: {Mailjet API KEY}
    password: {Mailjet SECRET KEY}
    from-address: 
    properties:
      mail:
        smtp:
          auth: ture
          starttls:
            enabled: true

(application.yml)

 

포트에는 보안된 SMTP인 SMTPS를 사용하는 이메일 전송 포트인 '587 port'가 사용됩니다.

또한 일부 SMTP 서버에는 TLS 연결이 필요하기 때문에 'spring.mail.properties.mail.smtp.starttls.enabled' 속성을 사용하여 TLS 보호 연결을 활성화합니다.

 

username, password의 경우 앞에서 이야기한 것처럼 mailjet에서 발급받은 'api key', 'secret key'를 입력하는데요.

username, password의 경우 외부에 노출되면 안 되기 때문에 해당 properties 또는 yml 파일의 gitignore 처리가 되어있는지는 꼭 확인이 필요한 부분입니다.

 

'spring.mail.from-address'의 경우 아래 구현 코드(MailServiceImpl)에서 볼 수 있지만 @Value 어노테이션을 통해 보내는 주소 값을 가져오기 위해 개인적으로 추가한 부분인데요.

보내는 주소의 경우 다음과 같이 외부 설정값을 통해 가져오지 않고 내부적으로 처리해도 문제가 없기 때문에 작업 환경에 맞게 적용하면 되는 부분입니다.

 

 

---

spring boot email 전송 구현 코드

@Getter
@Setter
@NoArgsConstructor
public class MailDto {

    private String toAddress;
    private String subject;
    private String text;
    private List<MultipartFile> attachmentFile;
}

(MailDto class)

 

@Service
@RequiredArgsConstructor
public class MailServiceImpl implements MailService {

    private final JavaMailSender mailSender;

    @Value("${spring.mail.from-address}")
    private String fromAddress;

    @Override
    public void sendMail(MailDto mailDto) {
        try {
            MailHandler mailHandler = new MailHandler(mailSender);

            mailHandler.setTo(mailDto.getToAddress());
            mailHandler.setFrom(fromAddress);
            mailHandler.setSubject(mailDto.getSubject());

            String htmlContent = "<p>" + mailDto.getText() + "<p><img src='cid:logo-img'>";
            mailHandler.setText(htmlContent, true);

            mailHandler.setInline("logo-img", "static/logo.png");

            if (!CollectionUtils.isEmpty(mailDto.getAttachmentFile())) {
                for (MultipartFile file : mailDto.getAttachmentFile()) {
                    mailHandler.setAttach(file);
                }
            }

            mailHandler.send();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

(MailServiceImpl class)

 

JavaMailSender 인터페이스의 경우 MailSender 인터페이스를 확장한 것으로 Java Mail API의 MimeMessage를 이용하여 메일을 발송하는 추가적인 기능이 정의되어 있습니다.

 

기본적인 메일의 경우 SimpleMailMessage를 사용하면 되지만, 첨부 파일이 포함된 경우 MimeMessage를 사용해야 하며, 스프링 부트에서는 MimeMessage를 편리하게 사용할 수 있도록 MimeMessageHelper 클래스를 추가로 지원하고 있습니다.

 

 

* MIME는 Multipurpose Internet Mail Extensions의 약자로 기존의 UUEncode 방식의 단점을 보완하여 나온 인코딩 방식입니다.

(UUEncode 방식의 경우 ASCII 파일만 지원하기 때문에 바이너리 파일을 전송할 수 없다는 큰 문제점이 있었습니다.)

 

 

MailSenderPropertiesConfiguration class

JavaMailSender 인터페이스의 구현체로는 JavaMailSenderImpl 클래스가 사용되는데요.

 

MailSenderPropertiesConfiguration 클래스를 살펴보면 mailSender() 메서드의 @ConditionalOnMissingBean(JavaMailSender.class) 부분을 통해 JavaMailSender 빈이 등록되어 있지 않은 경우 JavaMailSenderImpl 인스턴스를 생성하고 properties 정보를 적용시켜 해당 인스턴스를 빈으로 등록하는 것을 볼 수 있습니다.

 

 

public class MailHandler {

    private JavaMailSender mailSender;
    private MimeMessage mimeMessage;
    private MimeMessageHelper mimeMessageHelper;

    public MailHandler(JavaMailSender mailSender) throws MessagingException {
        this.mailSender = mailSender;
        this.mimeMessage = mailSender.createMimeMessage();
        this.mimeMessageHelper = new MimeMessageHelper(mimeMessage, true, "UTF-8");
    }

    //보내는 주소
    public void setFrom(String fromAddress) throws MessagingException {
        mimeMessageHelper.setFrom(fromAddress);
    }

    //받는 주소
    public void setTo(String toAddress) throws MessagingException {
        mimeMessageHelper.setTo(toAddress);
    }

    //받는 주소
    public void setTo(String[] toAddresses) throws MessagingException {
        mimeMessageHelper.setTo(toAddresses);
    }

    //setCc() 참조자 설정, setBcc() 숨은 참조자 설정

    //제목
    public void setSubject(String subject) throws MessagingException {
        mimeMessageHelper.setSubject(subject);
    }

    //내용
    public void setText(String text, boolean useHtml) throws MessagingException {
        mimeMessageHelper.setText(text, useHtml);
    }

    //첨부파일
    public void setAttach(MultipartFile attachmentFile) throws IOException, MessagingException {
        mimeMessageHelper.addAttachment(Objects.requireNonNull(attachmentFile.getOriginalFilename()), attachmentFile);
    }

    //이미지 삽입
    public void setInline(String contentId, String pathToInline) throws IOException, MessagingException {
        File file = new ClassPathResource(pathToInline).getFile();
        FileSystemResource fileSystemResource = new FileSystemResource(file);

        mimeMessageHelper.addInline(contentId, fileSystemResource);
    }

    //발송
    public void send() {
        mailSender.send(mimeMessage);
    }
}

(MailHandler class)

 

앞서 이야기한 것처럼 첨부파일이 포함된 경우 SimpleMailMessage가 아닌 MimeMessage 클래스를 사용하게 되는데요.

JavaMailSender 인터페이스는 MimeMessage 객체를 생성해 주는 createMimeMessage() 메서드를 제공합니다.

 

그리고 MimeMessage를 편리하게 사용하기 위해서 MimeMessageHelper를 사용하는데요.

MimeMessageHelper 생성자의 첫 번째 파라미터로 MimeMessage가 사용되고, 두 번째 파라미터로 Multipart 여부를 설정, 세 번째 파라미터로는 메시지에 사용할 문자 인코딩 값을 전달받습니다.

 

MimeMessageHelper 클래스에는 보내는 주소와 받는 주소를 설정하는 setFrom(), setTo() 메서드 외에도 참조자를 설정하는 setCc(), 숨은 참조자를 설정하는 setBcc() 등의 메서드도 있는데요.

위 코드에서 사용되지 않은 MimeMessageHelper 클래스의 전체 메서드들에 대해서는 아래 공식 문서를 참고하시면 좋을 것 같습니다.

 

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/mail/javamail/MimeMessageHelper.html

(MimeMessageHelper class 공식 문서)

 

 

addAttachment(String attachmentFilename, DataSource dataSource)
addAttachment(String attachmentFilename, File file)
addAttachment(String attachmentFilename, InputStreamSource inputStreamSource)

공식 문서를 보면 첨부 파일 추가에 사용되는 addAttachment() 메서드 역시 InputStreamSource 외에도 DataSource, File 타입을 파라미터로 받을 수 있기 때문에 필요에 따라 적절한 메서드를 추가해서 사용할 수 있습니다.

 

 

 

< 전체 코드 github 주소 >

https://github.com/JianChoi-Kor/send-mail

 

< 참고 자료 >

https://victorydntmd.tistory.com/342
https://www.baeldung.com/spring-email