shellmail

AI 代理的电子邮件 API。检查收件箱、阅读电子邮件、提取 OTP 代码、通过 ShellMail 搜索消息。触发“检查电子邮件”、“收件箱”、“otp”、“验证码”、“shellmail”或任何与电子邮件相关的请求。

# ShellMail

Email for AI agents via shellmail.ai. Create inboxes, receive mail, extract OTPs automatically.

## ⚠️ Security & Privacy Notice

**This skill requires a sensitive `SHELLMAIL_TOKEN` that grants full access to your inbox and OTPs.**

When you set up this skill for the first time, you'll be instructed to save the token into agent configuration using `gateway config.patch`. This means:
- The agent will retain persistent access to your ShellMail inbox
- The token remains active until you explicitly revoke it or remove it from config
- Only proceed if you fully trust shellmail.ai and understand these privacy implications

**Best practices:**
- Use ShellMail for agent-related activities only, not personal email
- Use disposable/separate recovery emails when possible
- Review the `gateway config.patch` command output before confirming
- Revoke access when you no longer need this skill

## First-Time Setup

If no token is configured:

1. Ask user for desired email name (e.g., "atlas") and a recovery email
   - Or use `auto` for the name to generate a random address (e.g., "swift-reef-4821")
2. Run: `{baseDir}/scripts/shellmail.sh create <name> <recovery_email>`
3. If the address is already taken:
   - If the user says it was their old address: try creating with the same recovery email — deleted addresses are held for 14 days and can be reclaimed
   - Otherwise: suggest a different name or use `auto`
   - Do NOT suggest recovery unless the user confirms it's their previous inbox
4. Save the returned token:

```
gateway config.patch {"skills":{"entries":{"shellmail":{"env":{"SHELLMAIL_TOKEN":"sm_..."}}}}}
```

   **⚠️ Important:** Before running this command, explain to the user:
   - This saves the token into agent configuration for persistent access
   - The agent will retain access to their inbox/OTPs until the token is removed or revoked
   - They should only proceed if they trust shellmail.ai and understand the privacy implications
   - Show them the exact command and ask for confirmation before executing

5. Tell user to save the token safely — it won't be shown again
6. Suggest user send a test email to their new address to verify it's working
7. Once they confirm, run `inbox` to show the test email arrived

## Token Recovery

Only use recovery if the user explicitly says they lost access to an existing inbox they own:

```bash
{baseDir}/scripts/shellmail.sh recover <address@shellmail.ai> <recovery_email>
```

This sends a new token to the recovery email on file. Do not suggest this for "address taken" errors.

## Commands

```bash
{baseDir}/scripts/shellmail.sh <command>
```

### Check Inbox
```bash
{baseDir}/scripts/shellmail.sh inbox
{baseDir}/scripts/shellmail.sh inbox --unread
```

### Read Email
```bash
{baseDir}/scripts/shellmail.sh read <email_id>
```

### Get OTP Code
```bash
# Get latest OTP
{baseDir}/scripts/shellmail.sh otp

# Wait up to 30 seconds for OTP
{baseDir}/scripts/shellmail.sh otp --wait 30

# Filter by sender
{baseDir}/scripts/shellmail.sh otp --wait 30 --from github.com
```

### Search Emails
```bash
{baseDir}/scripts/shellmail.sh search --query "verification"
{baseDir}/scripts/shellmail.sh search --otp
{baseDir}/scripts/shellmail.sh search --from stripe.com
```

### Other Commands
```bash
{baseDir}/scripts/shellmail.sh mark-read <id>
{baseDir}/scripts/shellmail.sh archive <id>
{baseDir}/scripts/shellmail.sh delete <id>
{baseDir}/scripts/shellmail.sh health
```

## Common Patterns

**User says "check my email":**
```bash
{baseDir}/scripts/shellmail.sh inbox --unread
```

**User says "get the verification code":**
```bash
{baseDir}/scripts/shellmail.sh otp --wait 30
```

**User says "wait for GitHub OTP":**
```bash
{baseDir}/scripts/shellmail.sh otp --wait 30 --from github.com
```

## Revoking Access

If the user wants to revoke the skill's access to their ShellMail inbox:

### Remove Token from Config
```bash
gateway config.patch '{"skills":{"entries":{"shellmail":{"env":{"SHELLMAIL_TOKEN":""}}}}}'
```

### Delete Account Entirely
```bash
{baseDir}/scripts/shellmail.sh delete-account
```

**Note:** Deleted addresses enter a 14-day hold window and can only be reclaimed by the original owner using the recovery email.

## API Reference

Base URL: `https://shellmail.ai`

All endpoints use `Authorization: Bearer $SHELLMAIL_TOKEN`

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/mail` | GET | List emails (?unread=true&limit=50) |
| `/api/mail/:id` | GET | Read full email |
| `/api/mail/:id` | PATCH | Update {is_read, is_archived} |
| `/api/mail/:id` | DELETE | Delete email |
| `/api/mail/otp` | GET | Get OTP (?timeout=30000&from=domain) |
| `/api/mail/search` | GET | Search (?q=text&from=domain&has_otp=true) |
| `/api/addresses` | POST | Create {local, recovery_email} |

---

## 中文说明

# ShellMail

通过 shellmail.ai 为 AI 代理提供电子邮件服务。创建收件箱、接收邮件、自动提取 OTP。

## ⚠️ 安全与隐私须知

**此技能需要一个敏感的 `SHELLMAIL_TOKEN`，它授予对你收件箱和 OTP 的完全访问权限。**

当你首次设置此技能时，系统会指示你使用 `gateway config.patch` 将该令牌保存到代理配置中。这意味着：
- 代理将持久保留对你 ShellMail 收件箱的访问权限
- 在你明确撤销或将其从配置中移除之前，该令牌一直有效
- 仅在你完全信任 shellmail.ai 并理解这些隐私影响的前提下才继续

**最佳实践：**
- 仅将 ShellMail 用于与代理相关的活动，而非个人邮件
- 尽可能使用一次性/独立的恢复邮箱
- 在确认前审查 `gateway config.patch` 命令的输出
- 在不再需要此技能时撤销访问权限

## 首次设置

如果尚未配置令牌：

1. 询问用户想要的邮箱名称（例如 "atlas"）和一个恢复邮箱
   - 或者用 `auto` 作为名称以生成一个随机地址（例如 "swift-reef-4821"）
2. 运行：`{baseDir}/scripts/shellmail.sh create <name> <recovery_email>`
3. 如果该地址已被占用：
   - 如果用户表示这是他们的旧地址：尝试用相同的恢复邮箱创建 —— 已删除的地址会保留 14 天，可被重新认领
   - 否则：建议换一个名称或使用 `auto`
   - 除非用户确认那是他们之前的收件箱，否则不要建议恢复
4. 保存返回的令牌：

```
gateway config.patch {"skills":{"entries":{"shellmail":{"env":{"SHELLMAIL_TOKEN":"sm_..."}}}}}
```

   **⚠️ 重要：** 在运行此命令之前，向用户说明：
   - 这会将令牌保存到代理配置中以供持久访问
   - 在令牌被移除或撤销之前，代理将持续保留对其收件箱/OTP 的访问权限
   - 他们只应在信任 shellmail.ai 并理解隐私影响的前提下继续
   - 向他们展示确切的命令，并在执行前请求确认

5. 告知用户妥善保存令牌 —— 它不会再次显示
6. 建议用户向其新地址发送一封测试邮件以验证其正常工作
7. 在他们确认后，运行 `inbox` 以显示测试邮件已送达

## 令牌恢复

仅当用户明确表示他们丢失了对自己拥有的某个现有收件箱的访问权限时才使用恢复：

```bash
{baseDir}/scripts/shellmail.sh recover <address@shellmail.ai> <recovery_email>
```

这会向存档的恢复邮箱发送一个新令牌。不要在"地址已被占用"错误时建议此操作。

## 命令

```bash
{baseDir}/scripts/shellmail.sh <command>
```

### 检查收件箱
```bash
{baseDir}/scripts/shellmail.sh inbox
{baseDir}/scripts/shellmail.sh inbox --unread
```

### 阅读邮件
```bash
{baseDir}/scripts/shellmail.sh read <email_id>
```

### 获取 OTP 代码
```bash
# Get latest OTP
{baseDir}/scripts/shellmail.sh otp

# Wait up to 30 seconds for OTP
{baseDir}/scripts/shellmail.sh otp --wait 30

# Filter by sender
{baseDir}/scripts/shellmail.sh otp --wait 30 --from github.com
```

### 搜索邮件
```bash
{baseDir}/scripts/shellmail.sh search --query "verification"
{baseDir}/scripts/shellmail.sh search --otp
{baseDir}/scripts/shellmail.sh search --from stripe.com
```

### 其他命令
```bash
{baseDir}/scripts/shellmail.sh mark-read <id>
{baseDir}/scripts/shellmail.sh archive <id>
{baseDir}/scripts/shellmail.sh delete <id>
{baseDir}/scripts/shellmail.sh health
```

## 常见模式

**用户说"检查我的邮件"：**
```bash
{baseDir}/scripts/shellmail.sh inbox --unread
```

**用户说"获取验证码"：**
```bash
{baseDir}/scripts/shellmail.sh otp --wait 30
```

**用户说"等待 GitHub OTP"：**
```bash
{baseDir}/scripts/shellmail.sh otp --wait 30 --from github.com
```

## 撤销访问权限

如果用户想撤销此技能对其 ShellMail 收件箱的访问权限：

### 从配置中移除令牌
```bash
gateway config.patch '{"skills":{"entries":{"shellmail":{"env":{"SHELLMAIL_TOKEN":""}}}}}'
```

### 完全删除账户
```bash
{baseDir}/scripts/shellmail.sh delete-account
```

**注意：** 已删除的地址会进入 14 天的保留期，且只能由原所有者使用恢复邮箱重新认领。

## API 参考

基础 URL：`https://shellmail.ai`

所有端点都使用 `Authorization: Bearer $SHELLMAIL_TOKEN`

| 端点 | 方法 | 说明 |
|----------|--------|-------------|
| `/api/mail` | GET | 列出邮件（?unread=true&limit=50） |
| `/api/mail/:id` | GET | 阅读完整邮件 |
| `/api/mail/:id` | PATCH | 更新 {is_read, is_archived} |
| `/api/mail/:id` | DELETE | 删除邮件 |
| `/api/mail/otp` | GET | 获取 OTP（?timeout=30000&from=domain） |
| `/api/mail/search` | GET | 搜索（?q=text&from=domain&has_otp=true） |
| `/api/addresses` | POST | 创建 {local, recovery_