📧 이메일 인증 시스템 구현하기

Dataracy 프로젝트에서는 회원가입, 비밀번호 찾기, 비밀번호 재설정 과정에서 이메일 인증을 필수로 적용한다.
회원가입 시 사용자는 6자리 인증번호를 이메일로 수신하고, 해당 코드를 입력해 검증을 통과해야 가입이 완료된다.
비밀번호를 분실했을 경우에도 동일하게 이메일 인증 단계를 거쳐야 한다.

이 글에서는 실제 적용한 코드를 기준으로 이메일 인증 구현(SendGrid) → 이메일 발송 → Redis 기반 OTP 관리 → 검증 API까지 흐름을 정리한다.
또한 헥사고날 아키텍처 기반으로 Port / Adapter / Application / Domain 레이어를 명확히 분리한다.

---

1. 아키텍처 개요

[Web Controller] → [UseCase (SendEmailUseCase / VerifyEmailUseCase)]
        ↓
[Application Service] (EmailCommandService / EmailVerifyService)
        ↓
[Port Out] (SendEmailPort, VerifyEmailPort)
        ↓
[Adapter] (SendGrid Adapter, Redis Adapter)
        ↓
외부 서비스 (SendGrid / Redis)

• Controller: HTTP 요청 처리 (/email/send, /email/verify)
• Application Service: 인증번호 생성, 전송, 검증 로직 처리
• Port: 외부 I/O 추상화 (SendEmailPort, VerifyEmailPort)
• Adapter: SendGrid API 호출, Redis 저장/조회/삭제

---

2. 인증 코드 발송 (SendEmailUseCase)

EmailCommandService가 다음 단계를 수행한다.

1. SecureRandom으로 6자리 숫자 코드 생성한다.
2. EmailContentFactory로 이메일 제목과 본문을 생성한다.
3. SendEmailPort를 통해 SendGrid API를 호출하여 이메일을 전송한다.
4. VerifyEmailPort.saveCode를 통해 Redis에 인증 코드를 저장한다.

@Override
public void sendEmailVerificationCode(String email, EmailVerificationType type) {
    String code = generateCode(); // 6자리 숫자
    EmailContent content = EmailContentFactory.generate(type, code);

    try {
        sendEmailPort.send(email, content.subject(), content.body());
    } catch (Exception e) {
        throw new EmailException(EmailErrorStatus.FAIL_SEND_EMAIL_CODE);
    }

    verifyEmailPort.saveCode(email, code, type);
}

---

3. 이메일 발송 어댑터 (SendGrid)

SendEmailSendGridAdapter가 SendGrid API를 호출한다.

• from, to, subject, body를 구성해 메일 객체를 만든다.
• 실패 시 예외를 발생시키고 로그를 남긴다.

@Override
public void send(String email, String subject, String body) {
    Email from = new Email(sender);
    Email to = new Email(email);
    Content content = new Content("text/plain", body);

    Mail mail = new Mail(from, subject, to, content);
    Request request = new Request();
    request.setMethod(Method.POST);
    request.setEndpoint("mail/send");
    request.setBody(mail.build());

    Response response = sendGrid.api(request);
    if (response.getStatusCode() >= 400) {
        throw new RuntimeException("SendGrid 전송 실패");
    }
}

---

4. Redis를 통한 인증 코드 저장

EmailRedisAdapter가 Redis에 인증 코드를 저장한다.

• Key 구조: email:verification:{purpose}:{email}
• 만료 시간: 기본 5분 (TTL)
• Redis 장애 시 CommonException으로 변환한다.

@Override
public void saveCode(String email, String code, EmailVerificationType type) {
    String key = getEmailKey(email, type);
    redisTemplate.opsForValue().set(key, code, EXPIRE_MINUTES, TimeUnit.MINUTES);
}

---

5. 인증 코드 검증 (VerifyEmailUseCase)

EmailVerifyService가 검증을 수행한다.

1. Redis에서 저장된 코드를 조회한다.
2. 입력값과 비교한다.
   • 불일치 / 만료 시 EmailException을 발생시킨다.
3. 성공 시 Redis에서 코드를 삭제한다.
4. 비밀번호 찾기(PASSWORD_SEARCH) 목적일 경우 비로그인 유저이기 때문에 email을 담은 JWT 기반 Reset Token을 발급한다.

@Override
public GetResetTokenResponse verifyCode(String email, String code, EmailVerificationType type) {
    String savedCode = cacheEmailPort.verifyCode(email, code, type);
    if (savedCode == null) throw new EmailException(EmailErrorStatus.EXPIRED_EMAIL_CODE);
    if (!savedCode.equals(code)) throw new EmailException(EmailErrorStatus.FAIL_VERIFY_EMAIL_CODE);

    cacheEmailPort.deleteCode(email, type);

    if (type.equals(EmailVerificationType.PASSWORD_SEARCH)) {
        String resetToken = jwtGenerateUseCase.generateResetPasswordToken(email);
        cacheResetTokenUseCase.saveResetToken(resetToken);
        return new GetResetTokenResponse(resetToken);
    }
    return new GetResetTokenResponse(null);
}

---

6. 컨트롤러 (API 레이어)

EmailCommandController는 API 요청을 처리한다.

• 회원가입 → OK_SEND_EMAIL_CODE_SIGN_UP
• 비밀번호 찾기 → OK_SEND_EMAIL_CODE_PASSWORD_SEARCH
• 비밀번호 재설정 → OK_SEND_EMAIL_CODE_PASSWORD_RESET

각자 목적에 따라 이메일 제목과 내용을 enum으로 설정하여 목적에 맞는 이메일을 보낼 수 있게 설정하였다.

@Override
public ResponseEntity<SuccessResponse<Void>> sendCode(SendEmailWebRequest webRequest) {
    EmailVerificationType type = EmailVerificationType.of(webRequest.purpose());
    sendEmailUseCase.sendEmailVerificationCode(webRequest.email(), type);

    return switch (type) {
        case SIGN_UP -> ok(EmailSuccessStatus.OK_SEND_EMAIL_CODE_SIGN_UP);
        case PASSWORD_SEARCH -> ok(EmailSuccessStatus.OK_SEND_EMAIL_CODE_PASSWORD_SEARCH);
        case PASSWORD_RESET -> ok(EmailSuccessStatus.OK_SEND_EMAIL_CODE_PASSWORD_RESET);
    };
}

---

7. 핵심 포인트

• 헥사고날 아키텍처 적용
  비즈니스 로직과 외부 의존성(SendGrid, Redis)을 분리한다.

• 보안 고려
  인증번호는 6자리 숫자로 생성하며 TTL 5분을 두고 Redis에 저장한다.
  비밀번호 찾기 시 JWT Reset Token을 추가 발급한다.

• 로그 체계
  LoggerFactory 기반으로 API / Service / Redis / SendGrid 흐름을 구분해 기록한다.

---

🎯 결론

Dataracy 프로젝트에서는 회원가입 / 비밀번호 찾기 / 비밀번호 재설정 과정에 이메일 인증을 적용하여 계정 보안을 강화한다.

• SendGrid로 안정적인 이메일 발송을 구현한다.
• Redis로 OTP 저장·검증·삭제를 관리한다.
• JWT Reset Token으로 비밀번호 재설정 플로우를 완성한다.

✅ 이 구조를 통해 스팸률을 줄이고, 보안을 강화하며, 유지보수성을 높일 수 있게 되었다. 또한, 한 API 기능으로 여러 목적에 따라 다른 이메일을 보낼 수 있기에 효율이 좋다는 생각이 든다.