通过 API 和 MCP 管理联系人

邮箱通讯录完全可以编程管理。消息 API 和 MCP 工具能够创建、编辑和删除联系人，批量导入和导出（CSV 或 vCard），搜索大型通讯录，并将联系人整理到群组中。这些数据与 Webmail 和 CardDAV 客户端中显示的数据相同，因此 AI 代理添加的联系人会出现在手机上，而你通过手机添加的联系人也会对 API 可见。

开始之前

• 联系人使用消息令牌接口 (/api/v1/messages/...) 及其权限范围，而不是控制面板 API 令牌。
• 每次调用都仅限令牌自己的邮箱。令牌只能查看和管理自己的联系人与群组，绝不能访问其他邮箱的联系人与群组。
• 联系人在邮箱中按电子邮件地址识别。导入操作会更新匹配的联系人。使用现有电子邮件地址创建联系人时，系统会原样返回该联系人，而不会创建重复项。
• 列表响应会返回一组整洁且易读的字段（姓名、电子邮件地址、公司、职位、电话、地址、生日和备注）。同步联系人背后的原始 CardDAV 卡片绝不会返回；你始终会收到整理后的版本。
• 导入支持最大 10 MB 的 CSV 和 vCard (.vcf) 文件，并能识别 Google 通讯录、Outlook、Apple 和 Roundcube 的导出格式，包括 UTF-8、UTF-16 和 BOM 的特殊情况。

权限范围

管理联系人

基础路径：/api/v1/messages/contacts

列出和搜索

GET /api/v1/messages/contacts?q=alice&per_page=50&page=1
Scope: messages:read

q 会匹配姓名或电子邮件地址。结果以分页形式返回（per_page 为 1 到 100，默认为 50），并包含 pagination 块（total、per_page、current_page、last_page），因此你可以逐页浏览大型通讯录直至末尾，而不会停在第一页。

创建联系人

POST /api/v1/messages/contacts
Scope: messages:write
{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "company": "Analytical Engines",
  "job_title": "Mathematician",
  "phone": "+1 555 0100",
  "address": "London",
  "birthday": "1815-12-10",
  "notes": "Met at the conference"
}

只有 email 是必填项。如果使用该电子邮件地址的联系人已经存在，系统会原样返回现有联系人。创建操作绝不会生成重复项，也不会覆盖已保存的详细信息。

批量导入

POST /api/v1/messages/contacts/import
Scope: messages:write
{
  "content_base64": "<base64 of your .csv or .vcf file>",
  "format": "csv"
}

发送经过 base64 编码的文件，并将 format 设为 csv 或 vcf（解码后最大 10 MB）。响应会说明应用了多少行，以及有多少行因缺少可用的电子邮件地址而被跳过：

{ "imported": 128, "skipped": 3 }

系统会自动识别 Google、Outlook、Apple 和 Roundcube 导出文件中的列标题，因此大多数导出文件无需编辑即可导入。

导出

GET /api/v1/messages/contacts/export?format=vcard
Scope: messages:read

将整个通讯录作为一个经过 base64 编码的文件返回：

{ "format": "vcard", "content_base64": "..." }

使用 format=csv 可获得适合电子表格的文件，使用 format=vcard 可获得能够载入其他邮件客户端的 .vcf 文件。

联系人群组

群组是通讯录中的通讯组列表。基础路径：/api/v1/messages/contact-groups

列出群组成员

GET /api/v1/messages/contact-groups/42/members?per_page=50&page=1
Scope: messages:read

返回群组中的联系人，字段与联系人列表中的整洁字段相同，另外还包含 pagination 块和群组的 contact_count 总数，因此你可以读取群组成员情况，而不必盲目修改。

添加或移除成员

POST /api/v1/messages/contact-groups/42/members
Scope: messages:write
{ "contact_ids": [11, 12, 13] }

添加操作是幂等的：已经在群组中的联系人将保持原样。只能添加属于同一邮箱的联系人。 每个添加或移除请求接受 1 到 200 个联系人 ID；更大的批次必须拆分为多个请求。

MCP 工具

AI 代理可通过 MCP 使用同一个通讯录，包括专用 stdio 服务器和公共 MCP 服务器：

写入工具仍然需要消息令牌的写入权限范围。本地托管 MCP 的管理员还可以要求明确批准写入操作，使代理能够浏览联系人而不能进行更改。