cfmail · 에이전트가 스스로 사용할 수 있는 사서함을 제공하세요

English | 简体中文

이게 뭔가요

목표는 간단합니다. 사람이 중간에 전달하거나 승인하거나 "보내기"를 클릭할 필요 없이 에이전트가 스스로 이메일을 받고 보내게 하는 것입니다. Cloudflare에서 실행되며 웹 UI가 없습니다 — 여러분이 둘러볼 받은 편지함이 아니라, AI/프로그램이 자기 것으로 사용하는 사서함입니다.

anything@your-domain으로 보낸 메일은 자동으로 수신되어 저장됩니다. 에이전트가 직접 검색하고, 전문을 읽고, 답장하고, 첨부파일을 전달합니다 — 여러분이 메일을 전달해 줄 필요도, 에이전트가 여러분이 "보내기"를 클릭할 때까지 기다릴 필요도 없습니다.

Someone emails you ──▶ Cloudflare receives it ──▶ parsed automatically, stored in a database and object storage
                                                              │
Agent ──asks a question / sends mail──▶ cfmail CLI (or MCP directly) ──▶ this service's API ──┘

초기 비용은 거의 0에 가깝습니다 — Cloudflare와 Resend의 무요 요금제로 충분하며, 둘 다 신용카드가 필요 없습니다:

한 사람이나 소수의 에이전트가 사용하는 소규모 프로젝트라면 이 한도에 도달하기 어렵습니다. 실졲로 사용량이 늘어나면 그때 업그레이드하세요.

이런 상황에 적합합니다:

• 에이전트에게 진정으로 자기 소유인 사서함을 주어, 중간에 수동 단계 없이 "수신 → 이해 → 답장/전달" 전체 프를 독립적으로 완료하게 합니다.

• 내 도메인으로 인증 코드, 알림, 청구서, 인보이스를 받고 AI가 찾아 정리하게 합니다.

• 메일(본몬과 첨부파일)을 일정에 따라 로컬 디스크에 동기화하고, 새 메일이 도착하는 즉시 클릭 가능한 로컬 파일이 포함된 채팅 메시지를 받습니다.

기술적 세부 사항(데이터베이스 스키마, 검색 설계, 구성 요소 분석, 이중 발송 백엔드 설계)은 ARCHITECTURE.md에 있습니다.

이 문서는 두 부븐으로 나니다: 설정(Setup) — 서비스를 자신의 Cloudflare 계정에 배포하기; 그리고 사용(Usage) — 배포 후 에이전트가 메일을 보내고 받도록 하는 방버.

Related MCP server: gmail-mcp

설정: Cloudflare에 배포하기 (~10분)

모든 작업은 여러분 자신의 Cloudflare 계정에서 이루어집니다 — 메일은 오직 여러분의 계정 아래에만 존재하며, 다른 누구도 접근할 수 없습니다.

준비물

1. Cloudflare 계정 (무요 요금제로 충분합니다).

2. 해당 계정에 이미 추가된 도메인 (메일 수신과 서비스 접근 양쪽에 사용됩니다).

3. 로컬에 설칙된 Node.js 18 이상.

0단계: 코드 받기, 로그인, 로컬 설적 파일 만들기

git clone <this-repo> && cd cfmail
npm install
npx wrangler login                       # log into your Cloudflare account in the browser
cp wrangler.jsonc wrangler.local.jsonc   # your private config, never pushed to the repo

계정과 연결된 모든 것(도메인, 데이터베이스 ID)은 wrangler.local.jsonc에 들어갑니다. 이미 gitignore 처리되어 있으며, 아래 모든 명령이 자동으로 읽어옵니다.

1단계: 데이터베이스 만들기 (메일 메타데이터와 본몬 저장)

npx wrangler d1 create email_db

명령이 database_id를 출력합니다 — 이를 wrangler.local.jsonc의 d1_databases[0].database_id에 복사하세요.

2단계: 객체 스토리지 만들기 (원본 메일과 첨부파일 저장)

npx wrangler r2 bucket create email-store

3단계: 도메인 설적

wrangler.local.jsonc를 열고 routes[0].pattern을 원하는 서브도메인으로 변경하세요. 예: mail.yourdomain.com (Cloudflare 계정에 있은 도메인이어야 합니다). 이 주소가 에이전트가 연결할 주소입니다.

4단계: 테이블 만들기, 접근 비밀번호 설적, 배포

npm run db:remote                        # create the tables
npx wrangler secret put MCP_TOKEN        # set an access password (see below)
npm run deploy                           # deploy

접근 비밀번호: 해당 명령을 실횅한 후 충분히 긴 임의의 문자열을 비밀번호로 붙여넣으세요 — openssl rand -hex 32로 충분합니다. 에이전트가 연결하러면 이 비밀번호가 필요합니다. 절대 유출하지 마세요. 교체하러면 명령을 다시 실횅하기만 하면 되며, 이전 비밀번호는 즉시 작동이 중지됩니다.

5단계: 수신 메일을 이 서비스로 연결

도메인으로 수신되는 모든 이메일을 이 서비스로 보네도록 설적합니다(1회성 설적):

# replace <ZONE_ID> with your domain's Zone ID, and <API_TOKEN> with a Cloudflare API token that has "Email Routing edit" permission
curl -X PUT "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/email/routing/rules/catch_all" \
  -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" \
  --data '{"enabled":true,"name":"catch-all to worker","matchers":[{"type":"all"}],"actions":[{"type":"worker","value":["cloudflare-email"]}]}'

대신 대시보드에서 클릭으로 진행하려면: Cloudflare 대시보드 → 내 도메인 → Email Routing → Catch-all → 작업 "Send to a Worker" → cloudflare-email 선택.

이 도메인에서 Email Routing을 켠 적이 없다면 대시보드에서 먼저 활성화하세요(메일 전달에 필요한 DNS 레코드를 자동으로 추가합니다).

완료! 이제 anything@your-domain으로 보낸 메일이 수신되며, 서비스는 https://your-subdomain에서 실행 중입니다. 확인하려면: test@your-domain으로 테스트 메일을 보낸 다음, 몇 초 안에 npx wrangler tail cloudflare-email에 처리되는 것이 표시되어야 합니다. 아래 '사용' 부분을 설정하면 에이전트가 이 메일을 찾을 수 있습니다.

선택 사항: 발송 활성화

이 단계를 건너뛰면 서비스는 메일 수신만 가능하고 발송은 불가능합니다. 두 가지 백엔드가 지원되며, 기본값은 Resend입니다:

옵션 1: Resend (권장):

1. Resend에 가입하고 도메인을 추가하세요 — 루트 도메인(yourdomain.com)을 바로 사용하면 되며, 서브도메인은 필요 없습니다.

2. Cloudflare DNS에 제공되는 세 가지 DNS 레코드를 추가하세요:

   유형	이름	값	프록시
   MX	send	Resend가 제공하는 주소, 우선순위 10	—
   TXT	send	v=spf1 include:amazonses.com ~all	—
   TXT	resend._domainkey	Resend가 제공하는 DKIM 공개 키	DNS 전용(회색 구름)

   이 MX 레코드는 send.yourdomain.com에 위치하므로 루트 도메인의 Email Routing과 충돌하지 않습니다. DKIM 레코드는 프록시를 꺼야 합니다 — 프록시를 켜 두면 검증에 실패합니다.

3. 키를 시크릿으로 설정하세요: npx wrangler secret put RESEND_API_KEY -c wrangler.local.jsonc

무료 요금제는 월 3,000건, 하루 100건입니다 — 시작하기에 충분하며, 규모가 커지면 유료로 전환하거나 아래 옵션으로 바꾸면 됩니다.

옵션 2: Cloudflare 기본 발송: wrangler.local.jsonc에 "send_email": [{ "name": "EMAIL" }]이 있는지 확인하고(템플릿에 이미 포함됨), Cloudflare Email 대시보드에서 도메인에 대한 1회성 Email Sending 온보딩을 진행하세요. Email Routing → Destination addresses에서 이미 검증한 주소로만 발송한다면 온보딩을 완전히 건너뛰고 바로 무료로 발송할 수 있습니다.

둘 다 설정하지 않으면 발송 시 무엇을 설정해야 하는지 설명하는 "no send backend available" 메시지가 반환되며, 수신과 조회에는 영향이 없습니다. 발송에 대한 자세한 내용(첨부파일 크기 제한, 발신자 제한, 실패 디버깅 방법)은 ARCHITECTURE.md와 cli/README.md를 참조하세요. 발송이 실패하면 에이전트가 오류 코드를 읽고 무엇이 잘못되었는지 알려주므로, 이러한 제한을 미리 외울 필요가 없습니다.

배포 후 지속적인 유지 관리

npx wrangler tail cloudflare-email        # tail incoming mail and errors live
npx wrangler secret put MCP_TOKEN         # rotate the access password
npx wrangler d1 execute email_db --remote --command "SELECT id,subject,from_addr,date FROM emails ORDER BY date DESC LIMIT 10"

wrangler.local.jsonc는 여러분의 컴퓨터에만 존재합니다 — 실수로 삭제하지 마세요. 삭제했다면 '0단계'를 다시 수행하고 데이터베이스 ID와 도메인을 다시 입력하세요.

사용: 에이전트가 메일을 보내고 받게 하기

배포가 끝나면 에이전트에 연결하는 방법은 세 가지가 있습니다. skills가 권장 경로입니다 — 가장 번거로움이 적고, "에이전트가 메일을 스스로 처리한다"는 목표에 가장 가깝습니다.

기본 방법: skills 사용 (권장)

skills/ 디렉터리에는 에이전트가 cfmail 명령줄 도구로 작업하도록 가르치는 두 가지 skill이 있습니다:

skills/
  email-inbox/   for a regular user: read and send mail with a bound Key
  email-admin/   for an admin: open mailboxes, issue/revoke Keys, configure new-mail alerts

두 skill은 함께 작동합니다. **관리자(admin)**는 email-admin으로 사서함 주소에 대한 Key를 발급하고, **사용자(user)**는 그 Key를 email-inbox에 넣어 메일을 보내고 받습니다.

0단계: cfmail 설치 (Node 20 이상 필요):

npm install -g cfmail

1단계: skill을 에이전트의 skills 디렉터리에 복사합니다. Claude Code의 경우 .claude/skills/입니다:

cp -r skills/email-inbox  your-project/.claude/skills/
cp -r skills/email-admin  your-project/.claude/skills/

skills/ 디렉터리 전체를 심링크로 연결할 수도 있습니다: ln -s /path/to/cfmail/skills your-project/.claude/skills.

2단계 (관리자): 사서함 열기:

cfmail admin setup --base https://your-subdomain --key <admin-MCP_TOKEN>   # one-time
cfmail admin create-key alice@your-domain                                 # prints a plaintext Key, shown only once

기타 관리자 명령: list-keys(발급 내역 확인), delete-key <address>(폐기), webhook --set whk_xxx(새 메일을 채팅으로 푸시, 선택 사항 — cli/README.md 참조).

3단계 (사용자): 해당 Key 구성:

cfmail setup --base https://your-subdomain --email alice@your-domain --key <the-key-from-step-2>

구성이 끝나면 에이전트에게 말만 하면 됩니다:

• "새 메일 있는지 확인해 줘" / "그 인증 코드 이메일 찾아줘"

• "그 인보이스 이메일에 답장해서 받았다고 확인해 줘"

• "그 첨부파일을 회계 부서로 전달해 줘"

에이전트가 스스로 올바른 명령을 선택하여 전문을 읽고, 첨부파일을 가져오고, 필요에 따라 답장합니다. 메일은 항상 Key에 바인딩된 주소에서 발송되며, 이는 서버 측에서 강제되므로 변경할 수 없습니다.

새 메일 도착 시 클릭 가능한 파일 링크가 포함된 채팅 푸시와 함께 메일을 로컬 디스크에 동기화하려면 — 이는 skills 흐름 밖의 별도 선택적 애드온입니다:

cfmail sync --dir ~/cfmail --notify whk_your-key

launchd/cron으로 일정에 따라 실행하세요. 디렉터리 구죠, 중복 제거 규칙, admin webhook과의 차이점은 모두 cli/README.md에 있습니다.

보안 참고: email-admin은 최고 권한의 관리자 키를 보유합니다 — 관리자 본인의 컴퓨터에만 두고, 일반 사용자에게 절대 넘겨주지 마세요.

대안: cfmail 명령줄을 직접 사용

skill 없이도 에이전트(또는 여러분)가 명령을 실행할 수 있습니다:

cfmail unread                                              # fetch the latest unread mail
cfmail search "invoice"                                    # full-text search, Chinese included
cfmail read <email-id>                                     # read the full text and attachment list
cfmail send --to a@x.com --subject "subject" --text "body"  # send one
cfmail reply <email-id> --text "reply text"                 # reply within the original thread
cfmail config                                              # see which mailbox this config points at

한 머신에서 여러 사서함 관리, 여러 에이전트 동시 실행, 로컬 아카이브 구죠, 모든 플래그 — 전체 참조는 cli/README.md에 있습니다(모든 명령은 --help도 지원합니다).

대안: CLI 없이 서비스를 MCP로 직접 연결

CLI를 설칙하고 싶지 않다면, MCP를 지원하는 AI 클라이언트를 서비스에 직접 연결할 수 있습니다:

claude mcp add --transport http email https://your-subdomain/mcp \
  --header "Authorization: Bearer your-password"

다른 MCP 클라이언트는 구성 파일을 사용합니다:

{
  "mcpServers": {
    "email": {
      "url": "https://your-subdomain/mcp",
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

연결이 끝나면 자연어로 그냥 요청하면 됩니다: "'invoice'가 포함된 메일 검색", "첫 번 메일을 열고 첨부파일 다운로드" — 내부적으로는 search_emails / list_emails / get_email / get_attachment / send_email 같은 도구를 AI가 자동으로 선택하므로 이름을 기억할 필요가 없습니다. 이 경로는 로컬 아카이빙이나 다중 사서함 관릭을 제공하지 않습니다 — 그 기능은 cfmail 전용입니다.

FAQ

• 서비스 URL이 로드되지 않음 / 연결이 재설정됨: 기본 *.workers.dev를 사용하지 마세요(일부 지역에서 차단됨) — 자체 도메인을 사용하세요(이 프로젝트가 기본적으로 하는 방버입니다).

• 보낸 테스트 메일이 반송됩(550 SPF): 발신 측 검증 문제입니다. 일반 사서함(Gmail, QQ, Outlook 등)에서 보내는 것은 영향을 받지 않습니다.

• 방금 보낸 메일이 아직 표시되지 않음: 수신과 인덱싱 사이에 몇 초의 지연이 있습니다 — 잠시 후 다시 확인하거나, npx wrangler tail cloudflare-email로 도착했는지 확인하세요.

• 401 오류 발새: Authorization: Bearer your-password가 올바르게 설적되었는지 확인하세요.

기여자를 위한: 로컬 개밥

cp .dev.vars.example .dev.vars                 # fill in a local access password
npm run db:local                               # create local database tables
npm run dev                                     # start locally on :8787
MCP_TOKEN=your-local-password node scripts/mcp-smoke.mjs    # smoke-test the local API
npm test                                        # unit tests
npm run typecheck                               # type checking

프로덕션 대상 스모크 테스트: BASE="https://your-subdomain" TOKEN="your-password" node scripts/remote-check.mjs

라이선스

MI T — 자유롭게 사용, 수정, 배포할 수 있습니다.