[Spring] eGovFramework 환경에서 구글 SMTP 연동 및 첨부파일 메일 보내기

안녕하세요! 이번 포스팅에서는 전자정부프레임워크(eGovFramework) 및 일반 스프링(Spring MVC/Boot) 환경에서 Apache Commons Email 라이브러리를 활용해 이메일을 발송하는 방법을 알아보겠습니다.

 

 1. 개발 환경 및 사전 준비

• Language: Java 11 이상
• Framework: Spring Framework / eGovFramework (Jakarta 패키지 기반)
• Library: Apache Commons Email 2.x (org.apache.commons.mail2.jakarta)
• SMTP Server: Gmail SMTP (smtp.gmail.com)

 

# Maven 의존성 추가 (pom.xml)

Jakarta 톰캣 환경에 맞는 Commons Email 라이브러리를 의존성에 추가합니다.

<dependency>
    <groupId>org.apache.commons.mail2</groupId>
    <artifactId>commons-mail2-jakarta</artifactId>
    <version>2.0.0-alpha1</version> 
</dependency>

 

# 구글(Gmail) 앱 비밀번호 발급

Gmail SMTP를 외부에서 호출하려면 계정의 일반 비밀번호가 아닌 16자리 앱 비밀번호가 필요합니다.

 

1. 구글 계정 설정 -> 보안 이동

https://support.google.com/accounts/answer/185833?hl=ko

앱 비밀번호로 로그인 - Google 계정 고객센터

 

2. 2단계 인증 활성화

 

3. 맨 아래 앱 비밀번호 메뉴 클릭 후 생성 및 16자리 키 복사

 

 

2. 일반 텍스트 메일

가장 기본적인 형태로, 별도의 첨부파일 없이 제목과 텍스트 본문만 전송할 때 사용합니다. 텍스트 전송에 최적화된 SimpleEmail 객체를 이용합니다.

 

# 이메일 공통 유틸리티 클래스 구현 (EgovMail.java)

import org.apache.commons.mail2.core.EmailException;
import org.apache.commons.mail2.jakarta.EmailAttachment;
import org.apache.commons.mail2.jakarta.SimpleEmail;

/**
 * Apache Commons Email 기반 이메일 발송 유틸리티 클래스
 */
public class EgovMail {

    // [공통 설정] SMTP 서버 정보 및 발신자 정보
    private static final String HOST_NAME = "smtp.gmail.com";
    private static final int SMTP_PORT = 587; // TLS 포트
    private static final String SENDER_EMAIL = "@gmail.com"; // 발신 구글 계정
    private static final String SENDER_NAME = "발신자명";
    private static final String APP_PASSWORD = "xxxx xxxx xxxx xxxx"; // 구글 앱 비밀번호 16자리
    private static final String CHARSET = "euc-kr"; // 한글 인코딩 설정

    /**
     * 일반 텍스트 메일 발송
     * @param targetEmail 수신자 이메일
     * @param targetName  수신자 이름
     * @param subject     메일 제목
     * @param content     메일 내용 (텍스트)
     */
    public static void sendSimpleMail(String targetEmail, String targetName, String subject, String content) {
        // 텍스트 전송 전용 SimpleEmail 객체 생성
        SimpleEmail email = new SimpleEmail();

        try {
            // SMTP 서버 기본 설정
            email.setCharset(CHARSET);
            email.setHostName(HOST_NAME);
            email.setSmtpPort(SMTP_PORT);
            email.setStartTLSEnabled(true); // TLS 보안 연결 설정 (필수)
            email.setAuthentication(SENDER_EMAIL, APP_PASSWORD); // 인증 정보 주입

            // 송수신자 및 내용 세팅
            email.addTo(targetEmail, targetName);
            email.setFrom(SENDER_EMAIL, SENDER_NAME);
            email.setSubject(subject);
            email.setContent(content, "text/plain; charset=" + CHARSET);

            // 메일 전송
            email.send();
            System.out.println("=> [SimpleMail] 발송 성공 성공 (수신: " + targetEmail + ")");

        } catch (EmailException e) {
            System.err.println("=> [SimpleMail] 발송 실패: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

 

# 스프링 컨트롤러 연동 (MailController.java)

웹 요청을 받아 유틸리티 클래스를 호출하는 컨트롤러 레이어 구현입니다. 실무 인터페이스와의 연동을 위해 HttpServletResponse로 성공 여부를 반환하도록 구성했습니다.

import javax.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import egovframework.cmmn.util.EgovMail;

@Controller
public class MailController {

    /**
     * 일반 텍스트 메일 테스트 API
     */
    @RequestMapping("/simpleMail.do")
    public void testSimpleMail(HttpServletResponse response) {
        String targetEmail = ""; // 수신자 메일
        String targetName = ""; // 수신자명
        String subject = "[알림] 시스템 공지사항 안내";
        String content = "안녕하세요. 시스템이 정상적으로 구동 중입니다.";

        try {
            EgovMail.sendSimpleMail(targetEmail, targetName, subject, content);
            
            response.setContentType("text/html; charset=UTF-8");
            response.getWriter().write("success");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

 

# Postman을 활용한 API 기능 테스트

작성된 API가 정상적으로 동작하는지 API 테스트 도구인 Postman으로 검증하는 단계입니다.

1. Method / URL: POST http://localhost:/simpleMail.do
2. Body: x-www-form-urlencoded 선택 (현재 파라미터를 고정값으로 처리했으므로 Key-Value 없이 Send 가능)
3. 결과: 200 OK 응답과 함께 Body 창에 success 텍스트 반환 확인. 수신자 메일함에 텍스트가 정상 도착하는지 체크합니다.

3. 로컬 파일 첨부 메일

서버 내부 디스크(예: D:\test.txt)에 실제로 물리적인 파일이 존재할 때, 해당 파일을 이메일에 동반하여 발송하는 방법입니다. 파일 처리가 가능한 MultiPartEmail과 파일 정보를 담는 EmailAttachment 객체를 함께 사용합니다.

 

# 이메일 공통 유틸리티 클래스 구현 (EgovMail.java)

import org.apache.commons.mail2.core.EmailException;
import org.apache.commons.mail2.jakarta.EmailAttachment;
import org.apache.commons.mail2.jakarta.MultiPartEmail;

/**
 * Apache Commons Email 기반 이메일 발송 유틸리티 클래스
 */
public class EgovMail {

    // [공통 설정] SMTP 서버 정보 및 발신자 정보
    private static final String HOST_NAME = "smtp.gmail.com";
    private static final int SMTP_PORT = 587; // TLS 포트
    private static final String SENDER_EMAIL = "@gmail.com"; // 발신 구글 계정
    private static final String SENDER_NAME = "시스템 관리자";
    private static final String APP_PASSWORD = "xxxx xxxx xxxx xxxx"; // 구글 앱 비밀번호 16자리
    private static final String CHARSET = "euc-kr"; // 한글 인코딩 설정
    
    /**
     * 2. 로컬 파일 첨부 메일 발송
     * @param targetEmail 수신자 이메일
     * @param targetName  수신자 이름
     * @param subject     메일 제목
     * @param content     메일 본문 내용
     * @param filePath    서버 로컬 파일 절대 경로 (예: D:\\test.csv)
     * @param fileName    수신자가 다운로드 받을 때 보일 파일명 (ex. test.csv)
     */
    public static void sendAttachmentMail(String targetEmail, String targetName, String subject, String content, String filePath, String fileName) {
        try {
            // 1) 첨부파일 정보 객체(EmailAttachment) 생성
            EmailAttachment attachment = new EmailAttachment();
            attachment.setPath(filePath); // 로컬 파일 경로 바인딩
            attachment.setDisposition(EmailAttachment.ATTACHMENT);
            attachment.setDescription("시스템 자동 첨부파일입니다.");
            attachment.setName(fileName); // 이메일에서 보일 파일 이름 설정

            // 2) 파일 첨부가 가능한 MultiPartEmail 객체 생성 및 설정
            MultiPartEmail email = new MultiPartEmail();
            email.setCharset(CHARSET);
            email.setHostName(HOST_NAME);
            email.setSmtpPort(SMTP_PORT);
            email.setStartTLSEnabled(true);
            email.setAuthentication(SENDER_EMAIL, APP_PASSWORD);

            email.addTo(targetEmail, targetName);
            email.setFrom(SENDER_EMAIL, SENDER_NAME);
            email.setSubject(subject);
            email.setMsg(content); // MultiPart에서는 setMsg() 사용 가능

            // 3) 이메일에 첨부파일 객체 추가 후 전송
            email.attach(attachment);
            email.send();
            System.out.println("=> [AttachmentMail] 발송 성공 (첨부파일: " + fileName + ")");

        } catch (EmailException e) {
            System.err.println("=> [AttachmentMail] 발송 실패: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

 

#  스프링 컨트롤러 연동 (MailController.java)

import javax.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import egovframework.cmmn.util.EgovMail;

@Controller
public class MailController {

    /**
     * 로컬 파일 첨부 메일 테스트 API
     */
    @RequestMapping("/attachmentMail.do")
    public void testAttachmentMail(HttpServletResponse response) {
        String targetEmail = ""; // 수신자 메일
        String targetName = ""; // 수신자명
        String subject = "[알림] 시스템 공지사항 안내_첨부파일 확인";
        String content = "안녕하세요. 시스템이 정상적으로 구동 중입니다. 자세한 내용은 첨부파일 확인바랍니다.";
        
        // 서버 로컬 경로에 파일이 실제로 생성되어 있어야 에러가 나지 않음
        String filePath = "D:\\test.csv"; 
        String fileName = "test.csv";

        try {
            EgovMail.sendAttachmentMail(targetEmail, targetName, subject, content, filePath, fileName);
            
            response.setContentType("text/html; charset=UTF-8");
            response.getWriter().write("success");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

 

# Postman을 활용한 API 기능 테스트

1. 사전 준비: 서버 컴퓨터의 D:\ 드라이브 최상위에 test.csv 파일을 임의로 하나 생성합니다.
2. Method / URL: POST http://localhost:/attachmentMail.do
3. 결과: 정상 발송 시 이클립스 콘솔에 => [AttachmentMail] 발송 성공 문구가 출력되며, 지정한 수신자 메일함에 test.csv 파일이 첨부된 상태로 전달됩니다.

 

4. 웹 URL 파일 첨부 메일 발송

서버에 저장된 파일이 아니라, 웹상에 노출된 URL 링크(ex. 파일 다운로드 API 주소 또는 정적 이미지 주소 등)를 통해 실시간으로 파일을 스트리밍하여 첨부파일로 변환해 보내는 기능입니다. EmailAttachment에 로컬 경로 대신 java.net.URL 객체를 주입합니다.

 

# 이메일 공통 유틸리티 클래스 구현 (EgovMail.java)

import org.apache.commons.mail2.core.EmailException;
import org.apache.commons.mail2.jakarta.EmailAttachment;
import java.net.MalformedURLException; 
import java.net.URL;                   // 웹 주소(String)를 URL 객체로 변환하기 위해 필요

/**
 * Apache Commons Email 기반 이메일 발송 유틸리티 클래스
 */
public class EgovMail {

    // [공통 설정] SMTP 서버 정보 및 발신자 정보
    private static final String HOST_NAME = "smtp.gmail.com";
    private static final int SMTP_PORT = 587; // TLS 포트
    private static final String SENDER_EMAIL = "@gmail.com"; // 발신 구글 계정
    private static final String SENDER_NAME = "발신자명";
    private static final String APP_PASSWORD = "xxxx xxxx xxxx xxxx"; // 구글 앱 비밀번호 16자리
    private static final String CHARSET = "euc-kr"; // 한글 인코딩 설정


  /**
     * 3. 웹 URL 첨부 파일 메일 발송
     * @param targetEmail 수신자 이메일 주소
     * @param targetName  수신자 이름
     * @param subject     메일 제목
     * @param content     메일 본문 내용
     * @param fileUrl     다운로드 가능한 웹 파일의 전체 URL 
     * @param fileName    수신자가 메일에서 첨부파일을 다운로드할 때 표시될 파일명 (예: test.csv)
   */
   public static void sendUrlAttachmentMail(String targetEmail, String targetName, String subject, String content, String fileUrl, String fileName) {
      try {
         EmailAttachment attachment = new EmailAttachment();
         attachment.setURL(new URL(fileUrl));
         attachment.setDisposition(EmailAttachment.ATTACHMENT);
         attachment.setName(fileName);

         MultiPartEmail email = new MultiPartEmail();
         email.setCharset(CHARSET);
         email.setHostName(HOST_NAME);
         email.setSmtpPort(SMTP_PORT);
         email.setStartTLSEnabled(true);
         email.setAuthentication(SENDER_EMAIL, APP_PASSWORD);

         email.addTo(targetEmail, targetName);
         email.setFrom(SENDER_EMAIL, SENDER_NAME);
         email.setSubject(subject);
         email.setMsg(content);

         email.attach(attachment);
         email.send();
         System.out.println("URL 파일 메일 발송 성공!");
      } catch (EmailException | MalformedURLException e) {
         System.err.println("URL 파일 메일 발송 실패: " + e.getMessage());
         e.printStackTrace();
      }
   }
}

 

#  스프링 컨트롤러 연동 (MailController.java)

import javax.servlet.http.HttpServletResponse;          
import org.springframework.stereotype.Controller;       
import org.springframework.web.bind.annotation.RequestMapping; 
import egovframework.cmmn.util.EgovMail;
@Controller
public class MailController {
   
   /**
     * 웹 URL 첨부 파일 메일 테스트 API
   */
   @RequestMapping("/urlFiletMail.do")
   public void urlFileMail(HttpServletResponse response) {

      try {
		 String targetEmail = ""; // 수신자 메일
		 String targetName = ""; // 수신자명
		 String subject = "[알림] URL 첨부파일 test 알림입니다.";
		 String content = "URL 첨부파일 메일 발송 완료";
         
         String fileUrl = "http://";
         String fileName = "test.csv";

         EgovMail.sendUrlAttachmentMail(targetEmail, targetName, subject, content, fileUrl, fileName);
         response.setContentType("text/html; charset=UTF-8");
         response.getWriter().write("success");

         System.out.println("URL 첨부 이메일 발송 성공!");

      } catch (Exception e) {
         System.err.println("URL 첨부 이메일 발송 실패: " + e.getMessage());
         e.printStackTrace();
      }
   }
}

 

# Postman 기능 테스트

• 사전 준비: fileUrl 주소 자체가 브라우저나 Postman에서 별도로 호출했을 때 에러 없이 다운로드가 잘 동작하는 주소인지 확인해 둡니다.
• Method / URL: POST http://localhost:/urlFiletMail.do
• 결과: API 요청 성공 시 콘솔에 URL 파일 메일 발송 성공!이 찍히고, 메일함에서는 웹 URL에서 스트리밍되어 가져온 파일 데이터가 test.csv라는 이름으로 안전하게 첨부된 것을 볼 수 있습니다.