메일 발송

이 문서는 메일전송 소스와 방법에 대해 다룹니다.

첫 번째로는 Config 설정 방법 및 확인에 대해 설명합니다. 두 번째로 각 업무단 작성 방법을 설명합니다.

<update>

2023.08.03

• MailSendRequest siteNo 를 입력하지 않아도 자동으로 넘어가도록 수정했습니다.

2024.05.29

• sendTemplateMailBulk 추가

---

Config 설정

application.yml

mail:
  smtp:
    host: smtp.office365.com
    port: 587
    userName: [e-mail]
    password: X2commerce!1
  fromMail: [e-mail]
  fromNameKo: 플래티어_X2BEE
  fromNameEn: PLATEER_X2BEE

Sample 소스 및 설명

• x2bee-api-sample-vanilla 프로젝트

MailController 예시 (요약):

@Autowired
private MailSender mailSender;

@PostMapping("/send")
public ResponseEntity<Response> send() throws MessagingException, UnsupportedEncodingException {
    Map<String, Object> params = new HashMap<>();
    // 템플릿용 파라미터
    params.put("name","teset");

    // 단건 전송
    MailSendRequest request = MailSendRequest.builder()
        .siteNo("1") // null 일 경우 Cookie에서 자동입력됩니다.
        .mbrNo("100033")
        .emailGbCd("EMA-MA_11")
        .emailTitle("안녕하세요 이메일 전송 테스트입니다.")
        .emailConts("이메일 내용이 들어가는 곳입니다.") // 템플릿을 사용하는경우 삭제!
        .template("sample/sp1") // 템플릿을 사용하는 경우 ---(2)필독!
        .variables(params) // 템플릿용 파라미터
        .recvmnNm("테스트")
        .recvmnEmailAddr("[e-mail]")
        .build();

    // ----- API-COMMON 프로젝트에서 직접 호출시
    mailSender.send(request);

    // ----- API-COMMON 호출시
    // restApiUtil.post(
    //   this.commonApiUrl + "/api/common/interface/bizmessage/sendmail",
    //   request,
    //   new ParameterizedTypeReference<Response<Void>>() {}
    // ).getPayload();

    // 대량 전송 예시
    List<MailSendRequest> mailSendRequestList = new ArrayList<>();
    for (int i = 0; i < 10; i++) {
        mailSendRequestList.add(
            MailSendRequest.builder()
                .siteNo("1") // null 일 경우 Cookie에서 자동입력됩니다.
                .mbrNo("100033")
                .emailGbCd("EMA-MA_11")
                .emailTitle("안녕하세요 이메일 전송 테스트 : "+(i+1))
                .emailConts("이메일 내용이 들어가는 곳입니다. -- "+(i+1)) // 템플릿을 사용하는경우 삭제!
                .template("sample/sp1") // 템플릿을 사용하는 경우 ---(2)필독!
                .variables(params) // 템플릿용 파라미터
                .recvmnNm("테스트")
                .recvmnEmailAddr("[e-mail]")
                .build()
        );
    }

    // ----- API-COMMON 프로젝트에서 직접 호출시
    // mailSender.sendBulk(mailSendRequestList);

    // ----- API-COMMON 호출시
    // restApiUtil.post(
    //   this.commonApiUrl + "/api/common/interface/bizmessage/sendmailbulk",
    //   mailSendRequestList,
    //   new ParameterizedTypeReference<Response<Void>>() {}
    // ).getPayload();

    ...
}

MailSendRequest 를 생성하여 예제와 아래 테이블을 참조하여 파라미터를 입력합니다.

항목	Mandatory	Type	설명	비고
siteNo	NOT NULL (자동입력)	String	사이트 번호	null 로 작성시 쿠키값 자동입력
mbrNo	NOT NULL	String	회원 번호
emailGbCd	NOT NULL	String	이메일구분코드(CM030)
emailTitle	NOT NULL	String	이메일 제목
emailConts	NOT NULL	String	이메일 내용
recvmnNm	NOT NULL	String	수신자 성명
recvmnEmailAddr	NOT NULL	String	수신자 이메일 주소

Builder 가 익숙치 않다면 Setter 도 사용 가능합니다:

MailSendRequest mailSendRequest = new MailSendRequest();
...
mailSendRequest.setEmailTitle("이메일 제목");
mailSendRequest.setEmailConts("이메일 내용");
mailSendRequest.setRecvmnEmailAddr("[e-mail]");
...
mailSender.send(mailSendRequest);

sendBulk 추가

• 대량의 메시지를 한번에 전송하는 sendBulk 메서드가 추가되었습니다.

• X2BEE-COMMON 0.6.3 이후 사용 가능

  • MailSendRequest 객체를 List로 받아 이메일 전송을 처리합니다.

  • Process : 메일전송 목록 INSERT (동기), 메일전송 처리 (비동기)

  • 테이블.컬럼명 : ST_EMAIL_SND_HIST.email_trns_stat_cd (CM029) – 전송 성공 : 30 → 발송완료, 전송 실패 : 20 → 발송ERROR

1. 다른 프로젝트에서 이메일 전송 시 (api-common 호출)

• x2bee-api-common-vanilla 가 아닌 다른 프로젝트에서 이메일을 전송하는 경우 api-common API를 호출합니다.

• 예제 소스와 같이 MailSendRequest 객체에 필요 파라미터들을 담아 POST 방식으로 /api/common/interface/bizmessage/sendmail End Point를 호출합니다.

• commonApiUrl 은 application.yml 에 명시된 URL 입니다.

1. 템플릿을 사용하는 경우 (필독)

• 기존 각 프로젝트에 있었던 MailSender 를 Common으로 옮기면서 각 프로젝트에 있던 타임리프 템플릿 들도 함께 x2bee-api-common-vanilla 으로 이동했습니다.

• 따라서 템플릿을 새로 생성할 때에는 각 프로젝트 폴더에 맞는 경로에 넣어주셔야 합니다.

• 템플릿 경로 (email/apibo, email/apidisplay 등) 는 각 프로젝트의 application.yml 에 명시되어 template 변수를 Builder 와 Setter 에서 문자열 앞에 자동으로 추가합니다.

• 따라서 템플릿을 명시할 때에는 email/apibo 이후의 경로부터 입력합니다.

  • ex) x2bee-api-display-vanilla 프로젝트 내 application.yml

  • 

---

sendTemplateMailBulk 추가

• 기존 mail api와 달리 템플릿 데이터를 상위 파라미터로 받아 메일을 보내는 sendTemplateMailBulk가 추가되었습니다.

• X2BEE-COMMON 0.9.71 이후 사용 가능

• 기존과 같이 템플릿 파일 경로 넣어서 사용하거나 템플릿 데이터를 문자열로 보내 사용할 수 있습니다.

Sample 소스 — sendTemplateMailBulk

템플릿 파일 경로를 사용할 경우 예시:

MailSendTemplateRequest mailSendTemplateRequest = new MailSendTemplateRequest();
mailSendTemplateRequest.setTemplate("email/apimember/Join_ko");
mailSendTemplateRequest.setMailList(mailSendRequestList);

restApiUtil.post(
  this.commonApiUrl + "/api/common/interface/bizmessage/sendTemplateMailBulk",
  mailSendTemplateRequest,
  new ParameterizedTypeReference<Response<Void>>() {}
).getPayload();

템플릿 문자열로 사용할 경우 예시:

MailSendTemplateRequest mailSendTemplateRequest = new MailSendTemplateRequest();
mailSendTemplateRequest.setTemplate("<!DOCTYPE html><html lang='en'><head><meta charset='UTF-8' /><title>회원가입완료 안내</title></head><body><tbody><td>[<span th:text='${userName}'></span>]님, 안녕하세요.<br />[<span th:text='${userName}'></span>]님의 회원가입을 진심으로 감사드립니다.</td></tbody></table></body></html>");
mailSendTemplateRequest.setMailList(mailSendRequestList);

restApiUtil.post(
  this.commonApiUrl + "/api/common/interface/bizmessage/sendTemplateMailBulk",
  mailSendTemplateRequest,
  new ParameterizedTypeReference<Response<Void>>() {}
).getPayload();

---