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

פתחו את TrekMail ב-Claude, בחרו Connect, התחברו ואשרו גישה. אין צורך ליצור אסימון API. אפשר לבדוק הרשאות או לנתק דרך AI Agents & API → Tokens → Connected apps.

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

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

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

קריאת דואר עם מפתח אחד

בתוכניות Pro ו־Agency, בחרו קריאת דואר בעת יצירת מפתח API. ההרשאה המפורשת היא mailboxes:messages:read; ההרשאה mailboxes:read מציגה רק כתובות ופרטי התחברות. בחירת כל התיבות כוללת תיבות קיימות ועתידיות, ואפשר גם להגביל לדומיינים ותיבות מסוימים. מפתחות קיימים אינם מקבלים הרשאות חדשות אוטומטית.

השתמשו במפתח החשבון במסלולי GET שלהלן. שליחה, מחיקה ושינוי עדיין דורשים אסימוני הודעות והרשאות נפרדים. MCP המתארח מקבל OAuth, ולא tm_live_ או tm_msg_. שגיאת סוג האסימון מסבירה לסוכן איזה מסלול או אישור נדרש.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

בחירה ועריכה של הרשאות אפליקציה

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

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

• כל התוכניות, כולל 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 והרשאות תוכנית לפרטים על כל היקף.

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

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

• דומיינים נבחרים בלבד: האסימון ניגש לדומיינים שסימנתם ולשום דבר אחר. דומיין שתוסיפו בהמשך יישאר בחוץ עד שתערכו את האסימון ותסמנו אותו.
• כל הדומיינים (נוכחיים ועתידיים) למעט…: האסימון ניגש לכל הדומיינים חוץ מאלה שסימנתם, כולל דומיינים שיתווספו בהמשך. כך אפשר להרחיק את הסוכנים מהדואר של לקוח אחד בלי לערוך את האסימון בכל פעם שמוסיפים דומיין.

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

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

הנפקה מחדש של אסימון

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

1. עברו אל סוכני AI ו-API ← אסימונים ופתחו את הפרטים של האסימון.
2. לחצו על הנפקה מחדש.
3. בחרו מתי הסוד הישן יפסיק לעבוד: עכשיו, בעוד שעה, בעוד 24 שעות, בעוד 3 ימים או בעוד 7 ימים. הסוד הישן אף פעם לא עובד אחרי תאריך התפוגה של האסימון עצמו.
4. לחצו על הנפקה מחדש והעתיקו את הסוד החדש. כמו באסימון חדש, הוא מוצג פעם אחת בלבד.

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

אסימוני הודעות (tm_msg_...) שנוצרו עם הסוד הישן מפסיקים לעבוד באותו זמן. אפליקציה שיוצרת בעצמה אסימוני הודעות יכולה ליצור חדשים עם הסוד החדש. אם ייתכן שהסוד דלף, בחרו עכשיו.

ביטול אסימון

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, ואז צרו או אשרו פרטי כניסה עם ההיקף הנדרש.
• אסימון מואצל נעצר אחרי שינוי תפקיד: צמצום, השעיה או הסרה של גישת חבר מבטלים מיד את פרטי הכניסה המושפעים. צרו אסימון חדש אחרי שהבעלים ישחזרו את הגישה הנכונה.