mailsnail

Mailsnail

AI エージェント向けの、オープンソースでプロバイダーを問わない郵送サービスです。

エージェントには、まだ使えない通信手段がひとつあります。メールの送信、テキストメッセージの送信、通話、あらゆるフィードへの投稿はできます。しかしこれまでは、消印のある本物の封筒を郵便受けに届けるには、人間が印刷プロバイダーのアカウントを登録し、API キーを発行し、請求を設定する必要がありました。Mailsnail はこの課題を解決します。

• インストール不要です。 Claude、ChatGPT、Cursor、または任意の MCP クライアントに URL をひとつ追加してサインインするだけです。カードで手紙1通分を支払うか、残高をチャージできます。料金は原価ベースで、ファーストクラス郵便は1.21ドルから、書留郵便は8.61ドルからで、サブスクリプションはありません。Stripe Shared Payment Token を発行できるエージェントは、Machine Payments Protocol（HTTP 402）を利用して、アカウントなしで1通ごとに支払うこともできます。
• ベンダーロックインは一切ありません。 プロバイダー層はオープンで、入れ替え可能です。Click2Mail または Lob のアカウントを持ち込むことも、ゲートウェイ全体をセルフホストすることも、フェイルオーバーのためにプロバイダーを連携させることもできます。マネージドサービスは利便性を提供するもので、囲い込むものではありません。
• コンプライアンス関連の郵便物向けに構築されています。 extra_service: "certified" で書留郵便を送れます。予備的なリーエン通知や法的通知など、法律上、物理的な郵便で送らなければならず、ひとつの印刷 API の不調によって期限に遅れてはならない郵便物に対応します。

claude mcp add -t http mailsnail https://api.mailsnail.dev/mcp
# then /mcp → mailsnail → Authenticate, and: "Mail a thank-you letter to my aunt."

Claude Desktop または ChatGPT で、カスタムコネクターとして https://api.mailsnail.dev/mcp を追加してください。各アプリの設定手順は mailsnail.dev/setup をご覧ください。Click2Mail または Lob のアカウントを使って自分で運用しますか？実行方法をご覧ください。

ホステッドコネクターとプラグイン

最も手軽に始める方法では、インストールは不要です。リモートサーバーに対応する Claude、ChatGPT、Cursor、または任意の MCP クライアントで、カスタムコネクターとして https://api.mailsnail.dev/mcp を追加し、サインインしてください。各アプリの設定手順は mailsnail.dev/setup にあります。

plugins/mailsnail には、手紙の送付、書留郵便の送付、郵便物の追跡に使うスキルと、このコネクターが含まれています。Claude（チャット、Cowork、Claude Code）と Cursor で利用できます。Claude Code にインストールするには、次の手順を実行してください。

/plugin marketplace add iancollins27/mailsnail
/plugin install mailsnail@mailsnail

パッケージ

パッケージ	内容
mailsnail	MCP サーバー。以下の任意のプロバイダーを利用できる11個のツール（doctor、verify_address、preview_letter、send_letter、send_postcard、get_balance、top_up、get_letter、get_postcard、list_letters、cancel_letter）を提供します。Claude Code、Claude Desktop、Cursor、Codex CLI、OpenAI Agents SDK で利用できます。
@mailsnail/core	プロバイダーに依存しないコアです。アダプター（Click2Mail、Lob、任意の Mailsnail ゲートウェイ）、複数プロバイダーのフェイルオーバールーター、リクエスト検証機能を備えています。依存関係はありません。
@mailsnail/gateway	セルフホスト可能な REST API です。BYO プロバイダー認証情報、body_text から PDF へのレンダリング、校正データ、呼び出しログ機能を提供します。api.mailsnail.dev のマネージドサービスも、同じワイヤープロトコルを使用しています。
spec/	プロバイダーに依存しない郵便物スキーマと、フェイルオーバーの安全性に関する仕様です。これを実装すれば、印刷会社を含むあらゆるものが Mailsnail 互換ノードになります。

実行方法

モード	認証情報	支払い	おすすめの用途
ホステッドコネクター（api.mailsnail.dev/mcp）	不要。サインインします	利用者が、カードまたは残高から、郵便物ごとに支払います	Claude、ChatGPT、Cursorを使う人。セットアップ不要
マネージド（デフォルトのstdio）	不要	エージェントが、郵便物ごとに支払います（Stripe SPT）	SPTを発行できるエージェント
ゲートウェイ	独自の認証情報をサーバーで使用	プロバイダーのアカウント	チーム。PIIを自社のインフラ内に保持できます
click2mail / lob（BYOK）	独自の認証情報をローカル環境で使用	プロバイダーのアカウント	直接制御したい場合、プロバイダーを1つだけ使う場合
フェイルオーバーチェーン	プロバイダーごとに独自の認証情報	プロバイダーのアカウント	期限厳守の郵便物

フェイルオーバーは意図的に慎重な設計です。失敗したプロバイダーが、何も本番処理に入っておらず、料金も発生していないことを保証した場合にのみ（safeToRetry — 仕様を参照）、次のプロバイダーに送信を引き継ぎます。エラーよりも、証明付き郵便物を重複して送るほうが深刻です。

エグレスプロキシまたは許可リストの背後での実行

サンドボックス化されたエージェント（CIランナー、エンタープライズ向けエージェントプラットフォーム、ホステッドエージェントセッションなど）は、通常、エグレス許可リストの背後で動作します。マネージドモードは、まさにそうした環境向けです。セットアップは2分です。

npx mailsnail doctor      # says exactly what it can and can't reach, and why. Free; never mails.

次のホストを許可してください：

モード	許可するホスト	ポート
マネージド（デフォルト）	api.mailsnail.dev	443（TCP / HTTPS CONNECT）
セルフホストのゲートウェイ	MAIL_API_BASE_URL が指すホスト	そのポート
click2mail（BYOK）	rest.click2mail.com	443
lob（BYOK）	api.lob.com	443

許可リストにはIPアドレスではなくホスト名を登録してください。マネージドゲートウェイはマネージドインフラ上で動作しており、そのアドレスは予告なく変わるためです。ポリシー上、IPアドレスしか指定できない場合は、自分で管理するアドレスで @mailsnail/gateway をセルフホストしてください。この回避策こそ、オープンなプロバイダーレイヤーを設けた理由です。

HTTPプロキシ経由の場合。 Nodeのfetchは、明示的に指定しない限りHTTPS_PROXYを無視します。そのため、許可済みのゲートウェイでもタイムアウトが発生し、何も通知されないことがあります。次のいずれかを行ってください。

export NODE_USE_ENV_PROXY=1        # Node >= 22.21
export HTTPS_PROXY=http://proxy.example:8080

または、undiciをmailsnailと一緒にインストールしてください（npm i undici）。MailsnailがHTTPS_PROXY／HTTP_PROXY／ALL_PROXYを使って経路を設定し、NO_PROXYにも対応します。どちらが実際に有効かは、mailsnail doctorで確認できます。

TLS検査プロキシを使っていますか？ NODE_EXTRA_CA_CERTSに組織のCAバンドルを指定してください。

**それでもブロックされる場合、**推測ではなく、失敗の原因が示されます。トランスポートエラーにはunreachable、egress_blocked、tls_untrustedのいずれかのcodeと、許可すべき正確なhost:portが含まれます。いずれのコードも、リクエストがバックエンドに到達していないことを意味します。郵便物は送られておらず、料金も発生していません。必要なのはネットワークポリシーの修正であり、アカウントの変更ではありません。

安全性

• どの環境でもデフォルトでドライランです。実際に郵便物を送るには、明示的にMAIL_MCP_ALLOW_LIVE=1を設定する必要があります。
• MCPサーバーではセッションごとに支出上限を設定できます。マネージドモードでは、有料の郵便物の発送に失敗した場合、自動で返金されます。
• preview_letterは、料金が発生する前に校正用PDFと正確な料金を返します。まずユーザーに提示してください。
• スパム、嫌がらせ、詐欺には使用しないでください。プロバイダーの利用規約とUSPSの規制が適用されます。マネージドモードでは独自の不正利用審査を実施します。

オープンソースにする理由

ソフトウェアに郵便物を投函させ、その費用を支払わせることになります。コードを確認してください。自分のプロバイダーアカウントを使って、無料で自分で実行できます。認証情報を自分で保持したくない場合は、マネージドモードを使ってください。私たちに不満があれば、MAIL_PROVIDER=click2mailを設定すれば、郵便物の発送をそのまま続けられます。それが私たちの約束であり、このリポジトリが存在することで、その約束を確実に守れます。

状況

開発初期です。現在は米国内のみ対応しています。手紙、証明付き郵便物、はがきに対応しています。マネージドAPI、MCPサーバー、セルフホストゲートウェイ、Click2Mail／Lobアダプターは利用可能です。次は追加のアダプター（PostGrid、Stannp）です。先にアダプターを追加したい場合は、CONTRIBUTING.mdのアダプターガイドをご覧ください。

ライセンス

MIT。