고정 헤더 영역
상세 컨텐츠
본문
PHP(Laravel 등)나 Python(FastAPI 등) 애플리케이션에서 Gmail SMTP 서버를 이용해 이메일을 보내는 방법을 정리했습니다. 특히 Gmail 계정에 2단계 인증(2-Step Verification)을 적용하지 않는 대신 앱 비밀번호(App Password)를 생성하여 SMTP 인증에 사용하는 절차를 중점적으로 다룹니다. 각 단계별 설정값과 코드 예시, 발생 가능한 보안 이슈 및 2025년 기준 Gmail 정책 정보까지 포함하였으니 순서대로 따라해보세요.
1. Gmail SMTP 서버 설정값
Gmail을 SMTP 발송 서버로 사용할 때 필요한 기본 설정값은 다음과 같습니다 (How To Set Up Your Gmail SMTP Settings (2025 Guide)) (How To Set Up Your Gmail SMTP Settings (2025 Guide)):
- SMTP 호스트: smtp.gmail.com (Gmail의 SMTP 서버 주소) (How To Set Up Your Gmail SMTP Settings (2025 Guide))
- SMTP 포트: TLS 연결 시 587 포트, SSL 연결 시 465 포트 사용 (How To Set Up Your Gmail SMTP Settings (2025 Guide))
- 암호화 방식: TLS 또는 SSL (서버 연결에 SSL/TLS 보안 필수) (How To Set Up Your Gmail SMTP Settings (2025 Guide))
- 인증 방식: SMTP 인증 필요 – Gmail 계정 로그인 자격 증명 요구됨 (사용자명과 앱 비밀번호) (How To Set Up Your Gmail SMTP Settings (2025 Guide))
- SMTP 사용자명: Gmail 로그인 이메일 주소 전체 (예: yourname@gmail.com) (How To Set Up Your Gmail SMTP Settings (2025 Guide))
- SMTP 비밀번호: Gmail 계정의 앱 비밀번호 (또는 2FA 미사용 시 계정 비밀번호 – 하지만 2025년 현재는 앱 비밀번호 사용 권장)
위 설정에서 포트(port)는 보안 방식에 따라 선택합니다. 일반적으로 포트 587 + STARTTLS(TLS)을 많이 사용하며, 이때 STARTTLS 명령으로 암호화된 통신을 시작합니다. 포트 465는 연결 시 바로 SSL 암호화(Implicit SSL)를 사용하는 방법으로, Laravel이나 메일 라이브러리 설정 시 Encryption(암호화) 옵션을 "ssl"로 지정해 사용합니다. 두 방식 모두 Gmail에서 지원하며 동일한 SMTP 서버 주소를 사용합니다 (IMAP, POP, and SMTP | Gmail | Google for Developers). 또한 Gmail SMTP는 반드시 SSL/TLS 보안 연결과 인증을 요구하므로, 보안 설정 없이 보내면 Gmail 측에서 연결을 거부합니다.
2. Gmail 계정에서 앱 비밀번호 생성 및 사용 방법
앱 비밀번호(App Password)는 Gmail 계정의 기본 비밀번호 대신 특정 앱이나 기기에서 사용할 수 있도록 발급하는 16자리 전용 비밀번호입니다. Gmail은 보안 강화를 위해 2단계 인증이 활성화된 계정에서만 앱 비밀번호를 생성할 수 있도록 제한하고 있습니다 (How to generate app password is a 16-digit passcode that gives a less secure app). 따라서 2단계 인증을 활성화한 후 앱 비밀번호를 발급받아 SMTP용 비밀번호로 사용해야 합니다. (2025년 현재 2단계 인증을 사용하지 않는 계정은 앱 비밀번호 발급이 불가하며, 과거에 존재하던 '보안 수준이 낮은 앱의 액세스 허용' 옵션은 2022년부터 단계적으로 폐지되었습니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024).)
앱 비밀번호 생성 절차:
- Google 계정 보안 설정 진입: Gmail에 로그인한 상태에서 Google 계정 관리 페이지로 이동하고, 좌측 메뉴에서 "보안"을 선택합니다.
- 2단계 인증 활성화: "Google에 로그인" 섹션에서 "2단계 인증"을 설정합니다. 안내에 따라 휴대전화 등 인증 수단을 추가하여 2단계 인증을 켭니다 (이미 활성화되어 있다면 다음 단계 진행) (Gmail Is Disabling Less Secure Apps on September 30, 2024).
- 앱 비밀번호 메뉴로 이동: 2단계 인증 설정 페이지 하단에 "앱 비밀번호" 옵션이 나타납니다. 이를 클릭하면 Google 로그인 비밀번호를 다시 한 번 물을 수 있습니다 (How to generate app password is a 16-digit passcode that gives a less secure app).
- 앱 비밀번호 생성: 앱 비밀번호 발급 화면에서 앱을 선택하고 기기 종류를 선택하도록 되어 있습니다. 여기서 사용 용도에 맞게 값을 선택하거나 "기타 (사용자 지정 이름)"으로 설정합니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 예를 들어 “Laravel SMTP” 혹은 “FastAPI Email” 등 식별하기 쉬운 이름으로 지정합니다.
- 16자리 비밀번호 발급: 생성(Generate) 버튼을 누르면 노란색 박스 등에 16자리 영어 소문자 비밀번호가 표시됩니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 이 값이 앱 비밀번호이며, 향후 SMTP 비밀번호로 이 값을 사용합니다. (공백 없이 4자리씩 나눠보여줄 뿐이므로 그대로 붙여 쓰면 됩니다.)
- 앱 비밀번호 사용: 발급된 앱 비밀번호를 복사하여 애플리케이션의 SMTP 설정에 입력합니다. Gmail SMTP 서버에 연결할 때 이 비밀번호를 제공하면, Google이 해당 앱 접근을 승인하여 메일 발송이 가능합니다.
참고: 앱 비밀번호는 2단계 인증을 켠 계정에서만 발급되며, 만약 2단계 인증을 끄거나 Google 계정 기본 비밀번호를 변경하면 기존에 발급된 모든 앱 비밀번호는 더 이상 유효하지 않게 됩니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 또한 2단계 인증을 사용하지 않는 계정의 경우 과거에는 보안 수준이 낮은 앱 허용 설정으로 일반 비밀번호를 사용하는 방법이 있었으나, Google은 2022년 5월 30일부터 일반 비밀번호를 사용하는 SMTP 접속을 전면 차단하였습니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 그러므로 현재는 반드시 2단계 인증 + 앱 비밀번호 방식으로 설정해야 합니다.
3. Laravel의 .env 및 config/mail.php 설정 예시
Laravel에서 Gmail SMTP를 사용하려면 메일 환경설정을 .env 파일과 config/mail.php 파일에 지정해야 합니다. 우선 프로젝트 루트의 .env 파일에 SMTP 정보를 다음과 같이 추가하거나 수정합니다:
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=465
MAIL_USERNAME=yourgmail@gmail.com
MAIL_PASSWORD=발급받은앱비밀번호16자리
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=yourgmail@gmail.com
MAIL_FROM_NAME="${APP_NAME}"
([Send Email in Laravel with Gmail SMTP: Code Snippets [2025]](https://mailtrap.io/blog/laravel-send-email-gmail/#:~:text=MAIL_MAILER%3Dsmtp%20MAIL_HOST%3Dsmtp.gmail.com%20MAIL_PORT%3D465%20MAIL_USERNAME%3Dmygoogle%40gmail.com%20MAIL_PASSWORD%3D,APP_NAME))
위 설정에서 `MAIL_USERNAME`에는 Gmail 이메일 주소, `MAIL_PASSWORD`에는 앞서 생성한 앱 비밀번호를 입력합니다. `MAIL_ENCRYPTION`은 사용 포트에 맞춰 `"tls"` 또는 `"ssl"`로 설정할 수 있습니다. 예를 들어 포트로 587을 사용한다면 `MAIL_PORT=587`과 `MAIL_ENCRYPTION=tls`로, 포트 465를 사용한다면 `MAIL_ENCRYPTION=ssl`로 변경하는 식입니다. (`tls`는 STARTTLS 방식, `ssl`은 SSL 방식 연결을 의미합니다.)
Laravel 8 이상 버전의 `config/mail.php` 파일을 열어보면, 기본적으로 `.env`의 설정을 불러오도록 되어 있습니다. 예를 들면 `config/mail.php` 내에 아래와 같은 설정이 포함되어 있습니다:
'default' => env('MAIL_MAILER', 'smtp'),
'mailers' => [
'smtp' => [
'transport' => 'smtp',
'host' => env('MAIL_HOST', 'smtp.mailtrap.io'),
'port' => env('MAIL_PORT', 587),
'encryption' => env('MAIL_ENCRYPTION', 'tls'),
'username' => env('MAIL_USERNAME'),
'password' => env('MAIL_PASSWORD'),
// ... (생략)
],
// ... 다른 메일러 설정 생략
],
'from' => [
'address' => env('MAIL_FROM_ADDRESS', '[email protected]'),
'name' => env('MAIL_FROM_NAME', 'Example'),
],
따라서 .env 파일에 올바르게 값을 넣었다면 별도로 mail.php를 수정하지 않아도 기본 메일러로 Gmail SMTP를 사용하게 됩니다. (MAIL_MAILER가 smtp로 지정된 경우) 만약 Laravel 프로젝트에서 여러 메일러를 병행 사용한다면 mail.php에 필요한 mailer 설정을 추가하고 MAIL_MAILER값으로 해당 mailer의 키를 지정하면 됩니다.
이제 Laravel에서 메일을 전송할 때는 일반적인 Mail API를 그대로 사용하면 됩니다. 예를 들어 Mailable 클래스를 생성하여 다음과 같이 메일을 보내면 .env에 설정된 Gmail SMTP 계정을 통해 실제 이메일이 발송됩니다:
Mail::to($userEmail)->send(new MyTestEmail($content));
Laravel이 내부적으로 위 설정한 Gmail SMTP (smtp.gmail.com)로 연결하여 메일을 보냅니다.
4. Python (FastAPI) 환경에서 Gmail SMTP 연동 예시
백엔드가 Python인 경우에도 Gmail SMTP로 메일을 보낼 수 있습니다. Python의 내장 smtplib 모듈이나 편의 라이브러리인 yagmail, 또는 FastAPI 전용 메일 라이브러리인 fastapi-mail 등을 사용하면 됩니다. Gmail SMTP 설정값(호스트, 포트, 계정정보)은 앞서와 동일하며, 앱 비밀번호를 사용하는 것이 핵심입니다.
4-1. smtplib 모듈을 사용한 SMTP 전송 예시
Python 표준 라이브러리의 smtplib과 email 모듈을 사용하여 Gmail SMTP 서버로 메일을 보내는 간단한 예시는 다음과 같습니다:
import smtplib
from email.mime.text import MIMEText
# Gmail SMTP 서버 정보
smtp_server = "smtp.gmail.com"
smtp_port = 587 # TLS 포트
username = "yourgmail@gmail.com"
password = "발급받은앱비밀번호16자리"
# 이메일 메시지 구성
msg = MIMEText("메일 본문 내용입니다.")
msg['Subject'] = "테스트 메일 제목"
msg['From'] = username
msg['To'] = "recipient@example.com"
# SMTP 서버에 연결하여 메일 보내기
server = smtplib.SMTP(smtp_server, smtp_port)
server.starttls() # TLS 보안 연결로 업그레이드
server.login(username, password) # Gmail 계정 로그인 (앱 비밀번호 사용)
server.sendmail(msg['From'], msg['To'], msg.as_string()) # 메일 전송
server.quit()
위 코드에서는 포트 587로 연결한 뒤 starttls()를 호출해 TLS 암호화 채널로 전환하고, Gmail 계정 자격증명(이메일 주소, 앱 비밀번호)으로 로그인합니다. 그런 다음 sendmail로 메일을 발송합니다. 앱 비밀번호를 사용하므로 추가적인 2단계 인증 과정 없이도 Gmail SMTP서버가 로그인을 허용합니다.
4-2. yagmail 라이브러리를 사용한 간소화 예시
yagmail은 Gmail 전송에 특화된 Python 패키지로, OAuth2 설정이나 SMTP 설정을 쉽게 처리해줍니다. 앱 비밀번호를 이용해 간편하게 보낼 수도 있습니다. 예를 들어 pip install yagmail로 설치한 후 다음처럼 사용할 수 있습니다:
import yagmail
yag = yagmail.SMTP(user="yourgmail@gmail.com", password="발급받은앱비밀번호16자리")
yag.send(to="recipient@example.com", subject="테스트 메일", contents="본문 내용")
yagmail.SMTP 객체 생성 시 Gmail 계정과 앱 비밀번호를 넣으면 바로 인증이 이루어지며, send() 메소드로 수신자, 제목, 내용을 지정해 이메일을 발송할 수 있습니다.
4-3. FastAPI에서 fastapi-mail을 사용한 예시
FastAPI 어플리케이션에서 비동기로 이메일을 보내려면 fastapi-mail 라이브러리를 사용할 수 있습니다. fastapi-mail의 ConnectionConfig에 Gmail SMTP 정보를 설정한 후, FastMail 클래스를 통해 메일을 보낼 수 있습니다. 예시는 다음과 같습니다 (환경에 맞게 값 설정):
from fastapi_mail import FastMail, MessageSchema, ConnectionConfig
conf = ConnectionConfig(
MAIL_USERNAME = "yourgmail@gmail.com",
MAIL_PASSWORD = "발급받은앱비밀번호16자리",
MAIL_SERVER = "smtp.gmail.com",
MAIL_PORT = 587,
MAIL_TLS = True,
MAIL_SSL = False,
MAIL_FROM = "yourgmail@gmail.com",
MAIL_FROM_NAME = "My App"
)
message = MessageSchema(
subject="안녕하세요",
recipients=["recipient@example.com"], # 수신자 리스트
body="FastAPI를 통해 보내는 테스트 이메일입니다.",
subtype="plain"
)
fm = FastMail(conf)
await fm.send_message(message)
위 설정에서 MAIL_TLS=True, MAIL_SSL=False와 포트 587 조합은 Gmail TLS 연결을 의미합니다 (Sending Email using FastAPI Framework in Python - GeeksforGeeks). MAIL_USERNAME과 MAIL_PASSWORD에 Gmail 주소와 앱 비밀번호를 넣으면 FastMail 객체가 내부적으로 Gmail SMTP에 인증을 수행합니다. 그런 다음 send_message를 통해 비동기적으로 메일을 발송합니다. (FastAPI의 경우 send_message는 코루틴이므로 호출 시 await가 필요합니다.)
5. Gmail SMTP 사용 시 발생 가능한 보안 경고 및 차단 이슈 해결
Gmail SMTP를 사용하여 메일을 보내는 초기 설정 과정에서 몇 가지 보안 경고나 로그인 차단 이슈가 발생할 수 있습니다. 이에 대한 원인과 해결 방법을 정리합니다:
- “로그인 시도가 차단됨” 경고: 2단계 인증이 없는 계정에서 SMTP로 접속을 시도하거나, 새로운 애플리케이션/IP에서 Gmail에 접속하면 Google이 의심스러운 로그인 시도로 간주하여 차단할 수 있습니다. 이때 Gmail 계정의 이메일로 “보안 경고: 새 기기에서 로그인 시도” 등의 알림이 오기도 합니다. 해결: Gmail 웹사이트나 Google 계정 보안 페이지에 로그인하여 해당 시도가 본인이 한 것임을 확인해주거나, 앱 비밀번호를 사용하여 접속하면 이러한 경고 없이 인증이 가능합니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 앱 비밀번호로 로그인하면 Google 측에서 해당 접속을 사용자가 허용한 것으로 간주합니다.
- SMTP 인증 오류 (534, 535 오류): 앱 비밀번호를 사용하지 않거나 Gmail 보안 설정이 맞지 않으면 SMTP 인증에서 오류 코드 534-5.7.9 또는 535-5.7.8 Username and Password not accepted 등의 에러가 발생할 수 있습니다 (php - laravel 9 smtp gmail .env setup - Stack Overflow) (What is the DisplayUnlockCaptcha Replacement? Random Alias Issues. : r/GMail). 해결: 우선 Gmail 계정에 2단계 인증 및 앱 비밀번호가 설정되어 있는지 확인합니다. 이미 앱 비밀번호를 사용 중인데도 오류가 난다면, 한 번 DisplayUnlockCaptcha 과정을 시도해볼 수 있습니다. 브라우저에서 accounts.google.com/DisplayUnlockCaptcha 링크에 접속하여 Google 계정으로 캡차(CAPTCHA)를 완료하면, 일시적으로 해당 기기나 앱의 접근이 허용되어 인증이 풀릴 수 있습니다 (How to Send Email Using Python FastAPI | by Agus Richard | Nerd For Tech | Medium) (What is the DisplayUnlockCaptcha Replacement? Random Alias Issues. : r/GMail). (과거에는 이 방법으로 SMTP 접속 문제를 해결하곤 했으나, 2023년 이후 Google이 이 기능을 중단했을 수 있다는 보고도 있으므로 참고만 하세요.)
- “보안 수준이 낮은 앱” 차단: 앞서 언급했듯, 2022년 이후 Google은 보안 수준이 낮은 로그인(예: 2단계 인증이 없는 계정의 기본 비밀번호로 SMTP 로그인)을 차단합니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 만약 앱 비밀번호 대신 실수로 계정 기본 비밀번호를 사용했다면 Gmail에서 차단하여 “계정에 안전하지 않은 앱이 접근하려 함” 경고를 보냅니다. 해결: 반드시 앱 비밀번호 사용 또는 OAuth2 방식을 사용하고, 계정 설정에서 "보안 수준이 낮은 앱 허용" 같은 옵션은 더 이상 지원되지 않음을 인지해야 합니다.
- 기타: Gmail SMTP를 처음 사용하는 경우 Gmail 계정의 IMAP 액세스가 꺼져 있으면 문제를 겪을 수 있다는 조언도 있습니다 (How to Send Email Using Python FastAPI | by Agus Richard | Nerd For Tech | Medium). Gmail 설정에서 IMAP이 활성화되어 있는지 확인해보세요 (SMTP 발송과 직접 연관은 없지만 메일 클라이언트 설정상 IMAP/SMTP를 모두 사용하는 경우 영향). 그리고 Gmail SMTP에는 발송 빈도/양 제한이 있으므로(하루 500건 이상 보내면 계정이 일시적으로 전송이 제한됨), 너무 많은 메일을 한꺼번에 보내지 않도록 주의해야 합니다.
요약하면, Google 계정 보안 설정을 올바르게 준비(2FA 및 앱 비밀번호 사용) 하고, 처음 연결 시 계정 측의 확인 절차(보안 알림 확인 또는 Unlock Captcha)를 거치면 Gmail SMTP로 무리없이 메일을 보낼 수 있습니다.
6. 2025년 기준 Gmail의 SMTP 정책 및 제한 사항
2025년 현재 Gmail의 SMTP 사용 정책은 보안을 위해 몇 가지 제한을 두고 있습니다:
- 2단계 인증 없는 SMTP 로그인 불가: 일반적인 Gmail 계정은 더 이상 기본 아이디/비밀번호만으로 SMTP 로그인을 허용하지 않습니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 2022년 5월 30일부터 Google은 사용자 이름과 비밀번호만 사용하는 타사 앱의 접속(이른바 Less Secure Apps 방식)을 차단했으며, 2024년 9월에는 GSuite/Workspace 계정에 대해서도 이 정책을 완전히 적용했습니다 (Gmail Is Disabling Less Secure Apps on September 30, 2024). 따라서 SMTP를 통한 Gmail 발송은 2단계 인증 + 앱 비밀번호 또는 OAuth2를 통한 인증 방식만 허용됩니다. OAuth2를 사용할 경우 Gmail API를 이용하거나 SMTP의 XOAUTH2 메커니즘을 통해 토큰으로 인증해야 하는데, 일반적인 웹앱에서는 앱 비밀번호 방식이 더 간편합니다.
- SMTP 발송 허용 여부: Gmail은 개인 사용자에게 SMTP로 메일 전송하는 기능 자체는 계속 지원하고 있습니다. 즉, 앱 비밀번호를 통한 SMTP 접속이나 OAuth2 인증을 통한 SMTP는 2025년에도 허용됩니다. 다만 Google은 대량 메일 발송이나 스팸 남용을 방지하기 위해 일정량 이상의 이메일을 보내면 계정에 일시적 제한을 걸 수 있습니다. 또한 SMTP를 장기간 대량으로 사용할 경우 Google이 계정 활동을 모니터링하여 비정상적인 발송 패턴이라고 판단되면 CAPTCHA 인증을 요구하거나 계정 보호 조치를 취할 수 있습니다.
- 일일 발송량 제한: Gmail SMTP를 사용할 때 하루에 보낼 수 있는 이메일 수에 제한이 있습니다. 일반 무료 Gmail 계정의 경우 대략 하루 500개의 이메일(또는 수신자)까지 보낼 수 있으며 (Understanding Gmail's Email Sending Limits [2025]), Google Workspace(유료 비즈니스 계정)의 경우 최대 하루 2,000개까지 허용됩니다 (Understanding Gmail's Email Sending Limits [2025]). 이 한도를 초과하면 해당 계정으로는 24시간 정도 이메일을 보낼 수 없게 되니, 대량 메일 발송이 필요한 경우 Gmail을 SMTP로 사용하지 않는 것이 좋습니다.
- SMTP 메시지 크기 및 빈도 제한: 한 통의 이메일 메시지 크기는 첨부파일 포함 약 25MB로 제한됩니다. 그리고 SMTP 세션당 보내는 메시지 수나 병행 연결 수에도 제한이 있습니다. 예를 들어 SMTP를 통해 한 번에 너무 많은 수신자에게 메일을 보내면 일부가 차단될 수 있습니다. 일반적인 개인 용도 사용에서는 크게 문제가 되지 않지만, 자동화된 대량 발송에는 적합하지 않습니다. Gmail 이용 약관상 자동화된 스크립트를 통한 대량 메일 발송은 금지되어 있으므로, 대량 메일링은 SendGrid, Mailgun 같은 전문 이메일 API 서비스를 사용하거나 Gmail API를 이용하는 것이 권장됩니다.
정리하면, Gmail SMTP를 통한 메일 전송은 2025년에도 가능하지만 보안상 App Password 또는 OAuth2 인증이 필수이며, 일일 전송량(무료 계정 500통) 등의 제한이 있습니다. Gmail을 SMTP로 활용할 때는 이 제한 사항을 염두에 두고, 소량의 알림이나 문의메일 전송 등에 적절히 사용하는 것이 바람직합니다.
반응형
