חשבונות מחוברים דרך API ו-MCP

חשבונות מחוברים מאפשרים לתיבת דואר אינטרנט לקרוא ולשלוח הודעות מתיבות חיצוניות, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 או כל שרת IMAP. ה-API להודעות וכלי MCP מספקים את אותה יכולת באופן תכנותי: אפשר להציג, להוסיף, לבדוק, לערוך ולהסיר חשבונות מחוברים, וגם להפנות קריאות רגילות של הודעות (הצגה, קריאה, שליחה, דגלים, העברה, מחיקה ותיקיות) לחשבון מחובר במקום לתיבה של האסימון עצמו.

במילים פשוטות: mailbox_id בוחר את תיבת TrekMail שהסוכן רשאי לפעול בשמה, ואילו external_account_id בוחר את Gmail או תיבה מחוברת אחרת בתוכה. לא ניתן להחליף ביניהם.

תוכניות, מגבלות וגודל הקטלוג

ניהול חשבונות מחוברים מספק שבעה כלי הודעות. אסימון מוגבל הרשאות רואה רק את הכלים שבהם הוא יכול להשתמש בפועל, ולא את קטלוג המוצר המלא.

לפני שמתחילים

• חשבונות מחוברים הם תכונת דואר אינטרנט ומשתמשים בממשק של אסימון ההודעות (/api/v1/messages/...), שמורשה באמצעות אסימון הודעות עם ההרשאות שלהלן, ולא באמצעות אסימון API של לוח הבקרה.
• מגבלות התוכנית חלות על כל תיבה: Starter 5, Pro 10, Agency 30. תוכנית Nano אינה כוללת חשבונות מחוברים.
• כל endpoint מוגבל לתיבה של האסימון עצמו. אסימון יכול לראות ולנהל רק את החשבונות המחוברים שלו, ולעולם לא חשבונות של תיבה אחרת.
• פרטי גישה ואסימוני OAuth תמיד מוסתרים בתגובות. אפשר להזין סיסמה או סיסמת יישום, אך לעולם אי אפשר לקרוא אותה בחזרה.
• חשבונות Outlook.com ו-Microsoft 365 מתחברים באמצעות כניסה ל-Microsoft ‏(OAuth) בממשק דואר האינטרנט. ה-API יכול לנהל ולהשתמש בהם לאחר החיבור, אך אינו מבצע את שלב ההסכמה האינטראקטיבי של Microsoft.

הרשאות

הפניית קריאת הודעות לחשבון מחובר דורשת את אותה הרשאה שכבר נדרשת לקריאה (לדוגמה, הצגת ההודעות שלו דורשת messages:read, ושליחה דורשת messages:send).

ניהול חשבונות מחוברים

נתיב בסיס: /api/v1/messages/external-accounts

הוספת חשבון

POST /api/v1/messages/external-accounts
Scope: messages:write

גוף הבקשה:

קראו תחילה אל POST /external-accounts/detect כדי למלא אוטומטית את provider ואת הגדרות השרת. קריאת האחסון מבצעת בדיקת IMAP + SMTP אמיתית לפני השמירה. תגובת 422 עם קטגוריית שגיאה (auth, tls, network, transient_throttle) פירושה שפרטי הגישה לא פעלו ושום דבר לא נשמר.

הפניית קריאות הודעות לחשבון מחובר

כל endpoint של הודעות שפועל על תיבה מקבל external_account_id אופציונלי. ספקו אותו כדי להפעיל את הקריאה על אותו חשבון מחובר במקום על התיבה של האסימון עצמו; השמיטו אותו כדי להשתמש בתיבה עצמה. הדבר חל על הצגה, קריאה, שליחה, תשובה, דגלים, העברה, מחיקה והצגת תיקיות.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

שליחה עם external_account_id בלבד יוצאת דרך שרת ה-SMTP של אותו חשבון (עם SPF/DKIM של הספק שלו). אספקת identity_id הקשור למקור במקום זאת משתמשת בדומיין או בנתיב הפרופיל השמור של זהות השליחה בשם, ועדיין שומרת את העותק שנשלח בתיבה המחוברת. החשבון חייב להיות תקין (status: active); חשבון מנותק מחזיר שגיאה שמבקשת לחבר אותו מחדש. ראו כתובות שליחה בשם דרך API ו-MCP.

כלי MCP

אותה יכולת זמינה לסוכני AI דרך MCP (גם בשרת stdio הפרטי וגם בשרת MCP הציבורי):

כלי ההודעות list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all ו-prepare_forward מקבלים את הארגומנט האופציונלי external_account_id. שליחה, יצירת טיוטות ותזמון מקבלים גם identity_id שקשור למקור ומוחזר על ידי list_identities.

מכיוון שכלי הניהול פותחים חיבורים יוצאים לשרתי דואר שרירותיים באמצעות פרטי גישה שסיפק המשתמש, הם פועלים לפי אותה מדיניות אבטחה כמו שאר תכונת החשבונות המחוברים: רשימת מארחים מורשים, חסימת טווחים פרטיים, רשימת יציאות מורשות ומגבלות חיבור לכל מארח.