{"id":47598152,"url":"https://github.com/chekusu/mails","last_synced_at":"2026-04-01T18:31:16.270Z","repository":{"id":345093592,"uuid":"1184444095","full_name":"chekusu/mails","owner":"chekusu","description":"email for agents. Built for AI agents that need to send, receive, and understand emails programmatically","archived":false,"fork":false,"pushed_at":"2026-03-31T08:22:52.000Z","size":299,"stargazers_count":267,"open_issues_count":0,"forks_count":15,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T10:23:36.918Z","etag":null,"topics":["agent","cli","mail"],"latest_commit_sha":null,"homepage":"https://mails.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chekusu.png","metadata":{"files":{"readme":"README.ja.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-17T15:38:54.000Z","updated_at":"2026-03-31T10:20:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chekusu/mails","commit_stats":null,"previous_names":["chekusu/mails"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/chekusu/mails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chekusu%2Fmails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chekusu%2Fmails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chekusu%2Fmails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chekusu%2Fmails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chekusu","download_url":"https://codeload.github.com/chekusu/mails/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chekusu%2Fmails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290869,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cli","mail"],"created_at":"2026-04-01T18:31:15.741Z","updated_at":"2026-04-01T18:31:16.263Z","avatar_url":"https://github.com/chekusu.png","language":"TypeScript","readme":"# mails\n\nAIエージェント向けのメールインフラ。プログラムでメールの送受信ができます。\n\n[![npm](https://img.shields.io/npm/v/mails)](https://www.npmjs.com/package/mails)\n[![license](https://img.shields.io/npm/l/mails)](https://github.com/chekusu/mails/blob/main/LICENSE)\n\n[English](https://github.com/chekusu/mails/blob/main/README.md) | [中文](https://github.com/chekusu/mails/blob/main/README.zh.md)\n\n## 仕組み\n\n```\n                        送信                                        受信\n\n  Agent                                               外部送信者\n    |                                                   |\n    |  mails send --to user@example.com                 |  agent@mails.dev にメール送信\n    |                                                   |\n    v                                                   v\n+--------+         +----------+              +-------------------+\n|  CLI   |--------\u003e|  Resend  |              | Cloudflare Email  |\n|  /SDK  |         | （外部）  |              |     Routing       |\n+--------+         +----------+              +-------------------+\n    |                    ^                              |\n    |  /v1/send          |  送信 API                    |  email() handler\n    |  /api/send         |                              |\n    v                    |                              v\n+-----------------------------------------------------------+\n|                       Worker                              |\n|                                                           |\n|  mails.dev（ホスティング）    or   自前デプロイ              |\n|  +-----------------------------------------+              |\n|  |  +----------+    +----------------+     |  +---------+ |\n|  |  |  db9.ai  |    |  fs9（ファイル） |     |  |   D1    | |\n|  |  | 全文検索  |    | （添付保存）    |     |  | （保存） | |\n|  |  | 高度検索  |    +----------------+     |  +---------+ |\n|  |  +----------+                           |              |\n|  +-----------------------------------------+              |\n+-----------------------------------------------------------+\n          |                           |\n   CLI/SDKで問い合わせ          mails sync\n   （remote provider）      （ローカルに取得）\n          |                           |\n          v                     +-----+------+\n       Agent                    |            |\n                          +---------+  +-----------+\n                          | SQLite  |  |  db9.ai   |\n                          |（ローカル）|  |（クラウド） |\n                          +---------+  +-----------+\n                          オフライン    全文検索\n                          バックアップ  高度なフィルター\n```\n\n## 特徴\n\n- **メール送信** — Resend経由、添付ファイル対応\n- **メール受信** — Cloudflare Email Routing Worker経由\n- **受信箱検索** — キーワードで件名、本文、送信者、認証コードを検索\n- **認証コード自動抽出** — メールから認証コードを自動検出（英/中/日/韓対応）\n- **添付ファイル** — CLIの `--attach` またはSDKで送信、MIME添付ファイルの受信・解析\n- **ストレージプロバイダー** — ローカルSQLite、[db9.ai](https://db9.ai)クラウドPostgreSQL、またはリモートWorker API\n- **ゼロランタイム依存** — Resend providerは `fetch()` のみ使用\n- **ホスティングサービス** — `mails claim` で無料 `@mails.dev` メールアドレス取得\n- **セルフホスト** — 独自Workerデプロイ、メールボックス単位の token 認証\n\n## インストール\n\n```bash\nnpm install -g mails\n# or\nbun install -g mails\n# or use directly\nnpx mails\n```\n\n## クイックスタート\n\n### ホスティングモード (mails.dev)\n\n```bash\nmails claim myagent                  # myagent@mails.dev を無料で取得\nmails send --to user@example.com --subject \"Hello\" --body \"World\"  # 月100通無料\nmails inbox                          # 受信箱を確認\nmails inbox --query \"password\"       # メール検索\nmails code --to myagent@mails.dev    # 認証コードを待機\n```\n\nResendキー不要 — ホスティングユーザーは月100通無料。無制限送信は自分のキーを設定：`mails config set resend_api_key re_YOUR_KEY`\n\n### セルフホストモード\n\n```bash\ncd worker \u0026\u0026 wrangler deploy             # 独自Workerをデプロイ\nwrangler secret put RESEND_API_KEY       # WorkerにResendキーを設定（送信用）\n# 単一メールボックス:\n#   MAILBOX=agent@yourdomain.com\n#   AUTH_TOKEN=YOUR_MAILBOX_TOKEN\n# 複数メールボックス:\n#   AUTH_TOKENS_JSON={\"agent@yourdomain.com\":\"token1\",\"other@yourdomain.com\":\"token2\"}\nmails config set worker_url https://your-worker.example.com\nmails config set worker_token YOUR_MAILBOX_TOKEN\nmails config set mailbox agent@yourdomain.com\nmails send --to user@example.com --subject \"Hello\" --body \"Hi\"  # Worker経由で送信\nmails inbox                              # Worker APIに問い合わせ\nmails sync                               # メールをローカルSQLiteにダウンロード\n```\n\n## CLIリファレンス\n\n### claim\n\n```bash\nmails claim \u003cname\u003e                   # name@mails.dev を取得（ユーザーあたり最大10個）\n```\n\n### send\n\n```bash\nmails send --to \u003cemail\u003e --subject \u003csubject\u003e --body \u003ctext\u003e\nmails send --to \u003cemail\u003e --subject \u003csubject\u003e --html \"\u003ch1\u003eHello\u003c/h1\u003e\"\nmails send --from \"Name \u003cemail\u003e\" --to \u003cemail\u003e --subject \u003csubject\u003e --body \u003ctext\u003e\nmails send --to \u003cemail\u003e --subject \"Report\" --body \"See attached\" --attach report.pdf\n```\n\n### inbox\n\n```bash\nmails inbox                                  # 最近のメール一覧\nmails inbox --mailbox agent@test.com         # 特定のメールボックス\nmails inbox --query \"password reset\"         # 全文検索（関連性順）\nmails inbox --query \"invoice\" --direction inbound --limit 10\nmails inbox \u003cid\u003e                             # メール詳細 + 添付ファイル\n\n# 高度なフィルター（mails.dev ホスティング / db9）\nmails inbox --has-attachments                # 添付ファイル付きのみ\nmails inbox --attachment-type pdf            # 添付ファイルの種類で絞り込み\nmails inbox --from github.com               # 送信者で絞り込み\nmails inbox --since 2026-03-01 --until 2026-03-20  # 期間指定\nmails inbox --header \"X-Mailer:sendgrid\"    # メールヘッダーで絞り込み\n\n# 自由に組み合わせ可能\nmails inbox --from github.com --has-attachments --since 2026-03-13\nmails inbox --query \"deploy\" --attachment-type log --direction inbound\n```\n\n### stats\n\n```bash\nmails stats senders                          # 送信者の頻度ランキング\n```\n\n### code\n\n```bash\nmails code --to agent@test.com              # 認証コード待機（デフォルト30秒）\nmails code --to agent@test.com --timeout 60 # タイムアウト指定\n```\n\n認証コードはstdoutに出力されるため、パイプで簡単に連携できます：`CODE=$(mails code --to agent@test.com)`\n\n### config\n\n```bash\nmails config                    # 設定をすべて表示\nmails config set \u003ckey\u003e \u003cvalue\u003e  # 値を設定\nmails config get \u003ckey\u003e          # 値を取得\n```\n\n### sync\n\n```bash\nmails sync                              # Workerからローカルストレージにメールを同期\nmails sync --since 2026-03-01           # 指定日からの同期\nmails sync --from-scratch               # フル再同期\n```\n\nWorker（ホスティングまたはセルフホスト）からローカルSQLiteにメールをプル。オフラインアクセスやローカルバックアップに便利。\n\n## SDK\n\n```typescript\nimport { send, getInbox, searchInbox, waitForCode } from 'mails'\n\n// 送信\nconst result = await send({\n  to: 'user@example.com',\n  subject: 'Hello',\n  text: 'World',\n})\n\n// 添付ファイル付き送信\nawait send({\n  to: 'user@example.com',\n  subject: 'Report',\n  text: 'See attached',\n  attachments: [{ path: './report.pdf' }],\n})\n\n// 受信箱一覧\nconst emails = await getInbox('agent@mails.dev', { limit: 10 })\n\n// 受信箱検索（全文検索、関連性順）\nconst results = await searchInbox('agent@mails.dev', {\n  query: 'password reset',\n  direction: 'inbound',\n})\n\n// 高度なフィルター（mails.dev ホスティング / db9）\nconst pdfs = await getInbox('agent@mails.dev', {\n  has_attachments: true,\n  attachment_type: 'pdf',\n  since: '2026-03-01',\n})\n\n// 認証コード待機\nconst code = await waitForCode('agent@mails.dev', { timeout: 30 })\nif (code) console.log(code.code) // \"123456\"\n```\n\n## Email Worker\n\n`worker/` ディレクトリにはメール受信用のCloudflare Email Routing Workerが含まれています。\n\n### セットアップ\n\n```bash\ncd worker\nbun install\nwrangler d1 create mails\n# wrangler.toml を編集 — D1データベースIDを設定\nwrangler d1 execute mails --file=schema.sql\nwrangler deploy\n```\n\nデプロイ後、Cloudflare Email Routingでこのworkerにメールを転送するよう設定してください。\n\n### Workerの認証設定\n\n```bash\n# 単一メールボックス:\n#   MAILBOX=agent@yourdomain.com\n#   AUTH_TOKEN=YOUR_MAILBOX_TOKEN\n# 複数メールボックス:\n#   AUTH_TOKENS_JSON={\"agent@yourdomain.com\":\"token1\",\"other@yourdomain.com\":\"token2\"}\n```\n\nすべての `/api/*` エンドポイントに `Authorization: Bearer \u003cmailbox-token\u003e` が必要です。この token は `?to=`、取得対象メール、または送信時の `from` と一致するメールボックス用である必要があります。`/health` は常に公開されます。mailbox token が未設定のまま `/api/*` にアクセスすると `503` を返します。\n\n### Worker API\n\n| エンドポイント | 説明 |\n|-------------|------|\n| `GET /api/inbox?to=\u003caddr\u003e\u0026limit=20` | メール一覧 |\n| `GET /api/inbox?to=\u003caddr\u003e\u0026query=\u003ctext\u003e` | メール検索 |\n| `GET /api/code?to=\u003caddr\u003e\u0026timeout=30` | 認証コードのロングポーリング |\n| `GET /api/email?id=\u003cid\u003e` | メール詳細（添付ファイル含む） |\n| `POST /api/send` | Resend経由でメール送信（RESEND_API_KEYが必要） |\n| `GET /api/sync?to=\u003caddr\u003e\u0026since=\u003ciso\u003e` | 増分メール同期（添付ファイル含む） |\n| `GET /health` | ヘルスチェック（常に公開） |\n\n## ストレージプロバイダー\n\nCLIはストレージプロバイダーを自動検出します：\n- 設定に `api_key` がある場合 → リモート（mails.devホスティング）\n- 設定に `worker_url` がある場合 → リモート（セルフホストWorker）\n- それ以外 → ローカルSQLite\n\n### SQLite（デフォルト）\n\nローカルデータベース：`~/.mails/mails.db`。設定不要。\n\n### db9.ai\n\nAIエージェント向けクラウドPostgreSQL。全文検索と関連性ランキング、添付ファイル内容の検索、高度なフィルタリングに対応。\n\n```bash\nmails config set storage_provider db9\nmails config set db9_token YOUR_TOKEN\nmails config set db9_database_id YOUR_DB_ID\n```\n\ndb9を使うと以下の機能が利用可能：\n- **重み付きFTS** — 件名（最高優先）\u003e 送信者 \u003e 本文 \u003e 添付ファイルテキスト\n- **添付ファイルフィルター** — 種類別、名前別、添付の有無\n- **送信者・期間フィルター** — `--from`、`--since`、`--until`\n- **ヘッダー検索** — JSONB形式のメールヘッダーを検索\n- **送信者統計** — 全送信者の頻度ランキング\n\n### リモート（Worker API）\n\nWorker HTTP APIに直接問い合わせます。`api_key` または `worker_url` が設定されている場合、自動的に有効になります。\n\n## 設定キー\n\n| キー | デフォルト | 説明 |\n|-----|----------|------|\n| `mailbox` | | 受信メールアドレス |\n| `api_key` | | mails.devホスティングサービスAPIキー |\n| `worker_url` | | セルフホストWorker URL |\n| `worker_token` | | セルフホストWorker用の mailbox token |\n| `resend_api_key` | | Resend APIキー |\n| `default_from` | | デフォルト送信者アドレス |\n| `storage_provider` | auto | `sqlite`、`db9`、`remote` |\n\n## テスト\n\n```bash\nbun test              # ユニット + E2Eテスト（外部依存なし）\nbun test:coverage     # カバレッジレポート付き\nbun test:live         # ライブE2Eテスト（.env設定が必要）\nbun test:all          # すべてのテスト（ライブE2E含む）\n```\n\nユニットテスト198件 + E2Eテスト27件 = **225件のテスト**、全プロバイダーをカバー。\n\n### プロバイダー別E2Eカバレッジ\n\n|                           | SQLite | db9   | Remote (OSS) | Remote (Hosted) |\n|---------------------------|--------|-------|--------------|-----------------|\n| Save inbound email        | ✅     | ✅    | N/A          | N/A             |\n| Save email + attachments  | ✅     | ✅    | N/A          | N/A             |\n| Send → receive (real)     | ✅     | —     | ✅           | ✅              |\n| Inbox list                | ✅     | ✅    | ✅           | ✅              |\n| has_attachments flag      | ✅     | ✅    | ✅           | ✅              |\n| Direction filter          | ✅     | ✅    | ✅           | ✅              |\n| Pagination                | ✅     | ✅    | ✅           | ✅              |\n| Email detail              | ✅     | ✅    | ✅           | ✅              |\n| Attachment metadata       | ✅     | ✅    | ✅           | ✅              |\n| Search                    | ✅     | ✅    | ✅           | ✅              |\n| Attachment content search | ✅     | ✅    | —            | —               |\n| Verification code         | ✅     | ✅    | ✅           | ✅              |\n| Download attachment       | ✅     | ✅    | —            | ✅              |\n| Save to disk (--save)     | ✅     | —     | —            | ✅              |\n| Mailbox isolation         | ✅     | ✅    | —            | —               |\n| Outbound recording        | ✅     | —     | ✅           | N/A             |\n| Send via Worker (/api/send)| —     | —     | ✅           | —               |\n| Sync to local             | —      | —     | ✅           | —               |\n\n## ライセンス\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchekusu%2Fmails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchekusu%2Fmails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchekusu%2Fmails/lists"}