xobni

通过 Xobni.ai 为 AI 代理提供电子邮件基础设施。提供具有 REST API 和 MCP 服务器访问的真实电子邮件地址 (@xobni.ai)。当 AI 代理需要发送/接收电子邮件、搜索收件箱、管理附件或设置电子邮件通知的 Webhook 时使用。

# Xobni.ai Email Skill

Give AI agents real email addresses with full inbox functionality.

## Quick Start

1. Create agent at [xobni.ai/agents/new](https://xobni.ai/agents/new) → gets email like `your-agent@xobni.ai`
2. Create API key at [xobni.ai/settings/api-keys](https://xobni.ai/settings/api-keys) scoped to your agent
3. Connect via REST API or MCP

## API Key Scoping

Each API key is scoped to a **single agent**. The key can only access that agent's emails, threads, attachments, and webhooks. No need to pass `account_id` or `agent_id` — they're auto-resolved from your key.

**What scoped keys can do:**
- Read, send, search, and manage emails
- Create and manage webhooks
- View agent info and storage usage

**What scoped keys cannot do:**
- Access other agents' data (returns 403)
- Create or delete agents
- Manage API keys or billing

## MCP Connection

**URL**: `https://api.xobni.ai/mcp/`  
**Transport**: Streamable HTTP  
**Auth**: `Authorization: Bearer YOUR_API_KEY`

### Claude Desktop Config
```json
{
  "mcpServers": {
    "xobni": {
      "url": "https://api.xobni.ai/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Core Operations

### Read Inbox
```bash
curl -H "Authorization: Bearer $XOBNI_KEY" \
  "https://api.xobni.ai/api/v1/emails?status=received&limit=20"
```

### Send Email
```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/emails/send" \
  -d '{"to":["recipient@example.com"],"subject":"Hello","body_text":"Message here"}'
```

### Send with Attachments
```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/emails/send" \
  -d '{
    "to":["recipient@example.com"],
    "subject":"Report",
    "body_text":"See attached.",
    "attachments":[{"filename":"report.pdf","data":"<base64>","content_type":"application/pdf"}]
  }'
```

### Search (Semantic)
```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/search" \
  -d '{"query":"invoices from last month","limit":10}'
```

### Get Agent Info
```bash
curl -H "Authorization: Bearer $XOBNI_KEY" \
  "https://api.xobni.ai/api/v1/agents"
```

### Check Storage Usage
```bash
curl -H "Authorization: Bearer $XOBNI_KEY" \
  "https://api.xobni.ai/api/v1/emails/storage-usage"
```

## MCP Tools (14 total)

| Tool | Purpose |
|------|---------|
| `get_agent_info` | Get agent's name, email, slug, status |
| `read_inbox` | List emails with filters (status, limit, offset) |
| `read_email` | Get full email content by ID |
| `send_email` | Send with optional attachments and reply threading |
| `get_thread` | Get all emails in a conversation |
| `list_attachments` | List attachments for an email |
| `download_attachment` | Get pre-signed download URL (15 min) |
| `get_attachment_text` | Extract text from PDF/DOCX/XLSX/PPTX |
| `mark_email` | Update status: read/unread/starred/unstarred/archived |
| `search_emails` | Semantic search across emails + attachments |
| `list_webhooks` | List configured webhooks |
| `create_webhook` | Create webhook for email.received/email.sent |
| `delete_webhook` | Remove a webhook |
| `list_webhook_deliveries` | View webhook delivery history |

## Webhooks

Set up real-time notifications when emails arrive or are sent:

```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/event-hooks" \
  -d '{
    "url": "https://your-endpoint.com/webhook",
    "events": ["email.received"],
    "description": "Email notifications"
  }'
```

Supported events: `email.received`, `email.sent`. Payloads include email metadata and a 200-character snippet. Use `read_email` to fetch full content.

## API Reference

See [references/api.md](references/api.md) for full endpoint documentation.

## Key Concepts

- **Agent-scoped keys**: Each key works with one agent only. Auto-resolves IDs.
- **Semantic search**: Natural language queries across email bodies AND attachments (PDF, DOCX, etc.)
- **Attachments**: Send files via base64 (max 10 files, 10MB total)
- **Webhooks**: Real-time notifications for email events via n8n, Zapier, Make, or any HTTP endpoint.

---

## 中文说明

# Xobni.ai 电子邮件技能

为 AI 代理提供具备完整收件箱功能的真实电子邮件地址。

## 快速开始

1. 在 [xobni.ai/agents/new](https://xobni.ai/agents/new) 创建代理 → 获得类似 `your-agent@xobni.ai` 的电子邮件
2. 在 [xobni.ai/settings/api-keys](https://xobni.ai/settings/api-keys) 创建一个限定到你代理的 API 密钥
3. 通过 REST API 或 MCP 连接

## API 密钥作用域

每个 API 密钥的作用域限定为**单个代理**。该密钥只能访问该代理的电子邮件、会话、附件和 Webhook。无需传递 `account_id` 或 `agent_id` —— 它们会根据你的密钥自动解析。

**限定作用域的密钥能做什么：**
- 读取、发送、搜索和管理电子邮件
- 创建和管理 Webhook
- 查看代理信息和存储用量

**限定作用域的密钥不能做什么：**
- 访问其他代理的数据（返回 403）
- 创建或删除代理
- 管理 API 密钥或账单

## MCP 连接

**URL**: `https://api.xobni.ai/mcp/`  
**传输方式**: Streamable HTTP  
**认证**: `Authorization: Bearer YOUR_API_KEY`

### Claude Desktop 配置
```json
{
  "mcpServers": {
    "xobni": {
      "url": "https://api.xobni.ai/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## 核心操作

### 读取收件箱
```bash
curl -H "Authorization: Bearer $XOBNI_KEY" \
  "https://api.xobni.ai/api/v1/emails?status=received&limit=20"
```

### 发送电子邮件
```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/emails/send" \
  -d '{"to":["recipient@example.com"],"subject":"Hello","body_text":"Message here"}'
```

### 带附件发送
```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/emails/send" \
  -d '{
    "to":["recipient@example.com"],
    "subject":"Report",
    "body_text":"See attached.",
    "attachments":[{"filename":"report.pdf","data":"<base64>","content_type":"application/pdf"}]
  }'
```

### 搜索（语义）
```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/search" \
  -d '{"query":"invoices from last month","limit":10}'
```

### 获取代理信息
```bash
curl -H "Authorization: Bearer $XOBNI_KEY" \
  "https://api.xobni.ai/api/v1/agents"
```

### 查看存储用量
```bash
curl -H "Authorization: Bearer $XOBNI_KEY" \
  "https://api.xobni.ai/api/v1/emails/storage-usage"
```

## MCP 工具（共 14 个）

| 工具 | 用途 |
|------|------|
| `get_agent_info` | 获取代理的名称、电子邮件、slug、状态 |
| `read_inbox` | 列出带过滤条件的电子邮件（status、limit、offset） |
| `read_email` | 通过 ID 获取完整电子邮件内容 |
| `send_email` | 发送邮件，可选附件和回复会话串接 |
| `get_thread` | 获取一次会话中的所有电子邮件 |
| `list_attachments` | 列出某封电子邮件的附件 |
| `download_attachment` | 获取预签名下载 URL（15 分钟有效） |
| `get_attachment_text` | 从 PDF/DOCX/XLSX/PPTX 中提取文本 |
| `mark_email` | 更新状态：read/unread/starred/unstarred/archived |
| `search_emails` | 跨电子邮件 + 附件进行语义搜索 |
| `list_webhooks` | 列出已配置的 Webhook |
| `create_webhook` | 为 email.received/email.sent 创建 Webhook |
| `delete_webhook` | 删除一个 Webhook |
| `list_webhook_deliveries` | 查看 Webhook 投递历史 |

## Webhook

设置当电子邮件到达或发送时的实时通知：

```bash
curl -X POST -H "Authorization: Bearer $XOBNI_KEY" \
  -H "Content-Type: application/json" \
  "https://api.xobni.ai/api/v1/event-hooks" \
  -d '{
    "url": "https://your-endpoint.com/webhook",
    "events": ["email.received"],
    "description": "Email notifications"
  }'
```

支持的事件：`email.received`、`email.sent`。负载中包含电子邮件元数据和一段 200 字符的摘要片段。使用 `read_email` 获取完整内容。

## API 参考

完整的端点文档见 [references/api.md](references/api.md)。

## 关键概念

- **代理作用域密钥**：每个密钥仅对一个代理生效，自动解析 ID。
- **语义搜索**：跨电子邮件正文和附件（PDF、DOCX 等）的自然语言查询。
- **附件**：通过 base64 发送文件（最多 10 个文件，合计 10MB）。
- **Webhook**：通过 n8n、Zapier、Make 或任意 HTTP 端点对电子邮件事件进行实时通知。