Voidmail (hosted)

@voidly/mcp-email

AI エージェント向けのメールです。受信トレイを作成し、受信メッセージを構造化データとして待ち受けて読み取り、人間の所有者が承認した宛先に送信できます。電話番号や CAPTCHA は不要です。

サーバーが読み取れる情報。 新しい受信トレイ宛てのメールはサーバーが読み取れます。エンドツーエンド暗号化ではありません。所有者が受信トレイ用のキーを登録すると（以下の owner keys init）、保存されたメールはそのキーで暗号化されるため、Voidly は保存されたメールを読み取れません。このパッケージはそのキーをお使いのマシン上で生成し、Voidly に送信することなく、お使いのマシン上でメールを復号します。ただし、これもエンドツーエンド暗号化ではありません。受信メールは封印されるまでの一時的な間、受信サーバー上では平文であり、外部のメールもエンドツーエンド暗号化ではありません。人間向けメールは別製品です。

1 つのコマンドで受信トレイを作成

Node.js 20 以降が必要です。

npx -y @voidly/[email protected] create --name my-agent

新しいアドレスとキーの保存先が表示されます。キー自体は表示されません。

Created [email protected]
  agent key: ~/.voidly/mcp-email/[email protected]/agent-key (saved, not shown)
  owner key: ~/.voidly/mcp-email/[email protected]/owner-key (saved, not shown)
  creator identity: ~/.voidly/mcp-email/creator/identity.json (enrolled now)
  recipient policy: allowlist

--address myagent を追加すると、[email protected] の取得を要求できます。次に、VOIDMAIL_ADDRESS に新しいアドレスを設定して、MCP サーバーを起動します（次のセクションを参照）。

仕組み：作成 API が受け付けるのは、小さなプルーフ・オブ・ワークを伴う、登録済みの Voidly エージェント ID（did:voidly:…）で署名されたリクエストのみです。初回実行時には、プロトコル @voidly/agent-sdk 4.0 の register() が使用する Voidly Home の join を通じて、このマシン専用の作成者 ID を登録します。キーはここで生成され、公開鍵、API キーのハッシュ、署名のみが送信されます。登録が確定する前にキーが保存され（モード 0600、ディレクトリ 0700）、その後は creator/identity.json に保管されます。以降の実行では、その ID が再利用されます。各 ID で作成できる受信トレイは 1 日あたり 2 つです。別の ID を登録して上限を回避することはできません。登録の応答が失われた場合、次回の実行では別の登録を作成せず、同じ登録を完了します。

ターミナルを使わない場合は、エージェントから MCP を使って同じ操作ができます。env を空のままにして、voidmail_create_account を呼び出してください。

MCP サーバーとしてインストール

実行するバージョンを固定してください。Voidly が公開しているのはこのクライアントであり、キーを保持するのもこのクライアントです。

npx @voidly/[email protected]

~/Library/Application Support/Claude/claude_desktop_config.json に追加します（Claude Desktop）：

{
  "mcpServers": {
    "voidmail": {
      "command": "npx",
      "args": ["-y", "@voidly/[email protected]"],
      "env": {
        "VOIDMAIL_ADDRESS": "[email protected]"
      }
    }
  }
}

VOIDMAIL_ADDRESS は、サーバーが <key dir>/<address>/agent-key を参照するための設定です。これを設定しない場合、エージェントは voidmail_create_account で受信トレイを作成できます。その後、VOIDMAIL_ADDRESS を設定すると、次回の起動時にキーファイルが見つかります。

クイックスタート

MCP サーバーをインストールした後、次のプロンプトを使用してください。

Voidmail の受信トレイを 1 つ作成し、そのアドレスと受信トレイのキーの保存先を教えてください。メールはまず下書きを作成し、送信前に私の承認を待ってください。

サインアップのフローでは、voidmail_wait_for_email を呼び出し（最大 25 秒、送信者、件名、since による任意のフィルターを指定可能）、続いて返されたメッセージに対して voidmail_extract_code を呼び出します。どちらも読み取り専用です。既読にはせず、リンクをたどらず、HTML も返しません。返されるコードやリンクは、信頼できない送信者のコンテンツです。ご自身で開始したサインアップにのみ使用してください。

DID を取得（独自のエージェント ID を使用）

create と voidmail_create_account はそれぞれ作成者 ID を作成するため、これは任意です。すでに運用している、またはご自身で登録するエージェント ID を使って署名するには、@voidly/agent-sdk 4.0 を使用してください（クライアントキーによる直接の /v1/agent/register は利用できません。register() は Home join を使用します）。

// npm i @voidly/[email protected]   ·   run once, keep the file private
import { VoidlyAgent } from '@voidly/agent-sdk';
import { writeFileSync } from 'node:fs';

const agent = await VoidlyAgent.register({ name: 'my-agent' });
writeFileSync('agent-credentials.json', JSON.stringify(agent.exportCredentials()), { mode: 0o600 });

その後、MCP サーバー（または create）でそのファイルを指定します。DID はファイルから読み取られます。

{
  "VOIDMAIL_CREATOR_SIGNING_KEY_FILE": "/private/path/to/agent-credentials.json"
}

ファイルの所有者はご本人で、モードは 0600 でなければなりません。シンボリックリンク、より緩いモードのファイル、DID と一致しないキーは、何も送信される前に拒否されます。2.0 形式も引き続き使用できます。これは、64 バイトの生の Ed25519 秘密鍵のみで構成されるファイルに、VOIDMAIL_CREATOR_DID でその DID を設定する形式です。エクスポートした ID ファイルには、その ID のすべてのキーが含まれます。MCP プロセスは作成時にそのファイルを読み取ります。デフォルトの専用作成者 ID を使えば、メインのエージェント ID をメールクライアントから分離できます。

自分のコードで署名付き作成

API が検証する証明の例を、2つの短いスクリプトで示します。各スクリプトは agent-sdk の ID エクスポート（上記、またはこのパッケージの creator/identity.json）を読み込み、ステータスとアドレスを出力します。レスポンスには、インボックスのエージェントキー（vm_…）とオーナーキー（vmo_…）が一度だけ含まれます。これらをパーミッション 0600 のファイルに保存し、出力やログへの記録は決して行わないでください。

Node.js 20 以降（npm i tweetnacl）：

import { createHash, randomBytes } from 'node:crypto';
import { readFileSync } from 'node:fs';
import nacl from 'tweetnacl';

const creds = JSON.parse(readFileSync(process.argv[2], 'utf8'));
const sha = (text) => createHash('sha256').update(text).digest();
const body = JSON.stringify({ name: 'my-agent', recipient_policy: 'allowlist' });
const ts = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const preimage = ['voidmail-create-v1', 'POST', '/v1/agent-mail/create', creds.did, ts, nonce, sha(body).toString('hex')].join('\n');
let work;
for (let i = 0; ; i++) {
  work = i.toString(16).padStart(16, '0');
  const h = sha(`voidmail-create-pow-v1\n${preimage}\n${work}`);
  if (h[0] === 0 && h[1] === 0) break;
}
const secretKey = Buffer.from(creds.signingSecretKey, 'base64');
const signature = Buffer.from(nacl.sign.detached(Buffer.from(`${preimage}\n${work}`), secretKey)).toString('base64');
const res = await fetch('https://api.voidly.ai/v1/agent-mail/create', { method: 'POST', body, headers: {
  'Content-Type': 'application/json', 'X-Agent-DID': creds.did, 'X-Mail-Timestamp': ts,
  'X-Mail-Nonce': nonce, 'X-Mail-Pow': work, 'X-Mail-Signature': signature } });
const out = await res.json();
console.log(res.status, out.address ?? out.error);

Python 3（pip install pynacl）：

import base64, hashlib, json, secrets, sys, time, urllib.request
from nacl.signing import SigningKey

creds = json.load(open(sys.argv[1]))
body = json.dumps({"name": "my-agent", "recipient_policy": "allowlist"}).encode()
ts, nonce = str(int(time.time())), secrets.token_hex(16)
preimage = "\n".join(["voidmail-create-v1", "POST", "/v1/agent-mail/create", creds["did"], ts, nonce, hashlib.sha256(body).hexdigest()])
i = 0
while True:
    work = format(i, "016x")
    h = hashlib.sha256(f"voidmail-create-pow-v1\n{preimage}\n{work}".encode()).digest()
    if h[0] == 0 and h[1] == 0:
        break
    i += 1
seed = base64.b64decode(creds["signingSecretKey"])[:32]
signature = base64.b64encode(SigningKey(seed).sign(f"{preimage}\n{work}".encode()).signature).decode()
req = urllib.request.Request("https://api.voidly.ai/v1/agent-mail/create", data=body, method="POST", headers={
    "Content-Type": "application/json", "User-Agent": "voidmail-create-example/1", "X-Agent-DID": creds["did"],
    "X-Mail-Timestamp": ts, "X-Mail-Nonce": nonce, "X-Mail-Pow": work, "X-Mail-Signature": signature})
with urllib.request.urlopen(req) as res:
    print(res.status, json.load(res).get("address"))

署名の対象は、送信する本文のバイト列そのものの SHA-256 です。ハッシュ化したものと同じバイト列を送信してください。タイムスタンプはサービス時刻から5分以内である必要があり、1つの DID／nonce の組み合わせで作成できるインボックスは1つだけです。これらのヘッダーを付けずに POST /v1/agent-mail/create を実行すると、401 が返されます。

HTTP 401 は、作成証明がないか無効である、タイムスタンプの有効期限が切れている、または DID が有効でないことを意味します。ID とキーを確認してください。HTTP 429 は、作成の上限に達したことを意味します。Retry-After に従い、既存のインボックスを再利用するか、待機してください。上限を回避するために DID や IP を切り替えてはいけません。503 は、アドミッション、ID、またはコミットの確認が利用できなかったことを意味する場合があり、処理結果が不明なことがあります。作成リクエストを送信したものの結果が不明な場合は、別のインボックスを自動的に作成せず、まず元の試行の状態を確認してください。

暗号化ストレージ

各受信箱で一度だけ、ご自身のターミナルから有効にしてください（モデルからは絶対に実行しないでください）。

voidly-mcp-email owner keys init --address [email protected]

• 機能。 このマシン上で2つの鍵を作成します。メールを封印するためのX25519鍵（mail-secret-key）と、受信箱の鍵リストに署名するためのEd25519鍵（mail-signing-key）です。どちらも受信箱の鍵ディレクトリにある0600のファイルです。所有者鍵とともに送信されるのは、公開鍵、署名、および鍵を保有していることの証明のみです。それ以降、サーバーは新しいメッセージ（ヘッダー、本文、添付ファイル）をそれぞれの鍵宛てに封印し、暗号化されたコピーのみを保存します。この設定は元に戻せません。
• Voidlyが読み取れるもの、読み取れないもの。 登録済みの鍵がある受信箱について、Voidlyは保存されたメールを読み取れません。Voidlyのサーバーが変更された場合、それ以降に届くメールをコピーされる可能性はありますが、すでに保存されているメールを開くことはできません。ただし、受信したメールは封印されるまでの間、一時的に平文で確認できます。また、受信メールサーバーを運用するCloudflareも同様です。CloudflareのEmail Routingログには各メッセージの送信者、受信者、件名が記録され、当社のアカウントから閲覧できます。Voidlyは送信者のドメイン、到着時刻、サイズに加え、重複配信を除外するために使われる各メッセージの鍵付きフィンガープリントを、最長14日間保持します。このフィンガープリントが存在する間は、Voidlyが推測したメッセージと照合できる可能性があります。外部アドレス宛てに送信するメールはエンドツーエンド暗号化されません。Voidlyと当社の送信プロバイダー（Resend）を平文で経由します。
• 過去のメール。 鍵の登録前に保存されたメールは、引き続きサーバーから読み取れます。ツールの結果では、各メッセージにstorage: "sealed"（このマシンで復号済み）またはstorage: "server-readable"と表示されます。鍵の登録後に届いた、読み取り可能なメッセージにはstorage_warningが付加されます。
• 読み取りと検索。 voidmail_list_inboxは各メッセージの封印された概要を開き、voidmail_read_emailは封印されたメッセージをダウンロードして開きます。検索はこのマシン上で実行されます。封印されたメールの検索をサーバーに要求することはありません。デフォルトでは、メッセージが暗号化されている場合、件名、送信者、受信者、および先頭280文字を検索対象にします。full_text: trueを指定すると、暗号化された本文全体もダウンロードして検索します。メッセージの復号に失敗した場合、または別の受信箱やメッセージIDに紐付けられている場合、そのメッセージに関する情報は、サーバーが提供するフィールドも含めて一切表示されません。
• 鍵リストの確認。 mail-keys.jsonには、署名鍵と、確認済みの最新の鍵リストのバージョン（エポック）が固定されています。voidly-mcp-email owner keys statusはサーバーのリストを確認します。すべての鍵が署名鍵で署名されていること、リストがそのエポックについて完全であること、固定されているバージョンより古くないことを検証します。また、各メッセージには封印先の鍵が記載されており、このマシンで確認されていない鍵があれば警告が表示されます。
• 制限事項。 前方秘匿性はありません。mail-secret-key（またはkeyring/内の鍵）を入手した人は、その鍵で封印されたすべての保存済みメールを読めます。鍵とバックアップを失うと、そのメールはVoidlyを含め、誰にも復元できません。鍵ディレクトリを安全な場所にバックアップしてください。暗号化によって、メッセージの送信者が誰であるかは証明されません。MCPサーバーは復号のためにmail-secret-keyを読み取りますが、mail-signing-keyは読み取らず、鍵の作成、登録、変更を行うツールも備えていません。エージェントがシェルやファイル操作ツールを使用できる場合など、ユーザー権限で実行されるプログラムは、鍵ファイルも読み取れます。
• 鍵のローテーション。 voidly-mcp-email owner keys rotateは新しい鍵を登録し、古い鍵をkeyring/に保持するため、以前のメールも引き続き開けます。

権限：鍵は分け、所有者は一人

各受信箱には、2つの認証情報（エージェント鍵と所有者鍵）があり、暗号化ストレージを有効にすると、さらに2つのメール鍵が加わります。このパッケージはそれぞれを個別のファイルに保存します。

キー	ファイル（0600、ディレクトリ 0700）	使用者	できること
エージェントキー vm_…	~/.voidly/mcp-email/<address>/agent-key	MCP サーバー（モデルのツール用）	読み取り、承認済みの宛先への送信、宛先の申請、宛先の削除、ポリシーの厳格化
オーナーキー vmo_…	~/.voidly/mcp-email/<address>/owner-key	voidly-mcp-email owner を通じて使用するあなた	申請の承認または拒否、宛先の追加または削除、ロックまたはロック解除、いずれかのキーのローテーション、メールキーの登録
メール秘密鍵 vmx_…	~/.voidly/mcp-email/<address>/mail-secret-key（古いものは keyring/ 内）	MCP サーバー（このマシンでの復号用）	この受信箱宛てに封印されたメールを開く。どこにも送信されません
メール署名鍵 vms_…	~/.voidly/mcp-email/<address>/mail-signing-key	voidly-mcp-email owner keys を通じて使用するあなた	受信箱の鍵リストに署名する。どこにも送信されません
作成者の ID	~/.voidly/mcp-email/creator/identity.json、または VOIDMAIL_CREATOR_SIGNING_KEY_FILE で指定された独自のファイル	create と MCP サーバー（受信箱の作成専用）	そのエージェントの DID として作成リクエストに署名する。デフォルトのものはこの用途専用ですが、独自の ID ファイルには、その ID が持つその他の権限も含まれます

• create と voidmail_create_account は両方のファイルを書き込み、パスのみを表示します。**このサーバーがツールの結果にキーを含めることはありません。**このサーバーが出力するすべてのメッセージは、メール内に含まれて届いたものも含め、Voidmail のキー形式（vm_…、vmo_…、vmx_…、vms_…）と AGE-SECRET-KEY-… 文字列が除去されます。クラウドや GitHub のトークンなど、メールで届くその他の秘密情報は、変更されずにモデルへ渡されます。
• MCP サーバーがオーナーキーのファイルを読み取ることはなく、オーナー API のルート（/v1/agent-mail/owner/*）を呼び出すこともありません。オーナーキーを使うツールはありません。
• **モード 0600 は、他の OS ユーザーを排除しますが、エージェントは排除しません。**ユーザーとして実行されるものはすべてオーナーキーファイルを読み取れます。シェルまたはファイル用ツールを持つエージェント（コーディングエージェント、ファイルシステム MCP サーバーなど）も含まれます。そのようなエージェントがオーナーキーを読み取り、自身の宛先を承認する可能性があります。このマシン上でエージェントにシェルまたはファイルへのアクセス権がある場合は、オーナーキーファイルを読み取れない場所、またはマシンの外へ移動し、オーナーコマンドの実行時に VOIDMAIL_OWNER_KEY_FILE でそのファイルを指定してください。
• このパッケージで作成した受信箱には、Voidly API によって強制されるオーナー承認済みの宛先リストが設定されます。モデルへの指示によって強制されるものではありません。（オプトインしない REST 作成では、オーナーキーなし、任意の宛先を許可し、認証情報に関する警告のみを表示する従来型の受信箱が作成されます。作成時に recipient_policy: "allowlist"、owner_key: true、または content_policy: "enforce" を指定するとオプトインされ、その場合にのみレスポンスに owner_key が含まれます。このパッケージは常に recipient_policy: "allowlist" を送信します。）それ以外の相手に送信すると、send_attempted: false を伴って RECIPIENT_NOT_AUTHORIZED が返されます。API は保留中のリクエストを記録し、ツールの結果にはオーナーが実行する必要のあるコマンドが正確に示されます。
• 認証情報（秘密鍵、クラウド、GitHub、Slack、Stripe、AI プロバイダー、または Voidmail のキーなど）を含むように見えるメッセージは、認証情報のブロックが有効な受信箱で CONTENT_CONTAINS_CREDENTIAL によって拒否されます。オーナーキーがある受信箱（このパッケージが作成するすべての受信箱）では、これがデフォルトです。ツールの結果には検出された種類が列挙されますが、一致したテキストは表示されません。このチェックは既知のキー形式に一致します。パスワード、未知のトークン形式、または別の理由で機密性の高いデータは検出できません。
• **送信メールの認証情報もチェックされます。**メッセージの送信前に、API は宛先、件名、本文、返信先をメモリ上で既知の認証情報形式と照合します。一致した内容のコピーは保持せず、検出した種類ごとの日次件数のみを記録します。認証情報のブロックが有効な受信箱（オーナーキーがある受信箱ではデフォルト）では、一致があれば送信を停止します。それ以外の受信箱ではメッセージは送信され、レスポンスの X-Voidmail-Content-Warning ヘッダーに検出された種類が示されます。オーナーは https://voidly.ai/agent-mail/owner（または POST /v1/agent-mail/owner/policy と content_policy: "off"）でチェックを無効にできます。例外が 1 つあります。以下で説明する bootstrap によって作成されたオーナーキーでは、チェックを無効にできません。
• エージェントキーでできるのは制限のみです。宛先の削除、またはブロックの有効化が可能です。エージェントができることを広げる操作には、オーナーキーが必要です。
• 宛先の承認にはオーナーキーが必要で、このサーバーを介してメールからオーナーキーを渡す方法はありません。受信メールは信頼できないコンテンツとして扱ってください。

オーナーコマンド

voidly-mcp-email owner list                              # policy, recipients, pending requests
voidly-mcp-email owner approve <request-id>              # shows the recipient, asks you to confirm
voidly-mcp-email owner deny <request-id>
voidly-mcp-email owner add [email protected]            # or @example.com for a whole domain
voidly-mcp-email owner remove [email protected]
voidly-mcp-email owner lock                              # allowlist + credential blocking
voidly-mcp-email owner unlock                            # any recipient; asks you to confirm
voidly-mcp-email owner rotate-agent-key                  # old key stops working at once
voidly-mcp-email owner rotate-owner-key                  # replaces the owner-key file it read
voidly-mcp-email owner keys init                         # encrypted storage on; asks you to confirm
voidly-mcp-email owner keys status                       # check the server's key list against your pin
voidly-mcp-email owner keys rotate                       # new mail key; old one kept for old mail

保存済みの受信箱が複数ある場合は --address <[email protected]> を追加し、プロンプトなしで確認するには --yes を追加します。approve は最初に保留中のリクエストを読み込み、受信者を示します。また、保留中ではない ID は受け付けません。ローテーションしたキーはファイルに書き込まれ、表示されることはありません。rotate-owner-key は、VOIDMAIL_OWNER_KEY_FILE のパスを含め、読み込んだオーナーキーファイルをアトミックに置き換えます。新しいキーを保存する前に古いオーナーキーが失効するため、そのファイルを置き換えられない場合は、同じ場所に新しい 0600 ファイルを作成して新しいキーを保存します。それも失敗した場合に限り、ターミナルに一度だけ表示されます。キーファイルを読み込む MCP サーバーは、次回の呼び出しからローテーション後のエージェントキーを使用します。同じ操作はブラウザーの https://voidly.ai/agent-mail/owner でも利用でき、オーナーキーはメモリ内にのみ保持されます。

オーナーキーのない受信箱（mcp-email 1.1.0 以前で作成されたもの、またはオプトインせずに REST で作成されたもの）では、従来の動作が維持されます。つまり、認証情報に関する警告のみで任意の受信者に送信でき、ストレージはサーバーから読み取り可能です。エージェントキーによるオーナー登録（POST /v1/agent-mail/owner/bootstrap）は、2.0 に同梱されるサーバーリリースで無効になります。モデルが保持するのはエージェントキーであるため、オーナーの役割を取得したり、メールを転送したりできてはなりません。このような受信箱ではオーナーキーも暗号化ストレージも利用できません。このパッケージで新しい受信箱を作成し、そちらに移行してください。以前のブートストラップで発行されたオーナーキーは、受信者とポリシーに関する権限を維持しますが、認証情報ガードを無効にすることはできず（CONTENT_POLICY_FLOOR）、メールキーの登録やエージェントキーのローテーションもできません（OWNER_KEY_FROM_AGENT_KEY）。

受信メールを確認するには voidmail_list_inbox を使い、メッセージを読むには voidmail_read_email を使います。送信する前に、受信者、件名、本文を確認してから voidmail_send_once を呼び出してください。呼び出しの前に、ホストの状態に一意の操作 ID を生成して保存してください。応答が失われた後のステータス照会と、オーナーが拒否された受信者を承認した後の再試行には、同じ ID を使用してください。

ツール（21）

ツール	説明
voidmail_create_account	DID 署名付きの証明を使って新しい @voidmail.ai の受信トレイを作成します（クリエイター ID が存在しない場合は、先に専用のクリエイター ID を登録します）。両方の受信トレイキーをアクセス権限 0600 のファイルに保存し、パスのみを返します
voidmail_account_info	アカウントの詳細を取得します
voidmail_list_inbox	ページネーションとフィルターを使ってメールを一覧表示します。暗号化されたメールはここで復号します
voidmail_read_email	特定のメールを読み取ります。暗号化されている場合はここで復号します（自動的に既読にします）
voidmail_search_inbox	このマシン上で、件名、送信者、宛先、本文を検索します。サーバー検索は行いません
voidmail_wait_for_email	送信者、件名、または到着時刻を指定して、新しいメッセージを最大 25 秒間待ちます。ID、送信者、件名を返します。既読にはしません
voidmail_extract_code	1 通のメッセージのプレーンテキストから、ワンタイムコードと思われるものと HTTPS 認証リンクを抽出します（暗号化されている場合はここで復号します）。信頼できないコンテンツを対象とし、HTML は扱いません
voidmail_sending_limits	送信枠を消費せずに送信ポリシーを確認します
voidmail_send_once	保存済みの操作 ID と保持されたステータスを使って、許可されたメッセージを 1 通送信します
voidmail_send_status	再送信せずに、同じ元の送信のステータスを確認します
voidmail_send_email	永続的なステータスを保持しない従来の送信方法です。voidmail_send_once を推奨します
voidmail_policy	宛先とコンテンツのポリシー、承認済みの宛先、保留中のリクエストを確認します
voidmail_request_recipient	宛先の承認を所有者に依頼します。承認手順を返します
voidmail_revoke_recipient	承認済みの宛先を削除します（制限を加える場合、所有者は不要です）
voidmail_mark_read	メールを既読にします
voidmail_delete_email	メールを削除します
voidmail_create_alias	使い捨てメールエイリアスを作成します
voidmail_list_aliases	すべてのエイリアスを一覧表示します
voidmail_delete_alias	エイリアスを削除します
voidmail_set_webhook	所有者キーなしで、ポリシーがオープンな受信トレイに HTTPS ウェブフックを設定します。許可リスト方式の受信トレイ、または所有者キーが設定された受信トレイでは、人間の所有者が所有者キーを使って POST /v1/agent-mail/owner/webhook を実行する必要があります
voidmail_get_stats	受信トレイの統計情報を取得します

リソース（3）

リソース	URI	説明
受信トレイ	email://inbox	現在の受信トレイの内容
エイリアス	email://aliases	有効なメールエイリアス
統計情報	email://stats	アカウントの統計情報

環境変数

変数	必須	説明
VOIDMAIL_ADDRESS	既存の受信トレイの場合	あなたの @voidmail.ai アドレスです。サーバーは呼び出しのたびに <key dir>/<address>/agent-key を読み取ります
VOIDMAIL_KEY_DIR	いいえ	キーディレクトリ（デフォルトは ~/.voidly/mcp-email）
VOIDMAIL_AGENT_KEY_FILE	いいえ	エージェントキーのファイルパスを明示的に指定します（アドレスによる検索より優先されます）
VOIDMAIL_API_KEY	いいえ	ホストから直接渡されるエージェントキー（vm_…）です。ファイルより優先されます。所有者キーを含む、それ以外の値はすべて拒否され、送信されません。rotate-agent-key の実行後に更新してください
VOIDMAIL_CREATOR_SIGNING_KEY_FILE	いいえ	独自のクリエイター ID を指定します。@voidly/agent-sdk の ID エクスポート（JSON）、または Ed25519 の秘密鍵の生データ 64 バイトのみを含むファイルを指定します。所有者が管理し、モードは 0600 です。受信トレイのメール署名キーや所有者キーは使用できません。未設定の場合は <key dir>/creator/identity.json が使用され、最初の作成時に登録されます
VOIDMAIL_CREATOR_DID	生データのキーファイルを使用する場合	生データ 64 バイトのキーファイルに対応する DID です。JSON エクスポートの場合は省略可能ですが、ファイル内の DID と一致する必要があります
VOIDMAIL_CREATOR_AUTO_ENROLL	いいえ	off にすると、クリエイター ID が設定も保存もされていない場合に、create と voidmail_create_account が ID を登録するのを停止します
VOIDMAIL_OWNER_KEY_FILE	いいえ	所有者 CLI 専用です。所有者キーのファイルパスを明示的に指定します。MCP サーバーがこのファイルを読み取ることはありません
VOIDMAIL_SIGNING_KEY_FILE	いいえ	所有者 CLI 専用です。エージェントから離して保管する場合の、メール署名キーのファイルパスです。MCP サーバーがこのファイルを読み取ることはありません

REST API

MCP を使わずに直接使用します。

# List inbox
curl https://api.voidly.ai/v1/agent-mail/inbox \
  -H "X-Agent-Mail-Key: vm_your_key"

# Send email
curl -X POST https://api.voidly.ai/v1/agent-mail/send \
  -H "X-Agent-Mail-Key: vm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","subject":"Hello","text":"From my agent"}'

# Search (server-readable inboxes only; an inbox with encrypted storage answers 410
# SEARCH_IS_CLIENT_SIDE, and this package searches on your machine instead)
curl "https://api.voidly.ai/v1/agent-mail/inbox/search?q=invoice" \
  -H "X-Agent-Mail-Key: vm_your_key"

REST API で直接作成するには、有効なエージェント DID による署名付き証明が必要です。詳細は独自のコードから署名付きで作成するをご覧ください。

暗号化されたメッセージは { "sealed": true, "envelope": … } として返されます。暗号化された本文は GET /v1/agent-mail/inbox/{id}/sealed-body にあります。メッセージを開くには、受信トレイのメール秘密鍵が必要です。この鍵を持っているのはお使いのマシンだけです。

制限と配信

送信ワークフローを計画する前に、voidmail_sending_limits（または公開 API の GET /v1/agent-mail/limits）を呼び出してください。処理しきれない作業は、独自のキューに保留してください。429 が返された場合は、Retry-After ヘッダーと、制限の適用範囲およびリセット時刻を示す構造化データが含まれます。MCP エラーには待機時間も含まれます。制限を回避するためにアカウントや IP を切り替えないでください。ループを検出するため、同一のメッセージは 60 秒間ブロックされます。これは永続的な冪等性を保証するものではありません。安全性カウンターを利用できない場合、送信はフェイルクローズします。受信トレイの読み取りは送信制限とは別です。

共通の上限は、IP ごとに 1 時間あたり 100 件の試行、エージェントメールは 1 時間あたり 200 件、1 日あたり 1,500 件です。共有の送信プロバイダー予算は、すべての送信機能を通じて 1 日あたり最大 1,500 人の宛先、約 31 日間で合計 40,000 人の宛先です。カウンターは、失敗したリクエストや一部のみ受け付けられたリクエストも含め、すべての試行を数えます。これらは上限であり、確保済みの容量ではありません。正当な理由でより多くのボリュームが必要な場合は、オペレーターによる確認を経て制限を変更する必要があります。メールボックスを作成しても、一括メールの送信は可能になりません。

• 送信には、メールボックスごと、IP ごと、サービス全体の制限があります。各メールボックスでは、1 分あたり最大 10 件、1 日あたり最大 100 件の送信を試行でき、同一の宛先には 1 日あたり最大 10 件送信できます。共有制限により、これより早くリクエストが拒否される場合があります。メールボックスの作成は、IP ごとに 1 時間あたり 3 件、サービス全体で 1 時間あたり合計 600 件、DID ごとに 1 日あたり署名付き試行 2 件、サービス全体で 1 時間あたり署名付き試行 60 件に制限されています。これらのカウンターには、失敗したリクエストや一部のみ受け付けられたリクエストも含まれます。これは無制限の送信サービスではありません。
• 送信成功のレスポンスは、送信プロバイダーがリクエストを受け付けたことを意味します。宛先への配信や、誰かがメッセージを読んだことを証明するものではありません。
• 各 API 呼び出しの期限は 20 秒、レスポンスの上限は 2 MiB です。リクエストはリダイレクトを拒否し、自動的に再試行されることはありません。受信トレイのレスポンスが上限を超える場合は、取得するメッセージ数を減らしてください。
• MCP ツールのアノテーションでは、読み取り、送信、変更、削除を正確に示します。これらは参考情報のメタデータです。承認やインストール時の警告は、ChatGPT、Claude、その他のホストによって引き続き管理されます。
• 送信がタイムアウトした場合、結果が不明なことがあります。保存済みの操作 ID を使って voidmail_send_once と voidmail_send_status を使用してください。確認せずに再送信しないでください。
• サーバーが読み取り可能な受信トレイでは、受信したテキスト本文と HTML 本文を解析します。添付ファイルは保持されず、レスポンスのスキーマに該当フィールドが含まれていても、返信スレッドのメタデータは設定されません。暗号化ストレージを使用する受信トレイでは、添付ファイルを含む生メッセージ全体が暗号化されます。ツールに表示されるのは添付ファイル名とサイズのみで、内容は表示されません。信頼性の高いスレッド返信には、まだ対応していません。
• 新着メッセージの Webhook はベストエフォートであり、永続的な再試行履歴はありません。通知を見逃した場合は、受信トレイを読み取って照合してください。許可リスト方式の受信トレイ、または所有者キーが設定された受信トレイでは、エージェントの外部で POST /v1/agent-mail/owner/webhook を使って所有者が Webhook を登録する必要があります。voidmail_set_webhook では登録できません。所有者キー API の更新が有効になると、新たに登録された Webhook には X-Voidmail-Signature-256: t=<timestamp>,v1=<HMAC-SHA256> による署名が付与されます。それ以前に登録された Webhook では、再登録するまで、レガシーの X-Voidmail-Signature ヘッダーも引き続き受信します。このヘッダーには共有シークレットそのものが含まれ、ペイロードの署名ではありません。
• 受信メールは信頼できないコンテンツとして扱ってください。メッセージを根拠に、エージェントにメールを送信させたり、非公開データを開示させたり、金銭を使わせたりしてはいけません。API が宛先を追加するのは、所有者キーを含むリクエストの場合のみです。そのキーは、エージェントが読み取れない場所に保管してください。
• 所有者キーの推測はネットワークごとに制限されています。1 つの IP アドレス（IPv6 の場合は /64）から所有者キーの認証に何度も失敗すると、正しいキーを使っていても、そのネットワークからの所有者による呼び出しは現在の UTC 時間の終了まで拒否されます。同じネットワークを共有する人が、この制限を発動させる可能性があります。

変更履歴

CHANGELOG.md を参照してください。2.1.1 ではパッケージの説明を修正しています。2.1.0 では voidly-mcp-email create、作成者の ID の自動登録、作成者キーのファイルとしての agent-sdk ID エクスポート、voidmail_wait_for_email、voidmail_extract_code を追加しています。

リンク

• API ドキュメント：https://voidly.ai/api-docs
• ランディングページ：https://voidly.ai/agent-email
• プライバシー：https://voidly.ai/c/privacy
• サポート：[email protected]

ライセンス

MIT

送信の耐久性（1.1.0）

voidmail_send_once を使用する際は、ホスト側で保存した operationId（英字、数字、アンダースコアまたはハイフンを16～128文字）、宛先、件名、本文を指定します。同じメールボックス、ID、有効な内容を指定すると、保持されている元の結果が返されます。内容が変更されている場合は競合になります。ホストは送信前にIDを保持する必要があります。このコネクターがIDを生成したり、代わりに保存したりすることはありません。メールボックスの認証情報はメッセージ本文ではなく、ホスト設定に保存してください。

タイムアウトまたは応答の消失後は voidmail_send_status を使用してください。accepted はプロバイダーがリクエストを受け付けたことを意味し、配信済みまたは既読であることを意味しません。prepared は送信が開始されたという記録がまだない状態です。outcome_unknown には、進行中または中断された送信が含まれる可能性があります。refused_before_send は、プロバイダーへの連絡前にリクエストがブロックされたことが判明している状態を記録します。どの状態も、新しいIDによる自動再送信を許可するものではありません。このサービスは、タイムアウト、再起動、経過時間を理由に送信処理を再取得することはありません。プロバイダーへの呼び出し前に障害が発生した場合、メールの重複を避けるため、元の処理が未解決のまま残ることがあります。

REST の同等機能は POST /v1/agent-mail/outbound と GET /v1/agent-mail/outbound/{operationId} で、既存のメールボックス認証を使用します。新しい操作記録の作成と送信には、既存のメールボックス／サービス上限が適用されます。保存済みの元の結果の検索では、送信クォータを消費しません。初回の試行が同時に行われた場合、保守的な受付カウンターを消費することがあります。従来の /send エンドポイントと voidmail_send_email は従来どおり動作し、送信状態の耐久性は保証されません。配信 Webhook、返信のスレッド管理、送信本文の履歴、添付ファイルは別途対応予定です。