Skip to content

Commit 9d25049

Browse files
Digidaiclaude
Digidai
and
claude
committed
docs: remove mails.dev — fully self-hosted only
mails.dev is the original author's hosted service. As an independent project, mails-agent should not depend on or promote third-party services. - Remove all mails.dev references from READMEs (en/zh/ja) - Remove Hosted quick start, claim commands, api.mails.dev URLs - Simplify architecture diagram (Worker-only, no cloud service) - skill.md: rewrite onboarding as deploy Worker → configure → use - Send priority: worker_url > resend_api_key (remove api_key path) - All examples use agent@yourdomain.com Source code still has mails.dev refs (hosted provider, claim command) — these remain functional for users who want upstream compatibility. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 07b56c2 commit 9d25049

4 files changed

Lines changed: 196 additions & 358 deletions

File tree

‎README.ja.md‎

Lines changed: 48 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ AIエージェント向けのメールインフラ。送信、受信、検索、
1212
1313
## なぜ mails？
1414

15-
メール送信のみの生のAPIとは異なり、mails はエージェントに完全なメールアイデンティティを提供します — 送信、受信、検索、認証コード抽出をワンパッケージで。無料の `@mails.dev` メールアドレスを取得して30秒で開始、または独自ドメインでセルフホスト。
15+
メール送信のみの生のAPIとは異なり、mails はエージェントに完全なメールアイデンティティを提供します — 送信、受信、検索、認証コード抽出をワンパッケージで。Cloudflare（無料枠）で独自ドメインにデプロイ。完全なコントロール、サードパーティへの依存なし。
1616

1717
## 特徴
1818

@@ -26,8 +26,7 @@ AIエージェント向けのメールインフラ。送信、受信、検索、
2626
- **削除API** — 処理済みメールの削除、添付ファイルとR2オブジェクトのカスケード削除
2727
- **ストレージプロバイダー** — ローカルSQLite（開発用）またはリモートWorker API（本番）
2828
- **ランタイム依存関係ゼロ** — すべてのプロバイダーがネイティブ `fetch()` を使用
29-
- **ホスティングサービス** — `mails claim` で無料 `@mails.dev` メールアドレス取得（月100通無料送信）
30-
- **セルフホスト** — Cloudflareに独自Workerをデプロイ（無料枠で十分）
29+
- **セルフホスト** — Cloudflareに独自Workerをデプロイ（無料枠で十分）、データを完全にコントロール
3130

3231
## インストール
3332

@@ -41,26 +40,21 @@ npx mails-agent
4140

4241
## クイックスタート
4342

44-
### ホスティングモード (mails.dev)
45-
4643
```bash
47-
mails claim myagent # myagent@mails.dev を無料で取得
48-
mails send --to user@example.com --subject "Hello" --body "World" # 月100通無料
49-
mails inbox # 受信箱を確認
50-
mails inbox --query "パスワード" # メール検索
51-
mails code --to myagent@mails.dev # 認証コードを待機
52-
```
44+
# 1. Workerをデプロイ（下記のセルフホスト完全ガイドを参照）
45+
cd worker && wrangler deploy
5346

54-
Resendキー不要 — ホスティングユーザーは月100通無料。無制限送信は自分のキーを設定：`mails config set resend_api_key re_YOUR_KEY`
55-
56-
### セルフホストモード
57-
58-
```bash
59-
cd worker && wrangler deploy # 独自Workerをデプロイ
47+
# 2. CLIを設定
6048
mails config set worker_url https://your-worker.example.com
6149
mails config set worker_token YOUR_TOKEN
6250
mails config set mailbox agent@yourdomain.com
63-
mails inbox # Worker APIに問い合わせ
51+
mails config set default_from agent@yourdomain.com
52+
53+
# 3. 使用開始
54+
mails send --to user@example.com --subject "Hello" --body "World"
55+
mails inbox # 受信箱を確認
56+
mails inbox --query "パスワード" # メール検索
57+
mails code --to agent@yourdomain.com # 認証コードを待機
6458
```
6559

6660
## 仕組み
@@ -70,46 +64,38 @@ mails inbox # Worker APIに問い合わせ
7064
7165
Agent 外部送信者
7266
| |
73-
| mails send --to user@example.com | agent@mails.dev にメール送信
67+
| mails send --to user@example.com | agent@yourdomain.com にメール送信
7468
| |
7569
v v
76-
+--------+ +----------+ +-------------------+
77-
| CLI |-------->| Resend |---> SMTP --->| Cloudflare Email |
78-
| /SDK | | API | | Routing |
79-
+--------+ +----------+ +-------------------+
70+
+--------+ +-------------------+
71+
| CLI |------ /api/send ----------------->| Cloudflare Email |
72+
| /SDK |<----- /api/inbox -----------------| Routing |
73+
+--------+ +-------------------+
8074
| |
81-
| または POST /v1/send（ホスティング） | email() handler
82-
| v
83-
v +-------------+
84-
+-------------------+ | Worker |
85-
| mails.dev クラウド | | (セルフホスト)|
86-
| (月100通無料) | +-------------+
87-
+-------------------+ |
88-
| 保存
89-
v
90-
+--------------------------------------+
91-
| ストレージプロバイダー |
92-
| |
93-
| D1 (Worker) / SQLite |
94-
+--------------------------------------+
95-
|
96-
CLI/SDKで問い合わせ
97-
|
98-
v
99-
Agent
100-
mails inbox
101-
mails inbox --query "コード"
102-
mails code --to agent@mails.dev
75+
v v
76+
+--------------------------------------------------+
77+
| あなたのCloudflare Worker |
78+
| /api/send → Resend API → SMTP配信 |
79+
| /api/inbox, /api/code → D1クエリ (FTS5全文検索) |
80+
| email() handler → MIME解析 → D1に保存 |
81+
+--------------------------------------------------+
82+
| |
83+
v v
84+
+--------+ +------------+
85+
| D1 | | R2 |
86+
| メール | | 添付ファイル|
87+
+--------+ +------------+
88+
|
89+
| CLI/SDKで問い合わせ
90+
v
91+
Agent
92+
mails inbox
93+
mails inbox --query "コード"
94+
mails code --to agent@yourdomain.com
10395
```
10496

10597
## CLIリファレンス
10698

107-
### claim
108-
109-
```bash
110-
mails claim <name> # name@mails.dev を取得（ユーザーあたり最大10個）
111-
```
112-
11399
### send
114100

115101
```bash
@@ -167,10 +153,10 @@ await send({
167153
})
168154

169155
// 受信箱一覧
170-
const emails = await getInbox('agent@mails.dev', { limit: 10 })
156+
const emails = await getInbox('agent@yourdomain.com', { limit: 10 })
171157

172158
// 受信箱検索
173-
const results = await searchInbox('agent@mails.dev', {
159+
const results = await searchInbox('agent@yourdomain.com', {
174160
query: 'パスワードリセット',
175161
direction: 'inbound',
176162
})
@@ -182,35 +168,34 @@ const email = await getEmail('email-id')
182168
await deleteEmail('email-id')
183169

184170
// 認証コード待機
185-
const code = await waitForCode('agent@mails.dev', { timeout: 30 })
171+
const code = await waitForCode('agent@yourdomain.com', { timeout: 30 })
186172
if (code) console.log(code.code) // "123456"
187173
```
188174

189175
## ストレージプロバイダー
190176

191177
CLIはストレージプロバイダーを自動検出：
192-
- 設定に `api_key` または `worker_url` がある → リモート（Worker APIに問い合わせ）
178+
- 設定に `worker_url` がある → リモート（Worker APIに問い合わせ）
193179
- それ以外 → ローカルSQLite（`~/.mails/mails.db`）
194180

195181
<details>
196182
<summary><strong>設定キー</strong></summary>
197183

198184
| キー | 設定方法 | 説明 |
199185
|-----|---------|------|
200-
| `mailbox` | `mails claim` または手動 | 受信メールアドレス |
201-
| `api_key` | `mails claim` | mails.devホスティングサービスAPIキー（mk_...） |
202-
| `worker_url` | 手動 | セルフホストWorker URL |
203-
| `worker_token` | 手動 | セルフホストWorker認証トークン |
186+
| `mailbox` | 手動 | 受信メールアドレス |
187+
| `worker_url` | 手動 | Worker URL（リモートプロバイダーを有効化） |
188+
| `worker_token` | 手動 | Worker認証トークン |
204189
| `resend_api_key` | 手動 | Resend APIキー（worker_url設定時は不要） |
205-
| `default_from` | `mails claim` または手動 | デフォルト送信者アドレス |
190+
| `default_from` | 手動 | デフォルト送信者アドレス |
206191
| `storage_provider` | 自動 | `sqlite` または `remote`（自動検出） |
207192

208193
</details>
209194

210195
<details>
211196
<summary><strong>セルフホスト完全ガイド</strong></summary>
212197

213-
自分のドメイン + Cloudflare + Resend でメールシステム全体を運用。mails.devに依存しません。
198+
自分のドメイン + Cloudflare + Resend でメールシステム全体を運用。完全なコントロール、サードパーティへの依存なし。
214199

215200
### 前提条件
216201

@@ -357,9 +342,8 @@ mails inbox
357342

358343
CLI/SDKがメールを送信する際、以下の順序で設定を確認：
359344

360-
1. `worker_url` → Worker `/api/send` 経由で送信（セルフホスト推奨）
361-
2. `api_key` → mails.devホスティングサービス経由
362-
3. `resend_api_key` → Resend APIに直接送信
345+
1. `worker_url` → Worker `/api/send` 経由で送信（推奨）
346+
2. `resend_api_key` → Resend APIに直接送信
363347

364348
`worker_url` を設定すれば、クライアント側に `resend_api_key` は不要 — ResendキーはWorker側にシークレットとして保存されます。
365349

‎README.md‎

Lines changed: 48 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Email infrastructure for AI agents. Send, receive, search, and extract verificat
1212
1313
## Why mails?
1414

15-
Unlike raw email APIs that only send, mails gives your agent a complete email identity — send, receive, search, and extract verification codes in one package. Claim a free `@mails.dev` mailbox and start in 30 seconds, or self-host on your own domain.
15+
Unlike raw email APIs that only send, mails gives your agent a complete email identity — send, receive, search, and extract verification codes in one package. Deploy on your own domain with Cloudflare (free tier). Full control, no third-party dependency.
1616

1717
## Features
1818

@@ -26,8 +26,7 @@ Unlike raw email APIs that only send, mails gives your agent a complete email id
2626
- **Delete API** — remove processed emails with cascade cleanup (attachments + R2)
2727
- **Storage providers** — local SQLite (dev) or remote Worker API (production)
2828
- **Zero runtime dependencies** — all providers use raw `fetch()`
29-
- **Hosted service** — free `@mails.dev` mailboxes via `mails claim` (100 sends/month)
30-
- **Self-hosted** — deploy your own Worker on Cloudflare (free tier)
29+
- **Self-hosted** — deploy your own Worker on Cloudflare (free tier), full control over your data
3130

3231
## Install
3332

@@ -41,26 +40,21 @@ npx mails-agent
4140

4241
## Quick Start
4342

44-
### Hosted (mails.dev)
45-
4643
```bash
47-
mails claim myagent # Claim myagent@mails.dev (free)
48-
mails send --to user@example.com --subject "Hello" --body "World" # 100 free/month
49-
mails inbox # List received emails
50-
mails inbox --query "password" # Search emails
51-
mails code --to myagent@mails.dev # Wait for verification code
52-
```
44+
# 1. Deploy your Worker (see Self-Hosted Deployment guide below)
45+
cd worker && wrangler deploy
5346

54-
No Resend key needed — hosted users get 100 free sends/month. For unlimited sending, set your own key: `mails config set resend_api_key re_YOUR_KEY`
55-
56-
### Self-Hosted
57-
58-
```bash
59-
cd worker && wrangler deploy # Deploy your own Worker
47+
# 2. Configure the CLI
6048
mails config set worker_url https://your-worker.example.com
6149
mails config set worker_token YOUR_TOKEN
6250
mails config set mailbox agent@yourdomain.com
63-
mails inbox # Queries your Worker API
51+
mails config set default_from agent@yourdomain.com
52+
53+
# 3. Use it
54+
mails send --to user@example.com --subject "Hello" --body "World"
55+
mails inbox # List received emails
56+
mails inbox --query "password" # Search emails
57+
mails code --to agent@yourdomain.com # Wait for verification code
6458
```
6559

6660
## How it works
@@ -70,46 +64,38 @@ mails inbox # Queries your Worker API
7064
7165
Agent External
7266
| |
73-
| mails send --to user@example.com | email to agent@mails.dev
67+
| mails send --to user@example.com | email to agent@yourdomain.com
7468
| |
7569
v v
76-
+--------+ +----------+ +-------------------+
77-
| CLI |-------->| Resend |---> SMTP --->| Cloudflare Email |
78-
| /SDK | | API | | Routing |
79-
+--------+ +----------+ +-------------------+
70+
+--------+ +-------------------+
71+
| CLI |------ /api/send ----------------->| Cloudflare Email |
72+
| /SDK |<----- /api/inbox -----------------| Routing |
73+
+--------+ +-------------------+
8074
| |
81-
| or POST /v1/send (hosted) | email() handler
82-
| v
83-
v +-------------+
84-
+-------------------+ | Worker |
85-
| mails.dev Cloud | | (your own) |
86-
| (100 free/month) | +-------------+
87-
+-------------------+ |
88-
| store
89-
v
90-
+--------------------------------------+
91-
| Storage Provider |
92-
| |
93-
| D1 (Worker) / SQLite |
94-
+--------------------------------------+
95-
|
96-
query via CLI/SDK
97-
|
98-
v
99-
Agent
100-
mails inbox
101-
mails inbox --query "code"
102-
mails code --to agent@mails.dev
75+
v v
76+
+--------------------------------------------------+
77+
| Your Cloudflare Worker |
78+
| /api/send → Resend API → SMTP delivery |
79+
| /api/inbox, /api/code → D1 query (FTS5 search) |
80+
| email() handler → parse MIME → store in D1 |
81+
+--------------------------------------------------+
82+
| |
83+
v v
84+
+--------+ +------------+
85+
| D1 | | R2 |
86+
| emails | | attachments|
87+
+--------+ +------------+
88+
|
89+
| query via CLI/SDK
90+
v
91+
Agent
92+
mails inbox
93+
mails inbox --query "code"
94+
mails code --to agent@yourdomain.com
10395
```
10496

10597
## CLI Reference
10698

107-
### claim
108-
109-
```bash
110-
mails claim <name> # Claim name@mails.dev (max 10 per user)
111-
```
112-
11399
### send
114100

115101
```bash
@@ -167,10 +153,10 @@ await send({
167153
})
168154

169155
// List inbox
170-
const emails = await getInbox('agent@mails.dev', { limit: 10 })
156+
const emails = await getInbox('agent@yourdomain.com', { limit: 10 })
171157

172158
// Search inbox
173-
const results = await searchInbox('agent@mails.dev', {
159+
const results = await searchInbox('agent@yourdomain.com', {
174160
query: 'password reset',
175161
direction: 'inbound',
176162
})
@@ -182,35 +168,34 @@ const email = await getEmail('email-id')
182168
await deleteEmail('email-id')
183169

184170
// Wait for verification code
185-
const code = await waitForCode('agent@mails.dev', { timeout: 30 })
171+
const code = await waitForCode('agent@yourdomain.com', { timeout: 30 })
186172
if (code) console.log(code.code) // "123456"
187173
```
188174

189175
## Storage Providers
190176

191177
The CLI auto-detects the storage provider:
192-
- `api_key` or `worker_url` in config → remote (queries Worker API)
178+
- `worker_url` in config → remote (queries Worker API)
193179
- Otherwise → local SQLite (`~/.mails/mails.db`)
194180

195181
<details>
196182
<summary><strong>Config Keys</strong></summary>
197183

198184
| Key | Set by | Description |
199185
|-----|--------|-------------|
200-
| `mailbox` | `mails claim` or manual | Your receiving address |
201-
| `api_key` | `mails claim` | API key for mails.dev hosted service (mk_...) |
202-
| `worker_url` | manual | Self-hosted Worker URL |
203-
| `worker_token` | manual | Auth token for self-hosted Worker |
186+
| `mailbox` | manual | Your receiving address |
187+
| `worker_url` | manual | Worker URL (enables remote provider) |
188+
| `worker_token` | manual | Auth token for Worker |
204189
| `resend_api_key` | manual | Resend API key (not needed when worker_url is set) |
205-
| `default_from` | `mails claim` or manual | Default sender address |
190+
| `default_from` | manual | Default sender address |
206191
| `storage_provider` | auto | `sqlite` or `remote` (auto-detected) |
207192

208193
</details>
209194

210195
<details>
211196
<summary><strong>Self-Hosted Deployment (Full Guide)</strong></summary>
212197

213-
Run the entire email system on your own domain using Cloudflare + Resend. No dependency on mails.dev.
198+
Run the entire email system on your own domain using Cloudflare + Resend. Full control, no third-party dependency.
214199

215200
### Prerequisites
216201

@@ -357,9 +342,8 @@ Your Agent External sender
357342

358343
When the CLI/SDK sends an email, it checks config in this order:
359344

360-
1. `worker_url` → sends via your Worker's `/api/send` (recommended for self-hosted)
361-
2. `api_key` → sends via mails.dev hosted service
362-
3. `resend_api_key` → sends directly to Resend API
345+
1. `worker_url` → sends via your Worker's `/api/send` (recommended)
346+
2. `resend_api_key` → sends directly to Resend API
363347

364348
Once `worker_url` is set, you don't need `resend_api_key` on the client — the Worker holds the Resend key as a secret.
365349

0 commit comments

Comments
 (0)