API リファレンス

電子メールボックスをアシスタントに接続するには、Agentic Inbox を使用します。または、管理 API を使用して、組織のドメイン、メールボックス、エイリアスを管理します。 これらは、別々の認証情報と権限を使用します。 必要な統合を選択します。

Agentic Inbox

PKCEでOAuthを介して接続 https://franklymail.com/api/agent/mcp. . . ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ザ・ 接続ガイド カバーChatGPTおよびClaudeの組み立て。 電子メールにサインインします。 各OAuthの助成金は、その1つの検証されたメールボックスに拘束されます。 助成金の使用 mailbox.read, message.read, message.search そして、 draft.write. . . 自動送信許可はありません。

Drafts はレビューリンクを返します。 そのメールボックスで検証されたセッションのみが、正確な現在のバージョンを承認できます。 パネルアカウントセッションは、同意または承認できません。 ツールの引数やチャットメッセージは送信を承認できません。

フォルダ固有の検索のために、パス folder として inbox, sent, drafts, archive, trash または junk (spam エイリアスです。 利用条件 list_folders そして、 folderId カスタムフォルダ用。 1つのセレクターを選択します。 欠落したフォルダは、すべてのメールを検索するのではなく、エラーを返します。 すべてのフォルダを検索するのを省略します。

prepare_forward リクエスト mailboxId, messageId, requestKey そして、 to; cc イントロダクション text オプションです。 それは両方を要求します message.read そして、 draft.write. . . 元のヘッダと読みやすいテキストが自動的に含まれています。 添付ファイルには、Webメール、または使用しているユーザーの明示的なテキストの選択が必要です。 omitAttachments: true. . . 未完成・超大型のオリジナルはお断りいたします。 フォワードドラフトは、同じレビューと承認フローを返信として使用しています。

ヒューマンレビューページでは、編集受信者、被写体、メッセージをサポートしています。 Mailbox Boostはまた任意を加えます トラックの開口部 そして、 AIで書き込む. . . 選択され、保存されるまで追跡は消えます。 複数の受信者に送信された共有メッセージは、受信者が開いたかを識別できません。 プライバシーのプロキシは、オープン信号に影響を及ぼす可能性があります。 Webメールのアクティビティを表示してください。

AIライターは、メールボックスの同意を必要とし、Webメールの書き込みの許容度を共有します。 保存されたドラフト、被写体、受取人、書き込み手順を使用して、OpenAIを介して提案を準備します。 提案を適用することは、保存と新鮮な人間の承認によって続いて、編集です。 MCP ツールや送信権限を追加し、エージェントは設定できません。 trackOpens またはブラウザのライターを呼び出します。

OAuthはS256 PKCEおよびS256 PKCEの承認コードを使用します resource=https://franklymail.com/api/agent/mcp. . . 構成を発見する 保護されたリソースメタデータ そして、 認可サーバーメタデータ. . . 動的クライアントの登録がサポートされています。 アクセストークンは1時間持続します。リフレッシュトークンが回転します。 リフレッシュトークンを使用して接続を呼び出します。 助成金は最大90日です。

MCP は、JSON レスポンスでステートレスな HTTP を使用します。 コールセンター tools/list スキーマ用 成功するコールには、 result.structuredContent; ツールの失敗は HTTP 200 を返すかもしれません result.isError=true と JSON テキスト ブロックを含む error. . . HTTP レスポンスとツールの結果の両方を確認します。 認証失敗は HTTP 401 を使用します。

同等の HTTP ルート: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id そして、 PUT /api/v1/drafts/:id. . . 募集職種 folder または folderId, text, from, subject, unread, limit (1～25) position. . . ドラフト作成が必要です mailboxId, requestKey, to, subject, text; cc そして、 replyToMessageId オプションです。 修正は現在の要求します version 置換受取人、被写体、テキストを完成させます。

フォルダリストと転送は、MCPツールを使用します list_folders そして、 prepare_forward; HTTP ルートは分離していません。 ドラフトは、10からCcの受信者まで、256-characterの件名と20,000-characterのメッセージを組み合わせ、24時間後に失効します。 承認されるまでAgentic Inboxに滞在し、送信されたメッセージはWebメールに表示されます。

Agentic Inboxは、25のリクエスト/日と5/分をメールボックスに割り当てます。ブーストはこれを2,500/日と60/分に引き上げます。 同じメールボックスへの接続は、その許容値を共有します。 パスワードはメールボックスのセッションと接続を変更します。 既存のアカウント認証受信トレイの付与は、Webメールを介して再接続する必要があります。 毎日の許容差は、深夜UTCでリセットされます。 マニュアルレビューと承認は、この許容値を使用しません。 限界の間違いで、尊重して下さい Retry-After そして、 error.resetsAt;標準計画の排気の供給されたブースト リンクを示します。

メールボックスを作成できる人

1つのアカウントは1つの組織です。 メールボックスは、スタッフ、請負業者、あなた自身のプロジェクト、エイリアス、共有アドレスの人々のためにあります。 彼らがいる お客様がお申し出いただくか、またはお申し出いただいたお客様にはお申し出ください。. . . FranklyMailメールボックスを再販売するか、支払われるサービスに代わって他人のアカウントを実行しているか、侵害している 用語集. . . そこに再販条項を参照してください。 あなたが所有する複数のドメインを実行することは、常に良いであり、常に存在しています。 15ブランドを持つ持株会社が1つの組織です。 15 人の顧客を持つ代理店はそうではありません。

その区別を強制するメールボックスアカウントのクォータはありません。 アカウントが複数の組織として読み込まれる形状を成長させる場合、書き込みと尋ねます。 質問に中断されることはありません。

レガシーリソースAPI:メタデータのみ

既存のリソース資格情報は、元の権限を保持します。 メールコンテンツへのアクセスを有効にするには、新しい接続を作成します。 アシスタント接続ガイド. . . キーのみが付与された domain.read そして、 mailbox.read メタデータのみを読み込みます。 メッセージを読み、メールを送ったり、リソースを変更したりすることはできません。 新しく作成されたメールボックスとドメインが自動的にアクセスできなくなります。

キーをとして送って下さい Authorization: Bearer fma_.... . . 以下のパスは相対的に https://franklymail.com/api.

リストは受け入れます limit から 1 へ 100 (デフォルト 50) と UUID cursor 前回の回答から。 それらは戻ります { data: [...], nextCursor, requestId }; 細部のリターン { data: {...}, requestId }. . . バイト数は小数の文字列です。 DNS件の結果が保存されます。

標準的な制限されたアクセスにより、25のリクエスト/日および5/分が、アカウントの鍵を渡って共有されます。 Mailbox Boost 購読したメールボックスにつき、2,500/day と 60/minute にこれを上げます。 深夜UTCで毎日リセットします。 キーの天井はデフォルトにへ 60/minute、調節可能から 1 へ へ へ 600、別の共有された記述の安全天井と、 600/分。

各返送されたブーストメールボックスは、独自の手当から1つのリクエストを使用します。 ページの標準的なリソースは1つの標準リクエストを共有します。 必要なすべての許容範囲が使用可能である必要があります。拒否されたページは、それらのいずれかを消費します。 空のページでは、標準の許容値を使用します。 ドメインとDNSの読み込みは、そのドメインのUUIDによる最初のブーストメールボックスの許容量を明示的に付与するときにのみ使用できます。 mailbox.read あまりにも。 他のメールボックスへのアクセスは増加しません。

オン・ザ・オン 429, 名誉 Retry-After そして、 error.resetsAt. . . 毎日の排気の使用 daily_quota_exceeded; 分限度の使用 rate_limited. . . スタンダードプランの上限は含まれます error.metadata.upgrade ブーストリンクとより高い手当で。 メールボックスを管理している人にそのリンクを表示する。 エージェントはアップグレードを購入できません。 排気およびキー/アカウントの安全天井のブーストは改善の提供を持っていません。 X-Agent-Plan 標準を識別します。, ブーストまたは混合されたアクセス; X-Agent-Daily-Limit, X-Agent-Daily-Remaining そして、 X-Agent-Daily-Reset 必要な日頃の許容量を最も少ないリクエストで記述します。 鍵の天井はまだ認証された拒否をカウントします。 スコープリターンの欠損 403; 助成金のリターンの外側のリソース 404; 期限切れまたは再発されたキーリターン 401. . . 制限された資格情報は、 /api/v1 そして、 /api/agent/mcp オリジナルのスコープ内で。 これらのルートは、ブラウザのクッキーと管理キーの両方を受け入れます。

管理 API 認証

「新規管理キー」を選択します。 設定 → API キー. . . 作成時に一度に示します。ハッシュのみを保存し、再び表示できません。 リクエストごとにベアトークンとして送信してください。

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes

リクエストは JSON および JSON です。 エラーは { "error": { "code", "message", "field? } } マッチング HTTP ステータス: 401 欠落しているキー、再発または未知のキーのために、 403 キーが到達できないルートの場合、 422 悪いフィールドのために。

curl -X POST https://franklymail.com/api/mailboxes \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domainId":"<uuid>","localPart":"sales"}'

管理キーが呼び出すことができるもの

パスは相対的に https://franklymail.com/api. . . このリストは網羅的です: 応答しないルート 401 署名付きブラウザで何をするか、キーに。

ドメイン

メールボックス

エイリアスとフォワード

ドメインの追加、ステップバイステップ

POST /domains レコードを作成して公開するレコードを手元に戻します。 チェックが自分のスケジュールで実行されているので、検証を開始するために呼び出す必要はありません。

curl -X POST https://franklymail.com/api/domains \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"example.com"}'

# {"id":"<uuid>","domain":"example.com","status":"pending",
#  "ownership":"unproven","sending":"pending","recheckIn":300,
#  "records":[{"key":"mx","type":"MX","host":"example.com","value":"…","status":"missing"},
#             {"key":"spf"…},{"key":"dkim"…},{"key":"dmarc"…}]}

それぞれを出版する records[] あなたのDNSプロバイダでエントリ, その後、時計 GET /domains, すべてのドメインの同じペイロード, その 1 つの投票は、全体のバッチをカバー. 3つのフィールドは3つの異なる質問に答え、それらを閉じることは、通常の間違いです。

• records[].status: live DNS が期待するものに答えると、 missing それまで。
• ownership: proven DKIMの記録が上がると。 メールボックスをゲートし、インポートするものです。そのため、MXが切替される前にメールをコピーすることができます。
• status: ドメイン全体 active MXを含む全てのものが生み出され、メールが実際に届きます。

recheckIn 次の自動チェックまでの秒数です。 ハンマーではなく、丸い間に大体に眠ります。 POST /domains/:id/recheck ドメインごとに1つずつ強制的に制限されるため、ポーリングループとしてではなく、公開レコードの後に使用してください。 ルートは、アカウントと名前ごとに不意です: 重複やエラーではなく、既存のドメインを既に返したドメインを再投稿します。

メールボックスを移動し、ステップバイステップ

これは、ほとんどのスクリプトが書かれている流れであり、その部分を移動して発見するのではなく、検出する価値があります。

1. スタートします。 POST /mailboxes/:id/import 古いサーバーの接続情報を使って。 パスワードは列に触れる前に暗号化され、任意のルートで返さず、ジョブが止まる瞬間をクリアします。

curl -X POST https://franklymail.com/api/mailboxes/<mailboxId>/import \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"host":"imap.oldhost.com","port":993,"username":"you@old.com","password":"…"}'

# 202 {"importId":"<uuid>","status":"pending"}

それは答えます 202, ない 200: コピーは数時間かかりますので、ジョブがキューに入れられ、リクエストはすぐに返ります。 メールボックス毎の1つのインポート. . . 回答を1つ実行しながら2つ目から始める 409 import_in_progress 実行中のジョブの ID で、同じソースの 2 つの同時コピーがすべてのメッセージと再試行がそれを禁止しないためです。 Thirtyメールボックスは一度にインポートできます。 制限はメールボックスごとで、アカウントごとではありません。

2. それに従ってください。 GET /mailboxes/:id/import そのメールボックスの最新のジョブを返すか、または {"import": null} もしも誰もいなかったら。

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes/<mailboxId>/import

# {"import":{"id":"<uuid>","status":"running","folders_done":2,"folders_total":9,
#            "messages_done":1841,"messages_skipped":3,"current_folder":"INBOX",
#            "last_error":null,"started_at":"…","finished_at":null}}

status の 1 つ pending, running, done, failed または cancelled最後の3つはターミナルです。 秒単位で、ミリ秒単位ではなく、読み取り値が制限されていないが、他のサーバーが応答するにつれて、カウンターは高速に動くだけです。 folders_done / folders_total 正直な進歩図です: messages_done フォルダが開いているまでは、デノミネーターがないため、そこから構築されたパーセンテージは後方にジャンプします。 失敗時、 last_error 人に示されるように書かれた文章を運びます。

3. 必要であれば、停止してください。POST /mailboxes/:id/import/cancel 実行中のジョブを終了します。 古いプロバイダでは、このどれも変更されません。 インポートはそれから読み込まれるだけ。 リクエストを明示的に要求しない限り、すでにコピーされた滞在。

スクリプトの前に知っておくべき2つのこと。 メールボックスは、そのドメインのDKIMレコードが実証されている必要があります, 完全ではありません MX 切り株, ので、コピーは、あなたがメールを切り替える前に日を実行することができます. そして、我々のデプロイメントはパネルを再起動します: 停止を実行していたジョブが、それ自体で再開しません。そのため、30のインポートを開始するスクリプトは、サイレンスが成功するのではなく、その後の状態をチェックする必要があります。

物事の削除

2つのルールは、この API が要求したことを行わない唯一の場所です。

• mailbox は削除時にメールを保持します。DELETE /mailboxes/:id サービスからアドレスを取り出して、そのメッセージのメッセージがすべて残します。 同様にメールを破壊するために、要求はそう言い、パネルが示した正確なバイト数を確認する必要があります。 以来、メールボックスが成長していると、無声に余計に服用するのではなく、破壊は拒否されます。 事故によるエージェントがメッセージを破壊できない。
• メールボックスがオンになっている間にドメインは削除できません。 あなたを得る 409 domain_has_mailboxes アドレスと使用しているアドレスのリスト。 各メールボックスを最初に削除します。メールに関する質問が尋ねられたステップです。メールボックスごとに、誰がそれを答える権利があります。

代理人の場合: 人間に代わって質問に答えない。 メールボックスの削除は、メールが破棄されるまでリバーシブルです。 タスクが破壊されると、何が破壊され、人が決定するのかを言う。

メールでのお問い合わせ

メールボックスは、mboxファイル、すべてのフォルダー、すべてのメッセージのzipとしてダウンロードできますが、 API キーではなく、. GET /mailboxes/:id/export フィードバック 403 browser_only 重要なのは、その周りのコンフィギュレーションではなく、メール自体を上回る1つのルートの手であり、キーは正確に漏れる場所を秘めています。

エクスポート: パネルのメールボックスを開き、ダウンロードを使用します。 ビルドするとストリームが流れますので、メモリよりも大きいメールボックスが到着し、待機するジョブはありません。 ターミナルから望む場合は、ブラウザのパネルにサインインし、そのセッションで同じURLを呼び出します。 ルートは変更されず、キーのみが拒否されます。

これを行う 前のページへ あなたが戻って欲しいかもしれない何かを削除. 輸出は、破壊を生き残る唯一のコピーです。

キーができないこと

鍵は1つのアカウントにスコープ付けされ、その中の3つにまとめられます。 メールボックスをダウンロードできません。請求することができません。ドメイン(送金手数料)を登録することはできません。アプリパスワードは作成できません。アカウントのパスワードや2FAを変更することはできません。また、他のAPIキーの作成や変更はできません。 これらはすべて、署名付きブラウザが必要です。

理由は、不信ではなく、クレデンシャルの形です。キーは、 .env ファイル、CI の秘密ストア、エージェントの環境、および 3 つの場所に住んでいる秘密は、アカウントをオーバーするか、所有者をロックすることはできません。 鍵が漏れた場合は、設定で取り消しします: ホルダーは、最初に交換をミントすることはできません。

境界が主張しないもの。 メールボックスの作成とハンドアウトのメールボックスパスワードは、それが存在しているジョブであり、メールボックスパスワードを設定できる人は、そのメールボックスにIMAPにサインインし、それを読むことができます。 開催概要 export それを変えないし、そうでなければ、誰よりも悪い種類のセキュリティになります。 変更は、パスがもはやサイレントされていないことです: パスワードのリセットは、自分のメールボックスから実際のユーザーをロックし、時間内に通知されますが、ダウンロードは何も後ろに残らず、ログラインを残します。 その取引が特定のキーを望むものではない場合、キーを作成しないでください。管理キーには、リソースのスコープはありません。 電子メールで確認されたメールボックスにAgentic Inbox OAuthの接続を使用してください。

管理キーは期限切れではありません。 クォータではなく天井であるアカウントあたりの10のライブキー、つまりスクリプトまたはマシンごとに名前を付けて、その1つは明らかな決定です。

アカウントパスワードの変更は、すべてのキーを呼び出します。、回復にできるだけ多くのルーチンの回転に。 誰も新しいパスワードを入力する瞬間にそれら2を別々に伝えることができないので、安全な回答は、それが誰であるかを知ることに依存しません。 計画:長期スクリプトは大声で失敗する必要があります 401 再試行ではなく、パスワードを回転させると、その後に新しいキーが切り替わります。 鍵が作成されると、パスワードが変更されたら、アカウント所有者にメールをお送りしますので、他の人が作ったキーは気づかれません。

管理 API および輸出率の限界

2つのカウンタは、キーの1つではなく、両方のアカウントで、キーを回転させると、それらをリセットしません。

• 毎回120回の書き込みで5分 ドメイン、メールボックス、エイリアスを横断。 読み込みはカウントされませんので、検証が無料になるまでドメインをポーリングします。 10つのドメインと30分のメールボックスを移動すると、合計で100の書き込みの下でうまくコストがかかるので、通常のバルク作業はこれに到達しません。
• 30個のメールボックスが1時間エクスポートされます。 エクスポートはメールボックス内のすべてのメッセージをストリームし、この API は最も高価なものです。

あなたが得る1つ以上 429 とりあう { "error": { "code": "rate_limited" } } そして、 Retry-After 秒単位のヘッダー。 すぐに再試行するのではなく、長く待つ:繰り返し限界を打つと、一時停止が長くなります。 正当な仕事がより多くのヘッドルームを必要とする場合, それを周りの作業ではなく、私たちに書きます; 私たちはむしろ、法案から調べるよりも数を上げます.

複数ドメインをまとめて移行

作品の注文: POST /domains それぞれの名前で、返すレコードを公開します。 GET /domains それぞれが検証されるまで、 POST /mailboxes アドレスごとに ドメインのみがDKIMレコードが証明されているので、メールはMXの切換前の古いホストからコピーすることができます POST /mailboxes/:id/import 実行するため、マイグレーションとスイッチオーバーは同じ日に発生する必要はありません。

MCPの特長

Agentic InboxはリモートMCPエンドポイントを提供します https://franklymail.com/api/agent/mcp メールボックスの読み込み、検索、準備の草案のため。 OAuthで接続する セットアップガイド. . . ドメインのプロビジョニングとメールボックスの管理は、上記の別の管理 HTTP API を使用します。