יצירה וניהול של אסימוני API ב-TrekMail

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

מחברים לקוח MCP? אם הוא תומך באישור בדפדפן, הוסיפו את https://trekmail.net/mcp כשרת MCP מרוחק ואשרו את הגישה בדפדפן. בדרך כלל אין צורך ליצור או להדביק אסימון. אסימוני tm_live_ ידניים מיועדים לסקריפטים, משימות CI, MCP באירוח עצמי ולקוחות שאינם תומכים בתהליך הזה. ראו חיבור סוכני AI (MCP).

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

• כל התוכניות, כולל Nano, יכולות ליצור אסימוני API. תוכניות Nano מוגבלות להיקפי Email Verifier (verify:read, verify:write).
• תוכניות Starter מאפשרות היקפי תשתית לקריאה בלבד והיקפים מלאים של Drive ו-Email Verifier. אפשר לנהל העברה גם בלוח הבקרה, אך כתיבה להעברה באמצעות API (mailboxes:forwarding:write) דורשת Pro או Agency. תוכניות Pro ו-Agency פותחות את כל ההיקפים.
• הבעלים יכולים לנהל את כל פרטי הכניסה של החשבון. חבר מואצל בעל הרשאת אסימוני API יכול לנהל רק פרטים שיצר, ולהעניק רק היקפים ודומיינים שכבר כלולים בחברות שלו.
• טיפ: לחצו על התחלת סיור בדף סוכני AI ו-API לקבלת הסבר קצר על אפשרויות חיבור, אסימונים, יישומים מחוברים ויומן הביקורת.

יצירת אסימון אוטומציה של Drive

ה-API של Drive וכלי MCP משתמשים באסימוני תפעול (tm_live_...). בחרו רק את היקפי Drive הדרושים לתהליך:

• דיווח לקריאה בלבד: drive:account:read, drive:mailbox:read או drive:addon:read.
• אוטומציית העלאה: הוסיפו drive:account:write או drive:mailbox:write.
• קישורי מסירה ציבוריים: הוסיפו drive:account:share או drive:mailbox:share.
• ניקוי קבוע: השתמשו ב-drive:account:purge או ב-drive:mailbox:purge רק באסימון נפרד ומבוקר היטב.

רכישה, שינוי גודל וביטול של תוסף Drive אינם זמינים באמצעות אסימוני API. סוכנים יכולים לקרוא את מצב התוסף ומחירו בעזרת drive:addon:read, אך שינויי המינוי נשארים בלוח הבקרה.

יצירת אסימון אוטומציה של White Label

White Label משתמש בחמישה היקפי אסימון תפעול: branding:read, branding:write, members:read, members:write ו-activity:read. הם מופיעים רק כל עוד לחשבון יש גישת White Label. ההיקף members:write מסומן כמסוכן מפני שהוא יכול להסיר גישה ולבטל מפתחות של אדם אחר.

לשילוב מצב וביקורת לקריאה בלבד, בחרו branding:read, members:read ו-activity:read. הוסיפו branding:write רק להגדרת המותג וה-DNS. הוסיפו members:write רק כשהאוטומציה חייבת להזמין או לשנות אנשים.

במהלך תקופת החסד לביטול, הבעלים שומרים את שלושת היקפי הקריאה לשחזור, ואילו כתיבה ופרטי White Label מואצלים מפסיקים לעבוד. הפעלה מחדש אינה משחזרת פרטים שבוטלו; צרו או אשרו פרטים חדשים.

יצירת אסימון

1. עברו אל סוכני AI ו-API ← אסימונים.
2. לחצו על יצירת אסימון.
3. מלאו את הטופס:
   • שם: תווית לזיהוי האסימון (לדוגמה, "סוכן Claude", "צינור CI/CD").
   • תפוגה: בחרו 7 ימים, 30 ימים, 90 ימים, תאריך מותאם או ללא תפוגה.
   • היקפים: בחרו את הפעולות שהאסימון יכול לבצע. כל ההיקפים המותרים מסומנים כברירת מחדל.
   • מגבלת דומיין: בחרו "כל הדומיינים" או דומיינים מסוימים כדי להגביל את גישת האסימון.
4. לחצו על יצירת אסימון.

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

אי אפשר להציג שוב את האסימון. שמרו אותו בבטחה לפני סגירת האישור.

יצירת אסימון הודעות

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

כדי ליצור אסימון הודעות, הסוכן קורא:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

בחרו את ההיקפים המצומצמים ביותר הדרושים לתהליך:

האסימון הגלוי (tm_msg_...) מוחזר פעם אחת. הוסיפו אותו לתצורת MCP בשם TREKMAIL_MESSAGE_TOKEN.

אסימוני הודעות זמינים בתוכניות Pro ו-Agency. אסימון התפעול חייב לכלול את ההיקף mailboxes:message-tokens:manage.

לתיבת Gmail מחוברת או תיבה חיצונית אחרת, השתמשו ב-external_account_id. כדי שנמענים יראו כתובת עסקית מורשית, השתמשו גם ב-identity_id שמחזיר endpoint הזהויות. ראו כתובות שליחה בשם באמצעות API ו-MCP.

מבנה האסימון

TrekMail משתמשת בשתי קידומות כדי להבדיל בין סוגי אסימונים:

8 התווים הראשונים אחרי הקידומת נשמרים כקידומת גלויה בלוח הבקרה לזיהוי קל.

היקפים

היקפים קובעים מה האסימון יכול לעשות. האפשרויות תלויות בתוכנית:

• Nano: Email Verifier בלבד (verify:read, verify:write). הוספת Drive Storage מעניקה לחשבון גם את יכולות Drive API ו-MCP שהוא זכאי להשתמש בהן.
• Starter: גישה מלאה ל-Drive ול-Email Verifier וגישה לקריאה בלבד לכל השאר (דומיינים, תיבות, העברה, מסנני דואר, מענה אוטומטי, העברות, כרטיסים, SMTP, Cloudflare). השתמשו בלוח הבקרה לפעולות כתיבה ש-Starter אינו חושף דרך ה-API, כגון יצירת העברות, מענה לכרטיסים או שינוי מענה אוטומטי.
• Pro ו-Agency: גישה מלאה. קריאה, כתיבה, יצירה ומחיקה בכל המשפחות, וכן אסימוני הודעות לקריאת דואר ושליחתו דרך ה-API.

היקפי White Label הם זכאות של התוסף ולא דרך לעקוף את טבלת התוכניות. הם מוצעים רק כש-White Label פעיל; הבעלים שומרים גישת שחזור לקריאה בלבד בתקופת החסד לביטול.

ראו היקפי API והרשאות תוכנית לפרטים על כל היקף.

מגבלות דומיין

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

1. בחרו דומיינים נבחרים באזור מגבלת הדומיין.
2. סמנו את הדומיינים שאליהם האסימון צריך לגשת.

אסימון מוגבל יקבל תגובות 404 בניסיון לגשת למשאבים בדומיינים אחרים; ה-API יתנהג כאילו הדומיינים אינם קיימים.

ביטול אסימון

1. עברו אל סוכני AI ו-API ← אסימונים.
2. מצאו את האסימון ברשימה.
3. לחצו על ביטול.
4. אשרו את הביטול.

אסימונים שבוטלו מפסיקים לעבוד מיד. כל בקשת API שמשתמשת באסימון שבוטל מקבלת 401 Unauthorized.

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

מצב האסימון

לאסימונים שלושה מצבים:

השתמשו במסנן המצב בדף האסימונים להצגת אסימונים לפי מצב.

נתיב ביקורת

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

פתרונות מהירים

• "היקפים אינם זמינים בתוכנית": התוכנית אינה כוללת אותם. Nano מוגבלת ל-verify:read ול-verify:write (הוסיפו Drive Storage כדי לקבל גם היקפי drive:*). Starter מוסיפה גישת קריאה בכל משפחות התשתית לצד Drive ו-Email Verifier מלאים. Pro ו-Agency פותחות כתיבה בכל מקום.
• האסימון הגלוי אבד: אי אפשר לשחזר אותו. בטלו אותו וצרו חדש.
• האסימון פועל אך מחזיר 404 לדומיינים מסוימים: כנראה קיימת מגבלת דומיין. בטלו וצרו אותו מחדש עם "כל הדומיינים", או הוסיפו את הדומיינים החסרים למגבלה.
• היקף White Label מחזיר scope_blocked_by_entitlement: הפעילו מחדש את White Label, ואז צרו או אשרו פרטי כניסה עם ההיקף הנדרש.
• אסימון מואצל נעצר אחרי שינוי תפקיד: צמצום, השעיה או הסרה של גישת חבר מבטלים מיד את פרטי הכניסה המושפעים. צרו אסימון חדש אחרי שהבעלים ישחזרו את הגישה הנכונה.