Gmail OAuth2와 Express로 전문 이메일 서비스 구축하기

프로젝트 개요

현대 웹 애플리케이션에서 이메일 알림은 필수적입니다. 이번 포스트에서는 Express.js 및 Gmail의 OAuth2 인증을 사용하여 안전한 이메일 알림 서비스를 구축하는 방법을 안내합니다. 이 서비스를 통해 웹훅 요청을 받아 자동으로 이메일을 전송할 수 있습니다.

우리가 만들 서비스

우리는 다음과 같은 기능을 가진 Express 서버를 구축할 것입니다:

• POST 요청을 통해 웹훅 데이터 수신
• OAuth2를 사용한 Gmail 인증
• 웹훅 페이로드를 기반으로 맞춤형 이메일 전송
• 에러 감지 및 우아하게 처리

사전 준비사항

이 프로젝트를 시작하기 전에 다음 사항을 준비하세요:

• Node.js가 설치된 컴퓨터
• 구글 클라우드 콘솔에서 Gmail API가 활성화된 프로젝트
• OAuth2 자격 증명(클라이언트 ID, 클라이언트 시크릿, 리프레시 토큰)
• Express.js 및 async/await에 대한 기본 이해

프로젝트 설정

필요한 패키지를 설치합니다:

npm install express body-parser nodemailer googleapis dotenv

.env 파일을 만들어 자격 증명을 추가합니다:

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
REDIRECT_URI=your_redirect_uri
REFRESH_TOKEN=your_refresh_token
EMAIL_USER=your_email@gmail.com

이 자격 증명을 설정하는 데 어려움을 겪는 경우, 아래 단계에 따라 해결할 수 있습니다...

1단계: 새로운 Google Cloud 프로젝트 생성

1. Google Cloud Console에 방문합니다.
2. 페이지 상단의 프로젝트 드롭다운을 클릭합니다.
3. "새 프로젝트"를 클릭합니다.
4. 프로젝트 이름을 입력하고 "생성"을 클릭합니다.

2단계: Gmail API 활성화

1. 왼쪽 사이드바에서 "API 및 서비스" > "라이브러리"로 이동합니다.
2. "Gmail API"를 검색합니다.
3. "Gmail API"를 클릭하고 "사용"을 클릭합니다.

3단계: OAuth 동의 화면 구성

1. "API 및 서비스" > "OAuth 동의 화면"으로 이동합니다.
2. "외부" 사용자 유형을 선택하고 "작성"을 클릭합니다.
3. 필요한 필드를 작성합니다:
   • 앱 이름: [앱 이름]
   • 사용자 지원 이메일: [이메일]
   • 개발자 연락처 정보: [이메일]
4. "저장 후 계속"을 클릭합니다.
5. "범위" 페이지에서 "범위 추가 또는 제거"를 클릭합니다.
6. "https://mail.google.com/" 범위를 찾아 선택합니다.
7. "업데이트"를 클릭한 후 "저장 후 계속"을 클릭합니다.
8. "테스트 사용자" 페이지에서 "사용자 추가"를 클릭합니다.
9. 자신의 Gmail 주소를 추가하고 "저장 후 계속"을 클릭합니다.
10. 요약을 검토한 후 "대시보드로 돌아가기"를 클릭합니다.

4단계: OAuth2 자격 증명 생성

1. "API 및 서비스" > "자격 증명"으로 이동합니다.
2. "자격 증명 만들기" > "OAuth 클라이언트 ID"를 클릭합니다.
3. 응용 프로그램 유형으로 "웹 애플리케이션"을 선택합니다.
4. 이름: [앱 이름]
5. 승인된 JavaScript 출처: 서버 도메인 추가(e.g., http://localhost:3000, 로컬 개발 시)
6. 승인된 리디렉션 URI:
   • https://developers.google.com/oauthplayground 추가
   • 서버의 콜백 URL 추가(e.g., http://localhost:3000/auth/google/callback)
7. "생성"을 클릭합니다.
8. 팝업에서 클라이언트 ID 및 클라이언트 비밀번호를 저장합니다.

5단계: 새로운 리프레시 토큰 받기

1. Google OAuth Playground로 이동합니다.
2. 오른쪽 상단의 톱니바퀴 아이콘 클릭합니다.
3. "내 OAuth 자격 증명을 사용" 체크박스를 클릭합니다.
4. 당신의 클라이언트 ID와 클라이언트 시크릿을 입력합니다.
5. 설정을 닫습니다.
6. 왼쪽 사이드바에서 "Gmail API v1"을 찾아 선택합니다.
7. "https://mail.google.com/"를 선택합니다.
8. "API 권한 승인" 클릭합니다.
9. Google 계정을 선택하고 요청된 권한을 부여합니다.
10. 다음 화면에서 "인증 코드로 토큰 교환" 클릭합니다.
11. 응답에서 "리프레시 토큰"을 복사합니다.

이 과정에서 문제가 발생하거나 이메일 기능 테스트 중 오류 메시지를 확인한 경우, 댓글로 구체적인 오류 메시지를 제공해 주시기 바랍니다.

코드 설명

이제 구현 내용을 단계별로 살펴보겠습니다.

1. 초기 설정 및 의존성

const express = require("express");
const bodyParser = require("body-parser");
const nodemailer = require("nodemailer");
const { google } = require("googleapis");
require("dotenv").config();

const app = express();
app.use(bodyParser.json());

이 섹션은 Express 서버를 설정하고 필요한 패키지를 가져옵니다. body-parser를 사용하여 JSON 요청을 구문 분석하고, dotenv를 사용하여 환경 변수를 관리합니다.

2. OAuth2 설정

const oAuth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);
oAuth2Client.setCredentials({ refresh_token: REFRESH_TOKEN });

구글의 인증 라이브러리를 사용하여 OAuth2 클라이언트를 생성합니다. 이 클라이언트는 Gmail API와의 인증을 처리합니다.

3. 이메일 전송 기능

async function sendEmail(webhookData) {
  const {
    receiver_email,
  } = webhookData;

  try {
    const accessToken = await oAuth2Client.getAccessToken();
    const transport = nodemailer.createTransport({
      service: "gmail",
      auth: {
        type: "OAuth2",
        user: process.env.EMAIL_USER,
        clientId: CLIENT_ID,
        clientSecret: CLIENT_SECRET,
        refreshToken: REFRESH_TOKEN,
        accessToken: accessToken,
      },
    });

    const mailOptions = {
      from: `Your Name <${process.env.EMAIL_USER}>`,
      to: receiver_email,
      subject: ``, // 이메일 제목 추가
      html: ``, // HTML 템플릿 추가
    };

    return await transport.sendMail(mailOptions);
  } catch (error) {
    console.error("sendMail 함수에서 오류 발생:", error);
    throw error;
  }
}

이 함수는 다음과 같은 기능을 수행합니다:

• 웹훅 페이로드에서 데이터를 추출 (필요에 따라 수정)
• 새 액세스 토큰을 가져옴
• OAuth2 인증으로 트랜스포트를 생성
• 맞춤형 내용을 담아 이메일을 전송

4. 웹훅 엔드포인트

app.post("/webhook", async (req, res) => {
  try {
    const webhookData = req.body;
    await sendEmail(webhookData);
    res.status(200).send("이메일이 성공적으로 전송되었습니다.");
  } catch (error) {
    console.error("웹훅 처리 중 오류 발생:", error);
    res.status(500).send("웹훅 처리 중 오류가 발생했습니다.");
  }
});

우리의 웹훅 엔드포인트는 다음과 같은 기능을 수행합니다:

• POST 요청 수신
• 웹훅 데이터 처리
• 이메일 전송
• 적절한 응답 반환

테스트하기

curl이나 Postman을 사용하여 웹훅 테스트를 진행할 수 있습니다:

curl -X POST http://localhost:4000/webhook \
-H "Content-Type: application/json" \
-d '{
  "receiver_email": "test@example.com",
}'

문제 해결

일반적인 문제와 해결 방법은 다음과 같습니다:

• 인증 오류: OAuth2 자격 증명 확인
• 토큰 만료: 리프레시 토큰이 유효한지 확인
• 데이터 누락: 웹훅 페이로드 유효성 검사

결론

이제 당신은 안전하고 OAuth2 인증된 이메일 알림 시스템을 구축하였습니다! 이 구현은 보안성과 신뢰성을 유지하면서 더 복잡한 알림 시스템을 구축할 수 있는 좋은 기초가 됩니다.

이 포스트가 이메일 서비스를 설정하는 데 도움이 되었기를 바랍니다.

행복한 코딩 되세요! 🚀

---

참고할 수 있는 자료