Anil-matcha/open-agent-email

Open Agent Email – AI 에이전트를 위한 이메일 받은 편지함 (셀프 호스팅)

개요

• 각 AI 에이전트에게 고유한 실제 이메일 주소와 메일함을 제공하는 셀프 호스팅 서비스입니다. 수신 SMTP를 처리하여 메시지를 저장하고, 에이전트가 이메일을 읽고, 답장하고, 전달하고, 예약하거나, 위험한 메일을 보내기 전 사람의 승인을 요청할 수 있도록 합니다.
• REST API, Python 및 TypeScript SDK, CLI, WebSocket 라이브 스트림, webhooks 및 MCP(Claude Code, Cursor 등에서 사용하는 프로토콜)를 통해 기능을 제공합니다.

AI 에이전트에게 중요한 이유

• 사람과 상호작용하는 에이전트는 종종 이메일(지원, 가입, 청구서 등)이 필요합니다. 일반적인 전송 서비스를 사용하면 에이전트에게 정체성이나 스레드 기록이 없으며 안전 장치도 없습니다.
• Open Agent Email은 에이전트별 받은 편지함, 대화 스레드, SPF/DKIM/DMARC 검증, 프롬프트 주입 차단 및 선택적 사람 승인 게이트를 제공합니다.

작동 방식

People / other agents  →  MX record → Open Agent Email (SMTP listener) → store in DB
                                                   ↑
                                                   │
                                   Agent ↔ REST / SDK / MCP / Webhooks / CLI

• 수신 메일은 존재하는 받은 편지함으로 오는 것만 허용되며, 검증(SPF/DKIM/DMARC)되고 AI 관련 공격을 스캔한 후 저장됩니다.
• 발신 메일은 구성한 모든 SMTP 릴레이(SES, SendGrid, Resend 등)를 통해 전송됩니다. 승인 게이트가 활성화된 경우, 사람이 승인/거부 링크를 클릭할 때까지 메시지가 보류됩니다.

주요 기능

카테고리	하이라이트
받은 편지함 및 스레드	무제한 받은 편지함, 적절한 답장 스레드, 라벨, 검색, 휴지통/복원, 예약 전송(최대 90일), 10MB 이하 첨부 파일, 서명된 다운로드 링크
안전성	프롬프트 주입 탐지, 선택적 바이러스 검사, 만료 시간 포함 승인 게이트, 받은 편지함별 API 키(읽기 전용, 전송, 검토), 수신자 차단, 원클릭 구독 취소
인증 및 검증	메시지별 SPF/DKIM/DMARC 검사 저장; 엄격한 DMARC 실패 시 거부
전송	모든 SMTP 릴레이, 백오프 재시도, 멱등 키, 전체 전송 기록
배달 추적	내장 SES 이벤트 처리(배달, 반송, 불만) 및 자동 억제
도메인 지원	사용자 지정 도메인 추가, DNS 레코드 획득, 도메인별 발신 메일 DKIM 서명
Webhooks 및 이벤트	서명된 webhooks, 재시도 로직, 재생, 검색 가능한 이벤트 로그, 받은 편지함별 또는 전역 엔드포인트
연락처 및 템플릿	주소록, CSV 가져오기, 동의 메모, 후속 알림, 미리보기 포함 재사용 가능 템플릿
개발자 도구	OpenAPI 사양, Python 및 TypeScript SDK(런타임 의존성 없음), oae CLI, 96개 MCP 도구, 커서 스타일 페이지네이션, 구조화된 오류 코드
운영	SQLite(기본값) 또는 PostgreSQL, Alembic 마이그레이션, 메트릭 엔드포인트, 백업/복원 스크립트, Docker Compose, nginx 배포 예시

일반적인 사용 사례

• 챗봇용 지원 받은 편지함: support@brand.com이 티켓을 읽고, 답장을 초안으로 작성하며, 위험한 응답은 사람이 검토할 때까지 보류합니다.
• 가입 인증: 에이전트가 사용자를 생성한 후 자신의 메일함에서 확인 코드를 읽습니다.
• 안전망이 포함된 아웃바운드 아웃리치: 캠페인 초안 작성, 전송 예약, 이메일 발송 전 승인 요청을 수행합니다.
• 에이전트 간 통신: 각 에이전트가 실제 주소를 가짐으로써 서비스 간 이메일 기반 워크플로우가 가능해집니다.
• 이벤트 기반 워크플로우: 수신 메일이 n8n/Zapier/webhooks를 트리거하여 추가 자동화를 시작합니다.
• 개인 비서: 로컬 에이전트가 라이브 스트림을 통해 받은 편지함을 모니터링하고 답장을 초안으로 작성하면, 사용자가 간단한 링크로 승인합니다.

시작하기

1. 리포지토리를 복제하고 개발 스크립트를 실행합니다(Python 3.11 필요). 서버가 http://127.0.0.1:8000에서 시작되고 관리자 키가 출력됩니다.
2. (선택 사항) Next.js 대시보드 실행: cd client && npm install && npm run dev (http://localhost:3000).
3. API/CLI를 통해 받은 편지함을 만들고, SMTP 릴레이를 구성하고, 도메인의 MX 레코드를 서버(포트 25)로 지정합니다.
4. Python 또는 TypeScript SDK, MCP 명령 또는 간단한 curl 호출을 사용하여 메일을 나열, 읽기 및 전송합니다.

기술 스택

• 서버: Python 3.11, FastAPI, async SQLAlchemy, Alembic, aiosmtpd (SMTP 리스닝용).
• 데이터베이스: SQLite(기본값) 또는 PostgreSQL.
• 대시보드: Next.js 16, React, Tailwind CSS.
• SDK: Python 및 TypeScript, 런타임 의존성 없음.
• 패키징: Docker Compose + 프로덕션 배포 예시(nginx, 백업 스크립트).

상태 및 커뮤니티

• 활발히 개발 중이며, 현재는 단일 사용자(관리자 키 1개, 멀티 테넌트 계정 미지원)입니다.
• 로컬 및 Amazon SES 통합이 포함된 PostgreSQL 16 설정에서 테스트되었습니다.
• Discord에 참여하거나 GitHub에서 이슈/PR을 생성하세요.

라이선스: Apache 2.0.