vaemail

VaEmail — AI エージェント向けメールインフラストラクチャ

VaEmail 用の MCP サーバーと CLI です。エージェントがメールを送信し、送信ドメインを認証し、配信状況を追跡し、メール到達性を診断できるようにします。その間に人間がダッシュボードを確認する必要はありません。

欧州のインフラストラクチャです。サーバーはドイツにあり、Amazon SES Europe 経由で送信します。

インストール

# Claude Code
claude mcp add vaemail --env VAEMAIL_API_KEY=swm_your_key -- npx -y vaemail mcp

# Any MCP client
npx -y vaemail mcp

または、設定ブロックとして：

{
  "mcpServers": {
    "vaemail": {
      "command": "npx",
      "args": ["-y", "vaemail", "mcp"],
      "env": { "VAEMAIL_API_KEY": "swm_your_key" }
    }
  }
}

GET /api/v1/me は、シークレットを返さずにテナント、キーのプレフィックス、スコープ、mode を識別します。連絡先操作では、CRM 識別子やアップサート用に、テナント内で一意の external_reference を指定できます。

統合テストにはサンドボックス API キーを使用してください。読み取りは通常どおり機能し、すべての書き込みは必ずロールバックされるトランザクション内で検証されます。行、ジョブ、メール、SMS、Webhook、外部 HTTP 呼び出しは一切発生せず、冪等性キーも保存されません。サンドボックスの書き込みレスポンスには、X-VaEmail-Sandbox: 1 と、JSON オブジェクト内の sandbox: true が含まれます。サンドボックスのレスポンスは、メールが配信された証拠にはなりません。

すべてが正しく接続されていることを確認します。

npx vaemail init

ツール

ツール	内容
vaemail_preparer_envoi	ニュースレターの下書きを準備し、リストを解決し、任意でテスト送信を行い、概要と1回限りの確認トークンを返します。送信も予約も行いません。
vaemail_confirmer_envoi	明示的な人間の確認後、トークンを使って、準備済みのニュースレターを予約または即時送信します。この操作は破壊的です。
vaemail_ou_en_est_ma_campagne	予約済み、送信中、送信済み、開封数、クリック数など、キャンペーンの状況を簡潔な文章で確認します。
vaemail_qui_est_abonne	フォルダーごとに購読者数とともに一覧表示するか、指定したアドレスのリストとステータスを表示します。
vaemail_importer_contacts	リストに連絡先を追加します（リストがない場合は作成されます）。購読解除済みのアドレスを再購読させることはありません。
vaemail_capabilities	サービスがサポートする機能を確認します。API キーは不要です。
vaemail_send_email	トランザクションメールをキューに登録し、その ID を返します。
vaemail_validate_email	ドライランを実行し、送信されるかどうかと、送信を妨げる要因を確認します。
vaemail_get_message	1件のメッセージの配信状況とすべてのイベントを確認します。
vaemail_list_messages	ステータス、タグ、受信者で絞り込んだ最近のメッセージを表示します。
vaemail_list_domains	SPF、DKIM、DMARC の状態がリアルタイムで反映された送信ドメインを表示します。
vaemail_create_domain	ドメインを登録し、公開する DNS レコードを返します。
vaemail_verify_domain	DNS を再読み込みし、認証済みの内容を報告します。
vaemail_dns_requirements	登録済みドメインにまだ必要なレコードを確認します。
vaemail_diagnose_deliverability	メールの到達状況が悪い理由と、改善するためのアクションを確認します。
vaemail_list_bounces	送信対象から除外されたアドレスと、その理由を表示します。
vaemail_get_usage	クォータ、キーの日次上限、残量を確認します。
vaemail_get_audit_log	このキーが行った操作を確認し、正確に報告できるようにします。

vaemail_confirmer_envoi と vaemail_send_email は、どちらも destructiveHint: true を示します。外部への送信は取り消せません。ニュースレターの確認ガードは即時送信に適用されます。下書きと予約済みキャンペーンの動作は従来どおりです。

これによって防ぐこと

エージェントは人間とは異なる形で失敗します。再試行し、ダッシュボードを確認せず、200 が返ると成功したと報告します。API はそれを前提に設計されています。

• 送信は受理されますが、配信されたとは限りません。 vaemail_send_email は 202 と ID を返します。送信後の状態を示すのは vaemail_get_message だけです。ツールの説明にもそのように記載されているため、エージェントは確認できない配信を完了したと報告しません。
• 再試行しても重複しません。 idempotency_key を渡すと、同じ呼び出しを繰り返した場合、二重送信せずに 24 時間は最初の応答を再生します。
• エラーには対処方法が記載されています。 すべての失敗には、安定した code、再試行可能かどうか、そしてそれを実行するエンドポイントを含む修正方法が付随します。
• キーには制限があります。 スコープ、1 日あたりの送信上限、メールごとの宛先数の上限、送信者ドメインの許可リストが設定されています。エージェントがキーの許可範囲を超えて利用することはできません。
• すべての呼び出しが記録されます。 どのキーを使い、どの操作を実行し、どのパラメーターを指定し、どのような結果になったかを記録します。メール本文は記録対象外です。自律的でありながら、説明責任を果たせます。
• 人間が行う手順は明示されています。 DNS レコードの公開がその一つです。値にプレースホルダーが残っているレコードには publishable: false のフラグが付きます。公開するとドメインの認証が壊れてしまうためです。

CLI

vaemail init                          # check config, print the MCP snippet
vaemail capabilities                  # what the service can do (no key needed)
vaemail send --to [email protected] --subject Hi --html '<p>Hello</p>'
vaemail status 42                     # delivery status of a message
vaemail domains:add exemple.fr        # declare a domain, print DNS records
vaemail doctor                        # why is my email not arriving?
vaemail usage                         # quota and remaining allowance
vaemail mcp                           # run the MCP server on stdio

任意のコマンドに --json を追加すると、機械可読な出力を取得できます。

ライブラリとして使用する

MCP サーバーと CLI が使用するクライアントはエクスポートされているため、アプリケーションから VaEmail を直接呼び出せます。依存関係はありません。

import { VaEmail } from 'vaemail';

const client = new VaEmail({ apiKey: process.env.VAEMAIL_API_KEY });

await client.send(
  {
    to: '[email protected]',
    subject: 'Your order is on its way',
    html: '<p>Tracking number: 1Z999</p>',
  },
  'order-4711', // idempotency key: safe to replay for 24 hours
);

エラーにはステータスコードだけでなく、次に取るべき対処方法も含まれます。

try {
  await client.send({ to: '[email protected]' });
} catch (error) {
  error.code;        // DOMAIN_NOT_VERIFIED
  error.retryable;   // false
  error.pourAgent(); // reason, corrective action, whether to retry
}

そのほか、capabilities()、health()、validate()、getMessage()、 listMessages()、listDomains()、addDomain()、verifyDomain()、 dnsRecords()、diagnoseDeliverability()、listSuppressions()、 removeSuppression()、usage()、auditLogs() を利用できます。

Stripe を接続する

Customers の読み取りと Webhook Endpoints の書き込みが可能な、Stripe の制限付きキー rk_live_ または rk_test_ を使用してください。シークレットキー sk_ は拒否されます。VaEmail は Stripe のシークレットを返しません。接続状態に表示されるのは、キーと webhook トークンの末尾 4 文字のみです。

REST ルート：

• GET /api/v1/integrations/stripe：接続状態を読み取ります。
• POST /api/v1/integrations/stripe：{"api_key":"rk_live_..."} と settings.write スコープを使って、webhook を作成または調整します。
• DELETE /api/v1/integrations/stripe：Stripe webhook を削除し、その後、ローカルの接続を削除します。取り消し不能な操作のため、人間による明示的な確認が必要です。

Stripe は POST /api/v1/webhooks/stripe/{token} を呼び出します。この公開ルートは Stripe-Signature を検証し、VaEmail API キーは受け取りません。

対応するイベントと自動化トリガー：

Stripe イベント	VaEmail トリガー
invoice.payment_failed	stripe_payment_failed (payment_failed)
customer.subscription.created	stripe_subscription_created (subscription_created)
customer.subscription.deleted	stripe_subscription_deleted (subscription_deleted)
checkout.session.completed	stripe_checkout_completed (checkout_completed)

同じ機能を提供する Python SDK も利用できます：pip install vaemail （https://github.com/vaemail/vaemail-python）。

環境変数

変数	意味
VAEMAIL_API_KEY	アカウント API キー。ダッシュボードの「API キー」から作成します。
VAEMAIL_BASE_URL	API のベース URL。デフォルトは https://app.vaemail.fr です。

その他の情報

• OpenAPI 仕様：https://app.vaemail.fr/openapi.json
• Capabilities エンドポイント：https://app.vaemail.fr/api/v1/capabilities
• エージェント向けドキュメント：https://vaemail.fr/agents

スキルと使用例

• エージェントスキル（エージェントが最初の呼び出し前に従うルール）：npx skills add vaemail/skills、ソースは https://github.com/vaemail/skills
• curl、Node、Python、Claude Code、Codex、OpenAI Agents、LangChain、CrewAI、n8n の使用例：https://github.com/vaemail/examples
• レジストリエントリー：io.github.vaemail/vaemail（server.json を参照）

依存関係

ありません。組み込みの fetch を使うために Node 18 以降が必要なだけで、ほかには何もありません。エージェントが自分でインストールするパッケージが、その背後に依存関係ツリーを引き込むことがないようにしてください。

ライセンス

MIT