AI 에이전트에 이메일 연결하는 방법, 순서대로 정리

지금까지 메신저에 붙이고 전화까지 해봤는데, 이메일은 진짜 빠르지 않다. 메신저 앱을 켜야 하고 전화는 통화 요금이 붙는다. 이메일이 제일 손에 익은 채널이라 마지막으로 붙였다. 생각보다 설정이 짧다. (운영자 환경 측정 기준)

왜 IMAP/SMTP로 붙이는가

Hermes는 메신저 앱과 달리, 메일 서버에 직접 로그인해서 읽고 쓴다. 웹훅도 웹소켓도 없다. 새로운 메일함 폴더를 지켜보다가 새 메일이 들어오면 읽고, 답을 쓸 때 SMTP로 보낸다.

메일함(IMAP) → Hermes가 주기적으로 폴더 확인 → 새 메일 읽기
                                              ↓
                                        에이전트 처리
                                              ↓
                                    답장(SMTP로 발송)

이 구조는 장점이 있다. 서버에 공개 주소를 노출할 필요가 없다. 내 서버가 밖으로 나가는 것뿐이라 방화벽이나 터널 설정이 필요 없다. 그래서 웹훅이 필요한 라인·왓츠앱보다 오히려 설정이 짧다.

필요한 환경변수는 네 개다.

EMAIL_ADDRESS=bot@example.com
EMAIL_PASSWORD=앱 비밀번호
EMAIL_IMAP_HOST=imap.example.com
EMAIL_SMTP_HOST=smtp.example.com

IMAP와 SMTP 호스트가 다를 수 있다.imap은 읽기, smtp는 쓰기 전용이라 같은 도메인이어도 포트가 다른 게 보통이다. 예를 들어 Gmail은 imap.gmail.com과 smtp.gmail.com이고, 587 포트에 STARTTLS 쓴다.

1. 봇용 메일 주소 만들기

자기 주소에 에이전트를 붙이면 메일이 안 들어올 때마다 신경 쓰인다. 봇 전용 주소를 하나 만든다. 받는 역할만 하는 주소다.

agent-bot@example.com

꿀팁 1: 필터로 들어오는 메일을 따로 모은다

봇 주소를 만든 뒤에는 정规则的 주소로 들어오는 메일이 스팸함에 빠진다. 메일 서비스의 필터 규칙을 하나 만들어서 그 주소가 보낸 메일을 받은 편지함으로 돌려놓는다. 필터를 안 만들면 봇이 조용히 아무것도 안 한다.

조건: 수신자가 agent-bot@example.com
동작: 받은편지함으로 이동, 스팸 아님으로 표시

2. 일반 비밀번호 대신 앱 비밀번호 발급

이 단계가 제일 막힌다. 메일 서비스는 대부분 2단계 인증을 요구해서, 원래 비밀번호로 IMAP 로그인을 시도하면 실패한다. 이유를 알려주지 않고 "인증 실패"만 준다.

꿀팁 2: 앱 비밀번호를 미리 만들어둔다

메일 서비스 설정에서 앱 비밀번호를 하나 발급받아 쓴다. 보통 16자리 랜덤 문자열이고, 공백을 제거한 형태로 나온다.

주의점 1: 앱 비밀번호는 서버 비밀번호와 다르다

여기가 헷갈리기 쉽다. 앱 비밀번호를 발급하면 기존 비밀번호가 그대로 남는다. 서버에는 앱 비밀번호만 넣는다. 나중에 웹 로그인에서 앱 비밀번호로 로그인하려고 하면 실패한다. 앱 비밀번호는 앱 전용이다.

3. IMAP/SMTP 연결 확인

Hermes에 넣기 전에 파이썬으로 먼저 확인한다. 여기서 먼저 안 되면 왜 안 되는지 알 수 있다.

import imaplib
import smtplib

imap = imaplib.IMAP4_SSL("imap.example.com", 993)
imap.login("bot@example.com", "앱 비밀번호")
imap.select("INBOX")
print(imap.search(None, "UNSEEN")[1])
imap.logout()

smtp = smtplib.SMTP("smtp.example.com", 587)
smtp.starttls()
smtp.login("bot@example.com", "앱 비밀번호")
smtp.quit()

IMAP은 993 포트(암호화), SMTP는 587 포트(STARTTLS)를 쓴다. 25 포트는 평문이라 쓰지 않는다. 이 코드가 성공하면 메일 서버 쪽 설정은 끝난 거다.

주의점 2: 여기서 성공해도 Hermes에서 실패한다

연결 확인용 스크립트는 성공하는데 Hermes는 여전히 못 붙는 경우가 있다. Hermes는 폴더 목록을 미리 읽어 오는 구조라, 쓰기 권한이 없는 폴더를 보려고 하면 권한 오류로 죽는다. 아니면 봇 계정의 전용 폴더를 미리 만들어 놔야 한다.

꿀팁 3: 전용 폴더를 미리 만들어 둔다

봇 주소에 Hermes 같은 폴더를 하나 만들어 두고, 게이트웨이가 그 폴더만 보게 하면 다른 메일이 섞이지 않는다. 읽지 않은 메일이 쌓인 통을 나중에 한 번에 처리하기도 편해진다.

4. Hermes에 넣기

.env에 네 값을 넣고 게이트웨이를 띄운다.

hermes gateway start

꿀팁 4: 게이트웨이 설정 화면에서 넣어도 된다

직접 파일을 고치는 대신 hermes gateway setup의 채널 화면에서 email 항목을 골라 넣을 수 있다. 비밀번호 항목은 마스킹되서 화면에 안 드러나고, 라벨도 "Email password or app password"로 나온다. 나처럼 서버 설정 파일을 몰라도 된다.

주의점 3: 따옴표를 붙이지 않는다

EMAIL_PASSWORD="앱 비밀번호"

따옴표까지 비밀번호로 읽혀서 로그인이 실패한다. 앞선 텔레그램·디스코드 글에서 반복된 오류이며, 메일도 똑같다. 값은 있는 그대로 적는다.

5. 몇 가지를 더 해본 사람만 아는 것

꿀팁 5: 비실명 주소는 메일함에서 밟힌다

봇이 쏜 메일이 스팸으로 분류되면 답장이 안 돌아온다. 발신 주소를 사람 이름이 들어가게 만들고, 발신 IP가 호스팅两家 IP에서 나야 안 잘려버린다. 집 와이파이에서 테스트하다가 이상 없다고 하고 서버로 옮기면 잘리는 경우가 있다. 메일 서비스마다 기준이 다르니 발신 헤더를 유니코드 없이 영문만 쓰는 게 안전하다.

꿀팁 6: 답장을 모두 돌려보내면 메일함을 열어본다

봇이 자동 응답만 하면 상대방의 메일 클라이언트가 응답 감지 Unable 하고 노란 경고를 띄운다. 하지만 발신자만 볼 때는 크게 신경 쓰이지 않는다. 사람이 매번 보는 메일이 아니기 때문이다.

꿀팁 7: 처리 후 메일을 못 본 것으로 표시하는 게 관건이다

이게 없다면 게이트웨이가 같은 메일을 계속 처리한다. 같은 메일이 여러 번 답장으로 가면 엄청 곤란하다. 읽음 처리까지 한 줄이 중요한 이유다. 폴더를 먼저 만들고 확인하는 이유도 이것과 같다.

꿀팁 8: 로그를 남겨두면 이유가 보인다

IMAP은 에러가 조용하다. 메시지가 안 보이면 먼저 폴더를 봤다. 그 다음 허용 발신자 목록을 봤다. 마지막으로 로그에서 인증 실패를 찾는다. 순서대로 보면 금방 찾을 수 있다.

정리

1. 봇 전용 메일 주소 만들기
2. 앱 비밀번호 발급 (일반 비밀번호는 2단계 인증 때문에 안 됨)
3. 파이썬으로 IMAP/SMTP 연결 확인 (993 / 587 + STARTTLS)
4. 전용 폴더를 미리 만들어 두고 그 폴더만 감시
5. EMAIL_ADDRESS / EMAIL_PASSWORD / EMAIL_IMAP_HOST / EMAIL_SMTP_HOST 네 개만 .env에
6. 따옴표 없이, 비실명 아웃바운드로

정리하면 이번엔 웹훅도 터널도 없다. 앱 비밀번호만 있으면 30분 안에 붙는다. 앞선 글들(라인·왓츠앱)에서 반나절씩 날렸던 게 이 글에서는 없다. 메일은 구현이 제일 단순한 채널이다. 그만큼 사용하기에도 편하다.

메신저로 문자를 주고받는 게 결국 눈으로 읽는 거라면, 이메일은 문서로 남기는 거다. 에이전트 출력물을 메일함에 쌓아두면 나중에 검색이 된다. 그게 메일을 붙이는 진짜 이유였다.