Python에서 Gmail SMTP 사용하기

Python 프로그램에서 Gmail을 통해 메일을 발송하려면 Gmail 계정의 앱 비밀번호를 생성하고, Gmail SMTP 서버에 연결해야 합니다.

⚠️ 일반 Google 계정 비밀번호는 사용하지 않습니다.

---

목차

1. Gmail 계정 준비
2. 2단계 인증 활성화
3. 앱 비밀번호 메뉴 찾기
4. 앱 비밀번호 생성
5. 앱 비밀번호 보안 안내
6. Gmail SMTP 서버 정보
7. Python에서 메일 발송하기
8. 인증정보 소스 코드 분리
9. 네트워크 및 방화벽 확인
10. 메일 발송 테스트 순서
11. 자주 발생하는 오류
12. 앱 비밀번호 관리
13. 최종 체크리스트

---

1. Gmail 계정 준비

메일 발송에 사용할 Gmail 계정을 준비합니다.

예:

example@gmail.com

SMTP 로그인 시 이 Gmail 주소가 사용자 이름으로 사용됩니다.

---

2. Google 계정의 2단계 인증 활성화

앱 비밀번호를 생성하려면 먼저 Google 계정의 2단계 인증이 활성화되어 있어야 합니다.

Google 계정 관리 화면에서 다음 순서로 이동합니다.

Google 계정
→ 보안 및 로그인
→ 2단계 인증

2단계 인증이 꺼져 있다면 안내에 따라 활성화합니다. 2단계 인증 방법으로는 다음과 같은 방식이 사용될 수 있습니다.

• Google 메시지
• 휴대전화 인증
• OTP 인증 앱
• 패스키
• 보안 키

2단계 인증이 이미 활성화되어 있다면 다음 단계로 이동합니다.

---

3. 앱 비밀번호 메뉴 찾기

Google 계정 화면에서 앱 비밀번호 메뉴가 바로 보이지 않을 수 있습니다.

이 경우 Google 계정 상단의 검색창에 다음과 같이 입력합니다.

앱 비밀번호

검색 결과에서 앱 비밀번호를 선택합니다. 또는 Google 계정의 앱 비밀번호 페이지로 직접 이동할 수도 있습니다.

https://myaccount.google.com/apppasswords

앱 비밀번호 메뉴가 표시되지 않는 경우에는 다음 사항을 확인합니다.

• Google 계정의 2단계 인증이 활성화되어 있는지
• 회사 또는 학교의 Google Workspace 계정인지
• 조직 관리자가 앱 비밀번호 사용을 차단했는지
• Google 고급 보호 프로그램을 사용하고 있는지
• 보안 정책상 앱 비밀번호 생성이 제한된 계정인지

개인 Gmail 계정이고 2단계 인증이 활성화되어 있다면 일반적으로 앱 비밀번호를 생성할 수 있습니다.

---

4. 앱 비밀번호 생성

앱 비밀번호 화면에서 사용할 프로그램을 구분할 수 있는 이름을 입력합니다.

예:

Python SMTP

또는:

Mail Sender

이 이름은 앱 비밀번호의 용도를 구분하기 위한 이름일 뿐이며, SMTP 설정값에는 사용하지 않습니다.

이름을 입력한 뒤 만들기를 누르면 16자리 앱 비밀번호가 생성됩니다.

예:

abcd efgh ijkl mnop

앱 비밀번호는 생성될 때 한 번만 표시됩니다.

SMTP 프로그램에는 공백을 제외하거나 포함한 형태로 입력할 수 있지만, 일반적으로 다음처럼 공백 없이 저장합니다.

abcdefghijklmnop

일반 Google 계정 비밀번호가 아니라 반드시 생성된 앱 비밀번호를 사용해야 합니다.

---

앱 비밀번호의 보안 안내

앱 비밀번호 화면에는 다음과 같은 경고 문구가 표시될 수 있습니다.

앱 비밀번호는 최신 보안 표준을 사용하는 앱 및 서비스보다 보안 수준이 낮습니다.

이 문구는 앱 비밀번호 자체가 위험하거나 계정에 문제가 있다는 뜻은 아닙니다.

앱 비밀번호는 웹브라우저에서 사용하는 다음과 같은 최신 로그인 방식을 사용할 수 없는 프로그램을 위한 기능입니다.

• 패스키
• 생체 인증
• Google 로그인 화면
• 2단계 인증 확인
• OAuth 2.0

SMTP 프로그램은 보통 사용자 이름과 비밀번호 방식으로 로그인하기 때문에, Google이 SMTP용으로 별도의 앱 비밀번호를 제공하는 것입니다.

앱 비밀번호의 장점

• 실제 Google 계정 비밀번호를 프로그램에 입력하지 않아도 됩니다.
• 특정 프로그램에만 별도의 비밀번호를 사용할 수 있습니다.
• 비밀번호가 노출되면 해당 앱 비밀번호만 삭제할 수 있습니다.
• Google 계정의 기본 비밀번호를 변경할 필요가 없습니다.
• 앱별로 서로 다른 비밀번호를 만들 수 있습니다.

예를 들어 Python SMTP용 앱 비밀번호가 노출되었다면 Google 계정의 앱 비밀번호 화면에서 해당 비밀번호를 삭제하면 됩니다.

다만 앱 비밀번호를 가진 사람은 해당 계정의 SMTP 기능을 이용할 수 있으므로 일반 비밀번호처럼 안전하게 관리해야 합니다.

운영 서비스나 보안 요구 수준이 높은 시스템에서는 앱 비밀번호보다 OAuth 2.0 인증 방식이 더 적합할 수 있습니다. 교육용 프로그램이나 개인 자동화에서는 앱 비밀번호 방식이 구현하기 쉽습니다.

---

5. Gmail SMTP 서버 정보

STARTTLS 방식

항목 설정값

SMTP 서버	smtp.gmail.com
포트	587
인증	사용
STARTTLS	사용
사용자 이름	Gmail 주소
비밀번호	앱 비밀번호

일반적으로 포트 587과 STARTTLS 방식을 권장합니다.

SSL 방식

항목 설정값

SMTP 서버	smtp.gmail.com
포트	465
SSL	사용
사용자 이름	Gmail 주소
비밀번호	앱 비밀번호

587과 465를 혼합해서 설정하면 SSL 오류가 발생할 수 있으므로 한 가지 방식만 선택해야 합니다.

---

6. Python에서 메일 발송하기

Python의 기본 라이브러리인 smtplib와 email을 사용하면 별도의 패키지 설치 없이 메일을 발송할 수 있습니다.

import smtplib
from email.message import EmailMessage

SMTP_SERVER = "smtp.gmail.com"
SMTP_PORT = 587

GMAIL_USERNAME = "example@gmail.com"
GMAIL_APP_PASSWORD = "abcdefghijklmnop"

message = EmailMessage()
message["Subject"] = "Gmail SMTP 발송 테스트"
message["From"] = GMAIL_USERNAME
message["To"] = "receiver@example.com"

message.set_content("Python에서 발송한 테스트 메일입니다.")

try:
    with smtplib.SMTP(SMTP_SERVER, SMTP_PORT) as smtp:
        smtp.starttls()
        smtp.login(GMAIL_USERNAME, GMAIL_APP_PASSWORD)
        smtp.send_message(message)

    print("메일 발송이 완료되었습니다.")

except smtplib.SMTPAuthenticationError:
    print("SMTP 인증에 실패했습니다. Gmail 주소와 앱 비밀번호를 확인하세요.")

except smtplib.SMTPException as error:
    print(f"메일 발송 중 SMTP 오류가 발생했습니다: {error}")

except Exception as error:
    print(f"메일 발송 중 오류가 발생했습니다: {error}")

SMTP 로그인 정보는 다음과 같이 사용됩니다.

사용자 이름 = Gmail 전체 주소
비밀번호 = 16자리 앱 비밀번호

일반 Google 계정 비밀번호는 입력하지 않습니다.

---

7. 인증정보를 소스 코드에서 분리하기

교육 초기에는 소스 코드에 값을 직접 입력할 수 있지만, 실제 프로젝트에서는 앱 비밀번호를 소스에 작성하지 않는 것이 좋습니다.

환경변수 설정 예시

GMAIL_USERNAME=example@gmail.com
GMAIL_APP_PASSWORD=abcdefghijklmnop

Python에서는 다음과 같이 읽습니다.

import os

GMAIL_USERNAME = os.getenv("GMAIL_USERNAME")
GMAIL_APP_PASSWORD = os.getenv("GMAIL_APP_PASSWORD")

if not GMAIL_USERNAME or not GMAIL_APP_PASSWORD:
    raise ValueError("Gmail SMTP 인증정보가 설정되지 않았습니다.")

.env 파일을 사용할 경우에는 해당 파일을 GitHub에 올리지 않아야 합니다. .gitignore 파일에 다음 내용을 추가합니다.

.env

---

8. 네트워크 및 방화벽 확인

메일을 발송하는 PC나 서버에서 다음 주소와 포트에 접속할 수 있어야 합니다.

smtp.gmail.com:587

또는 SSL 방식을 사용한다면:

smtp.gmail.com:465

회사 네트워크나 서버 환경에서는 보안 정책으로 외부 SMTP 포트가 차단될 수 있습니다.

인증정보가 정확한데도 연결 시간 초과가 발생한다면 다음 사항을 확인합니다.

• 인터넷 연결 상태
• 회사 방화벽 정책
• 서버의 아웃바운드 포트 제한
• 보안 프로그램의 SMTP 차단 여부
• DNS에서 smtp.gmail.com을 조회할 수 있는지

---

9. 메일 발송 테스트 순서

처음부터 여러 수신자에게 발송하지 말고 다음 순서로 테스트하는 것이 좋습니다.

1. 발신 Gmail → 동일한 Gmail 계정
2. 발신 Gmail → 다른 Gmail 계정
3. 발신 Gmail → Outlook 또는 다른 외부 메일
4. 발신 Gmail → 회사 메일

메일이 도착하지 않으면 받은편지함뿐 아니라 스팸함도 확인합니다.

---

10. 자주 발생하는 오류

인증 실패

SMTPAuthenticationError
Username and Password not accepted

확인할 내용:

• 일반 Google 비밀번호를 입력하지 않았는지
• 16자리 앱 비밀번호를 사용했는지
• Gmail 주소 전체를 사용자 이름으로 입력했는지
• 앱 비밀번호를 복사하면서 일부 문자가 빠지지 않았는지
• 앱 비밀번호를 삭제한 적이 없는지

연결 시간 초과

Connection timed out

확인할 내용:

• 인터넷 연결
• 방화벽
• smtp.gmail.com 접속 가능 여부
• 포트 587 또는 465 허용 여부

SSL 또는 TLS 오류

SSL error
TLS error
Wrong version number

다음 설정 조합을 확인합니다.

포트 587 → smtplib.SMTP() + starttls()
포트 465 → smtplib.SMTP_SSL()

포트 465에서 starttls()를 사용하거나, 포트 587에서 처음부터 SMTP_SSL()을 사용하면 오류가 발생할 수 있습니다.

---

11. 앱 비밀번호 관리

앱 비밀번호는 Google 계정의 앱 비밀번호 화면에서 관리할 수 있습니다.

다음과 같은 경우에는 기존 앱 비밀번호를 삭제하고 새로 만드는 것이 좋습니다.

• 비밀번호가 외부에 노출된 경우
• GitHub에 실수로 등록한 경우
• 사용하지 않는 프로그램의 비밀번호인 경우
• 어느 프로그램에서 사용하는 비밀번호인지 알 수 없는 경우
• 프로그램이나 서버를 폐기한 경우

앱 비밀번호를 삭제하면 해당 비밀번호를 사용하던 SMTP 프로그램은 더 이상 로그인할 수 없습니다.

---

최종 체크리스트

• [ ] Gmail 계정을 준비했다.
• [ ] Google 계정에서 2단계 인증을 활성화했다.
• [ ] 메뉴가 보이지 않을 경우 검색창에서 앱 비밀번호를 검색했다.
• [ ] 앱 비밀번호를 생성했다.
• [ ] SMTP 사용자 이름에 Gmail 전체 주소를 입력했다.
• [ ] 일반 계정 비밀번호 대신 앱 비밀번호를 입력했다.
• [ ] SMTP 서버를 smtp.gmail.com으로 설정했다.
• [ ] 포트 587과 STARTTLS를 사용했다.
• [ ] 인증정보를 환경변수로 관리했다.
• [ ] .env 파일을 Git 저장소에서 제외했다.
• [ ] 방화벽에서 SMTP 접속이 가능한지 확인했다.
• [ ] 테스트 메일 발송을 완료했다.
• [ ] 노출된 앱 비밀번호는 즉시 삭제하고 다시 생성했다.

Python_Gmail_SMTP_가이드.md.pdf

0.40MB