API と MCP で連絡先を管理する方法

メールボックスのアドレス帳は、すべてプログラムから操作できます。メッセージ API と MCP ツールでは、連絡先の作成、編集、削除、一括インポートとエクスポート (CSV または vCard)、大規模なアドレス帳の検索、連絡先のグループ整理が可能です。これはウェブメールや CardDAV クライアントで表示されるものと同じデータです。そのため、AI エージェントが追加した連絡先はスマートフォンにも表示され、スマートフォンで追加した連絡先は API からも確認できます。

始める前に

• 連絡先では、ダッシュボード API トークンではなく、メッセージトークンのサーフェス (/api/v1/messages/...) とそのスコープを使用します。
• すべての呼び出しは、トークン自身のメールボックスに限定されます。トークンが表示、管理できるのは自身の連絡先とグループだけで、別のメールボックスにはアクセスできません。
• メールボックス内の連絡先はメールアドレスで識別されます。インポートすると、一致する連絡先が更新されます。既存のメールアドレスで作成した場合、重複は作成されず、その連絡先が変更されずに返されます。
• 一覧レスポンスでは、名前、メールアドレス、会社、役職、電話番号、住所、誕生日、メモという、読みやすく整理されたフィールドが返されます。同期された連絡先の背後にある未加工の CardDAV カードは返されず、常に整理済みの形式で取得できます。
• インポートでは、最大 10 MB の CSV ファイルと vCard (.vcf) ファイルを受け付けます。Google Contacts、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 を、別のメールクライアントへ読み込める .vcf には format=vcard を使用します。

連絡先グループ

グループはアドレス帳内の配布リストです。ベースパス: /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 ツール

同じアドレス帳を、MCP 経由で AI エージェントから利用できます (プライベート stdio サーバーとパブリック MCP サーバーの両方)。

書き込みツールには、引き続きメッセージトークンの書き込みスコープが必要です。ローカルでホストする MCP の管理者は、書き込み操作に明示的な承認を要求することもできます。これにより、エージェントは連絡先を閲覧できても変更はできないように設定できます。