כתובות שליחה בשם באמצעות API ו-MCP

TrekMail מפריד בין שתי משימות שמשתמשות בפרטי גישה ובהרשאות שונים:

1. ממשק לוח הבקרה/Ops מנהל פרופילי SMTP לשימוש חוזר וניתוב דומיינים. הוא משתמש באסימון tm_live_ עם smtp:read או smtp:write.
2. ממשק דואר האינטרנט/הודעות מנהל את כתובות השולח הזמינות לתיבת דואר אחת ולתיבת דואר נכנס מחוברת אחת. הוא משתמש באסימון tm_msg_ עם messages:read, messages:write או messages:send.

ההפרדה מכוונת. אסימון תיבת דואר יכול לבחור נתיב שליחה שכבר אושר, אך אינו יכול לחשוף פרטי גישה ל-SMTP או לנהל תשתית של חשבון אחר.

בקצרה

• אם שולחים עם external_account_id בלבד, הנמענים רואים את הכתובת של החשבון המחובר ונעשה שימוש בשרת ה-SMTP שלו.
• אם שולחים גם identity_id שקשור למקור, הנמענים רואים את הכתובת העסקית של הזהות. TrekMail משתמש בנתיב הדומיין או בפרופיל SMTP השמור שהוקצה לזהות, ולאחר מכן שומר את העותק שנשלח בתיבה המחוברת.
• Starter מאפשר להגדיר ולהשתמש בכך בדואר האינטרנט. Pro ו-Agency מאפשרות גם להפוך זאת לאוטומטי דרך API או MCP. ב-Nano אין מקומות לחשבונות מחוברים.

כלי API ו-MCP הזמינים מתפתחים יחד עם המוצר. שליחה בשם משתמשת במשפחות SMTP וההודעות, וכל חיבור רואה רק את קבוצת המשנה שהתוכנית, ההרשאות והאישורים המאושרים שלו מאפשרים.

מודל הניתוב

כאשר external_account_id נשלח ללא identity_id, TrekMail שולח דרך שרת ה-SMTP של החשבון החיצוני ומשתמש בכתובת שלו.

כאשר שני הערכים נשלחים, TrekMail מתייחס לחשבון החיצוני כאל יעד תיבת הדואר הנכנס/נשלח ולזהות כאל כתובת השולח הגלויה + נתיב SMTP:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

הזהות והחשבון החיצוני חייבים להיות קשורים זה לזה. השמטת המקור או אספקת זהות מתיבת דואר אחרת מחזירה 422 identity_unavailable.

1. בדיקה או הגדרה של SMTP ב-API של לוח הבקרה

השתמשו באסימון Ops.

קריאת פרופיל לעולם אינה מחזירה את הסיסמה. endpoint השימוש הוא הדרך הבטוחה שבה סוכן יכול להסביר את ההשפעה לפני עריכה או מחיקה של פרופיל משותף.

כלי MCP: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. הצגת כתובות לתיבת הדואר הנכנס המדויקת

השתמשו באסימון הודעות:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

התגובה כוללת identities ייחודיות למקור, את כל external_identities שהוגדרו, sending_addresses, את send_as_domains המתאימים, את reply_from_policy של תיבת הדואר, ורק עבור תיבת הדואר של בעל החשבון, smtp_profiles שמורים שאפשר לבחור ישירות.

MCP: קראו אל list_identities עם external_account_id.

MCP מתארח לעומת stdio מקומי

לכלי הודעות יש הבדל חשוב אחד בין אמצעי התעבורה:

• MCP HTTP מתארח (OAuth): העבירו גם mailbox_id בכל קריאה לכלי הודעות. השרת המתארח משתמש בו כדי להנפיק אסימון הודעות קצר מועד לתיבת הדואר המדויקת. לדוגמה, קראו אל list_identities עם { "mailbox_id": 7, "external_account_id": 42 }.
• MCP stdio באירוח עצמי (tm_msg_): אל תעבירו mailbox_id. אסימון ההודעות הקבוע כבר קשור לתיבת דואר אחת, ולכן סכמת הכלי זקוקה רק ל-external_account_id.

external_account_id לעולם אינו מחליף את mailbox_id: הוא בוחר תיבת דואר נכנס מחוברת בתוך תיבת הדואר שכבר אושרה. כלי SMTP של לוח הבקרה נשארים מוגבלים לחשבון ואינם מקבלים mailbox_id באף אחד מאמצעי התעבורה.

3. יצירת זהות שליחה בשם

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email חייבת להיות כבר הכתובת הראשית של תיבת הדואר או כינוי פעיל שמורשה לשלוח. הדומיין שלה חייב להיות פעיל ובבעלות אותו חשבון. smtp_mode: domain פועל לפי נתיב הדומיין שהוגדר בלוח הבקרה. smtp_mode: profile מקבע את הזהות אל smtp_connection_id; בחירה ישירה בפרופיל מוגבלת לתיבת הדואר של בעל החשבון. חברות לא מאפשרת ליצור זהות send_as רגילה לכתובת המשותפת.

external_account_id הוא אופציונלי, וחשוב לדייק במשמעותו:

• כללו אותו כאשר אתם קוראים את הדואר של הכתובת דרך תיבת Gmail, Outlook או IMAP מחוברת. הזהות נקשרת אז לתיבה זו ואפשר להשתמש בה רק איתה.
• השמיטו אותו כאשר הדואר מועבר במקום זאת לתיבת TrekMail.

לעולם אי אפשר לצרף תיבת דואר נכנס אישית מחוברת לתיבת דואר משותפת: היא פרטית לאדם שחיבר אותה. השמיטו שם את external_account_id.

MCP: השתמשו ב-create_identity עם kind=send_as. ב-MCP מתארח, כללו את mailbox_id האב כמתואר לעיל.

4. שליחה, יצירת טיוטה, תזמון, תשובה או העברה

פעולות ההודעות הרגילות מקבלות את אותו זוג מקורות:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id נתמך בשליחה מיידית, בשמירה/עדכון של טיוטה ובשליחה מתוזמנת. הכנת תשובה/העברה מקבלת external_account_id ובוחרת את הזהות המתאימה מכותרות המסירה. הזהות שנבחרה מורשית מחדש כאשר הודעה בתור מופעלת בפועל; השבתת הכינוי, הדומיין, הפרופיל או החשבון המחובר שלה מפסיקה את המסירה במקום לעבור בשקט לכתובת שולח אחרת.

כלי MCP: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all ו-prepare_forward.

שליחה בשם תיבה משותפת

לשליחה מהתיבה המשותפת דרך Message API או MCP, החבר צריך קריאה וגם שליחה בשם. השתמשו באסימון שלו עם shared_mailbox_id. אסימון של התיבה המשותפת יכול לקרוא אך לא לשלוח.

{
  "shared_mailbox_id": 5,
  "to": ["customer@example.net"],
  "subject": "Re: your order",
  "body": { "text": "Answered by the team" }
}

האסימון נשאר משויך לחבר, וכך גם רישום הביקורת: שליחה מכתובת הצוות מתעדת מי ביצע אותה. GET /messages/identities?shared_mailbox_id=5 מציגה את הכתובות שמהן התיבה יכולה לשלוח.

שני סירובים צפויים:

• shared_mailbox_not_a_sender (403): האסימון עצמו משויך לתיבה משותפת. הקריאה אינה מושפעת, ורק השליחה דורשת חבר.
• shared_mailbox_send_denied (403): החבר צריך קריאה וגם שליחה בשם.

כתובות צוות מדואר האינטרנט האישי אינן מוצגות או מתקבלות כזהויות של Message API. דחיית identity_id מחזירה 422 identity_unavailable; שינוי או מחיקה של כתובת צוות מחזירים 422 identity_delegated. הדחיות כוללות hint ו־identity_id, וגם shared_mailbox_id ו־member_id כאשר הם זמינים. דחיית שליחה משותפת כוללת shared_mailbox_id, וגם member_id אם לחבר יש הרשאת שליחה בלבד. קראו את ההנחיה לפני ניסיון נוסף; השמטת ההקשר המשותף או הזהות שולחת מכתובת אחרת.

Message API יכול לתזמן עם shared_mailbox_id עבור חברים עם קריאה ו־שליחה בשם. הדואר בדפדפן לא מציע תזמון מתוך תיבה משותפת. להצגה, שינוי זמן או ביטול, העבירו את אותו shared_mailbox_id; השורות שייכות לתיבה המשותפת. השורה עצמה לא מציינת מי תזמן את ההודעה.

MCP: send_message, schedule_message ו-list_identities מקבלים shared_mailbox_id. ב-MCP המתארח mailbox_id נשאר החבר.

מדיניות תשובה

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient משיב מהכתובת שקיבלה את ההודעה כאשר הדבר אפשרי. default תמיד מתחיל מברירת המחדל של תיבת הדואר עבור דואר רגיל. MCP משתמש ב-set_reply_from_policy.

כללי בטיחות ובידוד

• פרטי גישה ל-SMTP לעולם אינם עוברים לתגובה של API ההודעות או MCP.
• כל חשבון חיצוני וכל זהות מוגבלים לתיבת הדואר של אסימון ההודעות.
• זהות שליחה בשם מחוברת זמינה לשימוש רק עם external_account_id המדויק שלה; זהות בבעלות תיבת הדואר זמינה רק בלעדיו.
• כתובת השולח חייבת להיות כבר מורשית ככתובת תיבת דואר או כינוי מורשה לשליחה; ה-API אינו יכול להמציא כתובות שולח שרירותיות.
• נדרש נתיב תקין לפני היצירה והוא נבדק שוב בזמן המסירה.
• כותרות Reply-To מותאמות אינן יכולות להתנגש עם הערך השמור בשדה השב אל של הזהות.
• שינויי זהות ופרופיל דרך MCP דורשים את הרשאת הכתיבה המתאימה. מנהל MCP שמתארח מקומית יכול לדרוש אישור מפורש לפעולות כתיבה; שליחה דורשת גם אישור לכל הודעה.

אין צורך במחרוזות הרשאה חדשות לאסימון. אסימוני smtp:* ו-messages:* קיימים ממשיכים לפעול בהתאם להרשאות הנוכחיות שלהם.

איזו מגבלת שליחה חלה?

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