Nodemailer로 Node.js 서버에서 이메일 보내기: Gmail OAuth2 설정까지 완벽 가이드

Nodemailer는 서버에서 손쉽게 이메일을 보낼 수 있도록 도와주는 Node.js 모듈입니다. 사용자와 소통하거나 오류가 발생했을 때 스스로에게 알림을 보내고 싶은 경우, 이메일은 가장 효과적인 방법 중 하나입니다.

인터넷에는 Nodemailer의 기본적인 사용법만 다룬 글이 많지만, 이 글은 조금 다릅니다. 여기서는 Nodemailer와 Gmail을 활용해 Node.js 백엔드에서 이메일을 보내는 가장 일반적이고 실전적인 방법을 단계별로 소개합니다.

Nodemailer 시작하기

먼저 Express를 사용해 Node.js 프로젝트의 기본 구조를 세팅해야 합니다. Node와 npm이 설치되어 있는지 확인하려면 아래 명령어를 실행하세요:

node -v 
npm -v

두 명령어 모두 버전 정보가 출력되면 준비가 된 것입니다. 그렇지 않다면 누락된 항목을 먼저 설치하세요.

프로젝트 디렉터리를 생성합니다. 여기서는 nodemailerProject라는 이름을 사용하겠습니다.

mkdir nodemailerProject

새로 만든 디렉터리로 이동한 뒤 아래 명령어를 실행합니다.

npm init

이 명령은 package.json 파일과 함께 프로젝트를 초기화합니다.

다음으로 Express를 설치합니다:

npm install express

진입점으로 지정한 파일(기본값은 index.js)을 열고 아래 코드를 붙여넣습니다:

const express = require('express')
const app = express()
const port = 3000


app.listen(port, () => {
  console.log(`nodemailerProject is listening at https://localhost:${port}`)
})

index.js

위 코드는 Express로 간단한 서버를 시작하는 데 필요한 최소한의 코드입니다. 아래 명령어를 실행해 정상적으로 동작하는지 확인할 수 있습니다:

node index.js

Nodemailer 설치하기

아래 명령어로 nodemailer를 설치합니다:

npm install nodemailer

Nodemailer의 API는 매우 직관적이며, 다음 세 단계만 거치면 됩니다:

Transporter 객체 생성
MailOptions 객체 생성
Transporter.sendMail 메서드 호출

Transporter 객체는 다음과 같이 생성합니다:

let transporter = nodemailer.createTransport({
      service: 'gmail',
      auth: {
        type: 'OAuth2',
        user: process.env.MAIL_USERNAME,
        pass: process.env.MAIL_PASSWORD,
        clientId: process.env.OAUTH_CLIENTID,
        clientSecret: process.env.OAUTH_CLIENT_SECRET,
        refreshToken: process.env.OAUTH_REFRESH_TOKEN
      }
    });

✋ 주의하세요. user와 pass 키는 본인의 Gmail 계정 자격 증명이지만, 나머지 세 개의 키(clientId, clientSecret, refreshToken)는 OAuth 설정을 마친 후에야 발급받을 수 있습니다.

앞서 언급했듯이 이 글에서는 Gmail을 사용해 메일을 보냅니다. 짐작하셨겠지만 Gmail은 계정과 관련된 메일에 대해 높은 수준의 보안 정책을 적용합니다.

이 장애물을 극복하는 방법은 여러 가지가 있으며, 여기서는 Google Cloud Platform에서 프로젝트를 생성하는 방식을 선택하겠습니다. Gmail이 요구하는 OAuth 보안 인증에 필요한 자격 증명을 얻으려면 이 과정이 필수입니다.

Gmail과 nodemailer를 함께 사용할 때의 복잡한 사항이 궁금하다면 구글의 공식 문서를 참고하세요.

이제부터는 코딩보다는 설정 작업이 많으니, 차분히 따라와 주세요.

Nodemailer로 Node.js 서버에서 이메일 보내기: Gmail OAuth2 설정까지 완벽 가이드

Photo by Daniel McCullough / Unsplash

Google Cloud Platform 설정하기

Google Cloud Platform 계정이 없다면 먼저 가입해야 합니다. 계정 준비가 끝났다면 화면 좌상단의 드롭다운 메뉴를 클릭해 새 프로젝트를 생성하세요.

'새 프로젝트(New Project)' 옵션을 선택합니다:

다음 창에서 프로젝트 이름을 입력해야 합니다. 원하는 이름을 지정하면 되지만, 여기서는 NodemailerProject라는 이름을 그대로 사용하겠습니다. 위치(location) 속성은 '조직 없음(No organization)'으로 두어도 괜찮습니다.

프로젝트 생성에는 몇 초 정도 걸리며, 완료되면 아래와 같은 화면을 볼 수 있습니다:

좌상단의 점선 세 개 아이콘을 클릭해 내비게이션 메뉴를 연 뒤 APIs 및 서비스(APIs & Services)를 선택합니다:

Nodemailer와 Gmail을 함께 사용하려면 OAuth2 인증 방식을 사용해야 합니다. OAuth에 익숙하지 않더라도 걱정하지 마세요. 인증을 위한 프로토콜이라는 것만 알아두면 충분하며, 더 깊이 이해하고 싶다면 관련 자료를 참고하시기 바랍니다.

먼저 OAuth 동의 화면(OAuth Consent Screen)을 구성해야 합니다:

G-Suite 회원이 아니라면 사용자 유형(User Type)은 External만 선택 가능합니다.

생성 버튼을 클릭하면 다음 화면에서 애플리케이션(우리의 서버) 정보를 입력해야 합니다:

'사용자 지원 이메일(User support email)'과 '개발자 연락처 정보(Developer contact information)' 필드에 본인의 이메일을 입력합니다. '저장 후 계속(Save and Continue)'을 클릭하면 범위(Scopes) 단계로 넘어갑니다. 이 단계는 우리에게 필요하지 않으므로 건너뛰고 테스트 사용자(Test Users) 단계로 이동합니다.

여기서 본인을 테스트 사용자로 추가한 뒤 저장하고 계속 진행합니다.

OAuth 설정 구성하기

이 단계에서는 Nodemailer에서 사용할 OAuth 자격 증명을 생성합니다. OAuth 동의 화면 탭 위에 있는 '사용자 인증 정보(Credentials)' 탭으로 이동하세요. Create Credentials라는 문구가 있는 플러스(➕) 버튼을 클릭하고 'OAuth 클라이언트 ID(OAuth Client ID)'를 선택합니다.

애플리케이션 유형(Application type) 드롭다운 메뉴에서 웹 애플리케이션(Web Application)을 선택합니다:

승인된 리디렉션 URI(Authorized Redirect URIs) 섹션에는 OAuth2 Playground(https://developers.google.com/oauthplayground)를 반드시 추가하세요. 이 글 앞부분에서 언급한 키 중 하나를 발급받을 때 이 도구를 사용하게 됩니다.

생성 버튼을 클릭하면 클라이언트 ID와 클라이언트 시크릿이 표시됩니다. 이 값들은 절대 외부에 노출해서는 안 되며, 어떤 형태로든 공개하지 마세요.

Photo by Power Lai / Unsplash

OAuth 리프레시 토큰 발급받기

Nodemailer의 transporter 객체에 사용할 리프레시 토큰(refresh token)을 받으려면 OAuth2 Playground로 이동해야 합니다. 앞 단계에서 바로 이 목적을 위해 해당 URI를 승인해 두었습니다.

1. 오른쪽 상단의 톱니바퀴 아이콘(OAuth2 Configuration)을 클릭하고 '자체 OAuth2 사용자 인증 정보 사용' 체크박스를 선택합니다:

2. 웹사이트 왼쪽에 서비스 목록이 보입니다. 아래로 스크롤해 Gmail API v1을 찾습니다.

3. Authorize APIs를 클릭합니다.

Gmail 계정 로그인 화면이 나타납니다. 테스트 사용자로 등록해 둔 계정을 선택하세요.

4. 다음 화면에서는 Google이 아직 이 애플리케이션을 검증하지 않았다는 안내가 표시됩니다. 검증을 신청하지 않았기 때문에 나타나는 것이므로 걱정하지 않아도 됩니다. 계속을 클릭합니다.

5. 다음 화면에서 프로젝트가 Gmail 계정과 상호작용할 수 있도록 권한을 부여하라는 요청이 표시됩니다. 허용합니다.

6. 완료되면 OAuth Playground로 돌아오며, 왼쪽 메뉴에 승인 코드(authorization code)가 표시된 것을 확인할 수 있습니다. Exchange authorization code for tokens라는 파란색 버튼을 클릭합니다.

이제 리프레시 토큰과 액세스 토큰 필드가 채워집니다.

서버 코드로 돌아가기

모든 설정이 끝났으니, 이제 애플리케이션으로 돌아가 발급받은 데이터를 transporter 생성 코드에 입력하겠습니다. 자격 증명을 안전하게 보관하려면 dotenv 패키지를 사용하는 것이 좋습니다. 생성한 .env 파일을 .gitignore에 추가하는 것도 잊지 마세요.

그러면 코드는 다음과 같습니다:

let transporter = nodemailer.createTransport({
      service: 'gmail',
      auth: {
        type: 'OAuth2',
        user: process.env.MAIL_USERNAME,
        pass: process.env.MAIL_PASSWORD,
        clientId: process.env.OAUTH_CLIENTID,
        clientSecret: process.env.OAUTH_CLIENT_SECRET,
        refreshToken: process.env.OAUTH_REFRESH_TOKEN
      }
    });

다음으로 mailOptions 객체를 생성합니다. 이 객체에는 이메일을 어디로 보낼지, 어떤 내용을 담을지에 대한 정보가 들어갑니다.

let mailOptions = {
      from: 'tomerpacific@gmail.com',
      to: 'tomerpacific@gmail.com',
      subject: 'Nodemailer Project',
      text: 'Hi from your nodemailer project'
    };

이 객체에는 더 많은 필드를 넣을 수 있고, 여러 수신자를 지정하는 것도 가능하지만 여기서는 다루지 않겠습니다.

마지막으로 sendMail 메서드를 사용합니다:

transporter.sendMail(mailOptions, function(err, data) {
      if (err) {
        console.log("Error " + err);
      } else {
        console.log("Email sent successfully");
      }
    });

애플리케이션을 실행하면 새 이메일이 받은 편지함에 도착한 것을 확인할 수 있습니다.

이 글은 Nodemailer를 활용해 만든 실제 프로젝트에서 영감을 받아 작성되었습니다. 위 과정을 따라 하면 여러분의 Node.js 서버에서도 안정적으로 이메일을 발송할 수 있습니다.