cfmail · Дайте вашему агенту почтовый ящик, которым он может пользоваться самостоятельно

Английский | 简体中文

Что это такое

Цель проста: дать агенту возможность самостоятельно получать и отправлять email — без участия человека, который пересылает, одобряет или нажимает «Отправить» в процессе. Сервис работает на Cloudflare и не имеет веб-интерфейса — это не почтовый ящик для просмотра, а ящик, которым 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 ──┘

Стоимость запуска почти нулевая — бесплатных тарифов Cloudflare и Resend достаточно, и ни один из них не требует кредитной карты:

Для небольшого проекта, которым пользуется один человек или несколько агентов, эти лимиты трудно превысить; обновите тариф позже, если объём действительно вырастет.

Он подходит для таких ситуаций:

• Дать агенту почтовый ящик, который действительно принадлежит ему, чтобы он мог самостоятельно выполнить весь цикл «получить → понять → ответить/переслать» без ручных действий между шагами.

• Получать коды подтверждения, уведомления, счета, инвойсы на свой домен и позволить ИИ находить и систематизировать их для вас.

• Синхронизировать почту — тела и вложения — на локальный диск по расписанию и получать в чат сообщение с кликабельной ссылкой на локальный файл в момент поступления нового письма.

Технические детали (схема базы данных, дизайн поиска, структура компонентов, двойная схема бэкенда отправки) — в ARCHITECTURE.md.

Этот документ состоит из двух частей: Настройка — развертывание сервиса в вашем собственном аккаунте Cloudflare; и Использование — после развертывания, как дать агенту возможность отправлять и получать почту.

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: направьте входящую почту в этот сервис

Направьте все письма, адресованные на ваш домен, в этот сервис (настраивается один раз):

# 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-записи, необхдимые для доставки почты).

Готово! Теперь почта, отправленная на anythhing@your-domain, перехватывается, а сервис доступен по адресу https://your-subdomain. Чтобы проверить: отправьте тестовое письмо на test@your-domain — в течение нескольких секунд npx wranler tail cloudflare-email должен показать его обработку; агент сможет найти его после того, как вы выполните настройку из раздела «Использование» ниже.

Необязательно: включите отправку

Пропустите этот шаг — и сервис сможет только получать почту, но не отправлять её. Поддерживаются два бэкенда, и по умолчанию используется Resend:

Вариант первый, Resend (рекомендуется):

1. Зарегисрируйтесь на Resend и добавьте свой домен — используйте корневой домен (yourdomain.com) напрямую, поддомен не нужен.

2. Добавьте три DNS-записи, которые он выдаст, в DNS Cloudflare:

Эта MX-запись находится на send.yourdomain.com, поэтому не конфликтует с Email Routing на корневом домене. Запись DKIM должна быть без прокси — если оставить её за прокси, проврка не пройдёт.

3. Установите ключ как секрет: npx wranler secret put RESEND_API_KEY -c wranler.local.jsonc

Бесплатный тариф — 3 000 писем/месяц, 100/день — этого достаточо для старта; платите по мере роста или переключитесь на вариант ниже.

Вариант второй, встроенная отправка Cloudflare: убедитесь, что в wrangler.local.jsonc есть "send_emails": [{ "name": "EMAL" }] (в шаблоне уж ест), затем один раз пройдите онбординг Email Sending для вашего домена в Email-дашборде Cloudflare. Если вы отправляете письма только на адреса, уже подтверждённые в Email Routing → Destination addresses, можно полностью пропустить онбординг и сразу отправлять бесплатно.

Если ни один из них не настроен, при отправке возвращается сообщение «no send backend available», в котором объясняется, что нужно настроить; приём и поиск писем не затрагиваются. Подробности об отправке — лимиты размера вложений, ограничения для отправителя, как отлаживать сбой — см. в ARCHITECTURE.md и cli/READEME.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/ есть два навыка, которые учат агента работать через инструмент командной строки cfmail:

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

Они работают вместе: администратор с помощью email-admin выпускает ключ для адреса почтового ящика, а пользователь вставляет этот ключ в email-inbox, чтобы отправлять и получать почту.

Шаг 0, установйте cfmail (требуется Node 20 или новее):

npm install -g cfmail

Шаг 1, скоируйте навыки в каталог навыков агента. Для 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 (админistrator), откройте почтовый ящик:

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

Другие команды админistrator: list-keys (посмотреть, что было выпущено), delete-key <address> (отозвать), webhook --set whk_xxx (присылать новые письма в чат, необязательно — см. cli/READEME.md).

Шаг 3 (пользватель), настройте этот ключ:

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

После настройки просто общайтесь с агентом:

• «Проверь, есть ли новые письма» / «Найди то письмо с кодом подтверждения»

• «Ответь на то письмо со счётом и подтверди, что мы его получили»

• «Перешли то вложение в бухгалтерию»

Он сам выбират нужную команду, читат полный текст, загружает вложения и отвечает по мере необходимос и. Письма всегда отправляются с адреса, привязанного к ключу, — это обеспечивается на стороне сервера и не может быть измнено.

Если вы также хотите синхронизировать почту на локальный диск и получать в чат кликабельную ссылку на файл при появлении нового письма — это отдельный необязательный дополнительный модуль, не входящий в процесс работы с навыками:

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

Запускайте его по расписанию через launchd/cron. Структура каталогов, правила дедупликации и отличия от admin webhook описаны в cli/READEME.md.

Замечание по безопасности: email-admin содержит админistrative ключ с наивысшими привилегиями — хранite его только на машине админistrator, никогда не передавайте обычному пользвателю.

Альтернатива: используйте напрямую командную строку cfmail

Без навыков агент (или вы) может просто выполнять команды:

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-совместимый ИИ-клиент прямо на сервис:

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" }
    }
  }
}

После подключения просто спрашивайте обычным языком: «найди письма, содержащие "счёт"», «открой первое и загрузи вложение» — под капотом используются инструменты вроде search_emails / list_emails / get_email / get_attachment / send_email, которые ИИ выбирает автоматически; запоминать их названия не нужно. Этот путь не даёт локального архивирования или управления несколькими ящиками — эти функции доступны только в cfmail.

Часто задаваемые вопросы

• 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

Лицензия

MIT — можно свободно использовать, изменять и распространять.