סקירת TrekMail REST API למפתחים

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

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

TrekMail API מאפשר לכם לנהל דומיינים, תיבות דואר, העברה, DNS, העברות דואר ופעולות Webmail מתוך לקוח HTTP או סוכן AI. האפשרויות כוללות קריאה ושליחה של דואר, טיוטות, תזמון, תיקיות, אנשי קשר, לוחות שנה, זהויות, תבניות ושולחים חסומים. בקשות מאומתות משתמשות באסימון Bearer, התגובות הן JSON, ופעילות ה-API מתועדת לביקורת.

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

בתוכניות 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}

מה מקבלים

• REST API v1 עם תבנית בקשה ותגובה של JSON.
• אימות באמצעות אסימון Bearer: ללא קובצי Cookie או הפעלות עבור קריאות API מאומתות.
• מפתחות אידמפוטנטיות בפעולות הכתיבה שדורשות אותם, למניעת עבודה כפולה במהלך ניסיונות חוזרים.
• הגבלת קצב לכל אסימון עם כותרות Retry-After.
• יומן ביקורת שמוצג בלוח הבקרה תחת סוכני AI ו-API, יומן ביקורת.
• שרת MCP עם קטלוג שמסונן לפי פרטי האימות, התעבורה והגדרות הבטיחות של החיבור הנוכחי. לכן חיבור פרויקט מצומצם רואה רק את הכלים שבהם הוא יכול להשתמש.
• כינויי דומיין: חברו כתובות לקבלה בלבד בדומיין משני לאותם חלקים מקומיים בדומיין ראשי, עם מצבי מסירה שמורים לעומת פעילים והסרה בטוחה. ראו כינויי דומיין באמצעות API ו-MCP.
• ארכיטקטורה של שני אסימונים: אסימוני ops נפרדים לתשתית ואסימוני message לפעולות דואר מלאות כגון קריאה, שליחה, יצירת טיוטות, תזמון, אנשי קשר, לוחות שנה, זהויות, תבניות ותיקיות.
• תובנות על עבירות משלוח והחזרות: משכו מלוח הבקרה את הסיכום של הודעות שנשלחו, נמסרו, חזרו בהחזרה קשיחה או רכה, יחד עם קודי SMTP ותגובות לכל נמען. ראו עבירות משלוח והחזרות.
• סיסמאות אפליקציה לדואר: נהלו סיסמאות נפרדות ל-IMAP, ל-SMTP, ליומנים ולאנשי קשר, וקבעו אילו סיסמאות אפליקציות דואר יקבלו. הן אינן מחליפות אסימוני Bearer של ה-API או אסימוני Message API. ראו סיסמאות אפליקציה לדואר באמצעות API ו-MCP.
• שימוש באחסון תיבת הדואר: list_mailboxes ו-get_mailbox מחזירים used_mb, quota_mb, allocation_mb ו-is_pooled, כדי שסוכן יוכל לזהות תיבות דואר שמתקרבות למגבלה בלי גישה ללוח הבקרה.
• ניהול מותג לבן: בדקו את ההגדרה, נהלו מיתוג לכל דומיין, הזמינו לקוחות, שלטו בתפקידים ובדומיינים, השעו או שחזרו גישה ובדקו פעילות באמצעות API או MCP. ראו את מדריך המיתוג ואת מדריך ניהול הצוות.

Drive API ואוטומציית קבצים

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

Drive משתמש באחד עשר היקפים של אסימון ops: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read ו-drive:devices:write. פעולות חיוב עבור תוסף Drive, רכישה, שינוי נפח וביטול נשארות זמינות רק בלוח הבקרה ואינן נחשפות כפעולות כתיבה של API או MCP.

התחילו עם סקירת Drive API או עם המדריך המהיר ל-Drive API.

ארכיטקטורה של שני אסימונים

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

לאסימוני ops ולאסימוני message יש היקפים נפרדים ומגבלות קצב נפרדות. סוכן יחיד יכול להשתמש בשני האסימונים בו זמנית באמצעות הגדרתם בסביבת שרת ה-MCP.

אסימוני Message זמינים בתוכניות Pro ו-Agency.

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

• לכל התוכניות יש גישה ל-API:
  • Nano: Email Verifier. הוסיפו תוסף Drive Storage לקבלת גישה מלאה ל-Drive API ול-MCP.
  • Starter: גישה מלאה ל-Drive ול-Email Verifier וגישה לקריאה בלבד בכל שאר אזורי התשתית. השתמשו בלוח הבקרה לפעולות הכתיבה באזורים אלה.
  • Pro / Agency: גישה מלאה ל-API הבסיסי, כולל אסימוני message. היקפי מותג לבן נוספים כל עוד תקופת הניסיון או התוסף בתשלום פעילים.
• מחברים סוכן AI? הוסיפו את https://trekmail.net/mcp כשרת MCP מרוחק בכל לקוח תואם. אם הוא תומך באימות דפדפן, אין צורך באסימון ידני. ראו חיבור סוכני AI ‏(MCP) לאפשרויות מרוחקות, CLI/שולחן עבודה, גשר ואירוח עצמי.
• כותבים שילוב משלכם? צרו אסימון tm_live_ תחת סוכני AI ו-API, אסימונים, יצירת אסימון ושלחו אותו בתור Authorization: Bearer …. ראו יצירה וניהול של אסימוני API.
• חדשים ב-API? לחצו על התחלת הסיור בחלק העליון של דף סוכני AI ו-API לסיור קצר בשיטות החיבור, ניהול אסימונים, יישומים מחוברים ויומן הביקורת.

כיצד האימות פועל

כל בקשה חייבת לכלול את האסימון בכותרת Authorization:

Authorization: Bearer tm_live_abc123...

אסימוני Ops מתחילים ב-tm_live_ ואסימוני message מתחילים ב-tm_msg_. שניהם מוצגים פעם אחת בעת היצירה ואי אפשר להציגם שוב.

אם האסימון חסר, בוטל או פג תוקף, ה-API מחזיר 401 עם קוד השגיאה unauthenticated.

כתובת URL בסיסית וניהול גרסאות

כל נקודות הקצה נמצאות תחת:

https://trekmail.net/api/v1

כתובת ה-URL הבסיסית מוצגת בלוח הבקרה סוכני AI ו-API תחת עיון מהיר. הגרסה נמצאת בנתיב ה-URL. אם אי פעם תוצג v2, ‏v1 תמשיך לפעול.

תבנית תגובה

תגובות מוצלחות מחזירות JSON עם מפתח data עבור משאב יחיד או רשימה מחולקת לעמודים:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

תגובות שגיאה משתמשות במבנה עקבי:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

מזהי בקשות

כל תגובה כוללת כותרת X-Request-Id. תוכלו גם להעביר מזהה משלכם באמצעות X-Request-Id בבקשה. הוא יוחזר אליכם ויירשם ביומן הביקורת.

מגבלות קצב

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

לפעולות הרסניות (כוונות מחיקה) יש מגבלה יומית נוספת לכל אסימון ותקופת המתנה בין מחיקות רצופות.

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

אסימוני Message משתמשים במגבלות נפרדות. ערכי ברירת המחדל הם 30 בקשות קריאה לדקה לכל אסימון, 60 בקשות שליחה לדקה לכל אסימון, 5,000 קריאות מוצלחות ביום לכל אסימון ו-100 שליחות API ביום בתיבת דואר אחת. מונה בטיחות שליחה שני מוגדר כברירת מחדל ל-500 ביום לכל אסימון; התקרה הנמוכה יותר לתיבת הדואר חלה בדרך כלל ראשונה. אמצעי ההגנה האלה של ה-API אינם מחליפים את מגבלות ה-SMTP המנוהל של התוכנית או את המגבלות של ספק חיצוני.

אידמפוטנטיות

נקודות קצה שמשנות מצב ומסומנות כאידמפוטנטיות דורשות כותרת Idempotency-Key. הדרישה חלה על יצירות, עדכונים, שליחות ומחיקות שבהם ניסיון חוזר אוטומטי עלול ליצור עבודה כפולה. פעולות POST שדומות לקריאה, כגון זיהוי ספק או בדיקת חיבור, אינן דורשות אותה; בדקו את טבלת נקודות הקצה או את מפרט OpenAPI. אם תשלחו את אותו מפתח עם אותו גוף, ה-API ישחזר את התגובה המקורית בלי ליצור כפילויות. שליחת הודעות היא החריג אחרי שהמסירה נכשלה (למשל בגלל מכסת שליחה): ה-API כבר לא משחזר את ה-202 הקודם, כך שאפשר לשלוח את אותה הודעה שוב מאוחר יותר עם אותו תוכן. אם אתם מעבירים מזהה משלכם ב-X-Request-Id, השתמשו במזהה חדש לניסיון הזה: ה-API מתייחס גם לשליחה מאותה תיבת דואר עם אותו X-Request-Id כחזרה, ולכן עם המזהה הישן תקבלו רק את המסירה המקורית שנכשלה, ושום דבר לא יישלח. ניסיון חוזר לשליחה שעדיין ממתינה או שכבר נמסרה עדיין מקבל את התגובה המקורית.

Idempotency-Key: create-mailbox-alice-2024

אם תשלחו את אותו מפתח עם גוף שונה, ה-API יחזיר 409 Conflict.

הקצאת אחסון לתיבות דואר

כל נקודת קצה שיוצרת תיבת דואר או הזמנה, POST /api/v1/mailboxes, ‏/api/v1/mailboxes:bulk, ‏/api/v1/mailboxes/invites, ‏/api/v1/mailboxes/invites:bulk, מקבלת מספר שלם אופציונלי storage_allocation_mb.

ההקצאות מאומתות מול המאגר הפעיל בניכוי תיבות דואר ייעודיות קיימות והזמנות ייעודיות שממתינות. נקודות קצה בכמות גדולה בודקות כל פריט עם הקצאה ייעודית מול מה שנותר ברגע יצירתו: מה שנכנס נוצר, ומה שכבר לא נכנס נכשל בנפרד עם הסיבה storage_pool_exceeded (207 הצלחה חלקית, או 422 כשכל הפריטים נכשלים). בדומיין עם מגבלת אחסון של לקוח ב-White Label, גודל קבוע חייב להיכנס גם במה שנותר מהמגבלה הזו: יצירה או הזמנה בודדת מחזירה 422 client_storage_limit_exceeded עם limit_mb, allocated_mb, available_mb ו-requested_mb בתוך details (מפתח שמוגבל לחלק מהדומיינים מקבל רק את available_mb ו-requested_mb כשהמגבלה חלה גם על דומיין מחוץ לטווח שלו), ופריט בכמות גדולה נכשל עם הסיבה client_storage_limit_exceeded. המאגר מתרענן כאשר תיבת דואר ייעודית נמחקת, כאשר הזמנה ממומשת (ההקצאה עוברת לתיבת הדואר החדשה), וכאשר הזמנה ממתינה פגת תוקף.

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

כדי לשנות תיבת דואר קיימת, שלחו PATCH /api/v1/mailboxes/{id}/storage עם storage_allocation_mb שמוגדר לגודל קבוע ב-MB, או ל-null עבור אחסון משותף. הבקשה דורשת mailboxes:write ו-Idempotency-Key, עובדת על תיבות פעילות ומושהות, ומבצעת את אותן בדיקות כמו עריכת אחסון בלוח הבקרה: storage_pool_exceeded כשהמקום הפנוי בחשבון לא מספיק, ובדומיין עם מגבלת אחסון של לקוח client_storage_limit_exceeded, או client_storage_below_usage כשהגודל החדש קטן ממה שהתיבה כבר מאחסנת. אחסון משותף אף פעם לא נדחה בגלל הגודל שלו. תיבה שנמצאת בנמחקו לאחרונה או בתהליך מחיקה מחזירה 422 mailbox_unavailable. כלי ה-MCP הוא set_mailbox_storage.

מגבלות אחסון של לקוחות ב-White Label נמצאות תחת /api/v1/white-label/client-limits; ראו ניהול צוותי מותג לבן באמצעות API ו-MCP. מפתח שמוגבל לחלק מהדומיינים רואה ב-GET /api/v1/account רק את החלק שלו בחשבון: usage סופר רק את הדומיינים ותיבות הדואר שלו, limits.max_storage_mb הוא המגבלה של הלקוח כשכל הדומיינים שלו חולקים מגבלה אחת שלא חלה על אף דומיין אחר, ו-client_limit מכיל את המגבלה הזו (id, storage_limit_mb, allocated_mb, used_bytes) או null. שאר מבצעי הקריאות מקבלים את התגובה ללא שינוי.

תיבות דואר רגילות חדשות, כולל יצירה בכמות גדולה, הזמנות ויצירה בידי סוכני AI, פועלות לפי הגדרות חשבון > תיבות דואר חדשות > אפליקציות דואר צריכות סיסמאות אפליקציה, שמופעל כברירת מחדל. שינוי ההגדרה אינו משנה תיבות קיימות. ב-POST /api/v1/mailboxes אפשר לבחור client_auth_mode של app_password_only או password_or_app_password; אם השדה מושמט, הגדרת החשבון חלה. משאבי הרשימה והפרטים של תיבות הדואר מחזירים client_auth_mode ו-app_passwords_count (סיסמאות אפליקציה פעילות). לתיבות משותפות אין סיסמאות אפליקציה או מצב כניסה משלהן.

ששת כלי ה-MCP לניהול סיסמאות אפליקציה הם list_mailbox_app_passwords, create_mailbox_app_password, rotate_mailbox_app_password, revoke_mailbox_app_password, set_mailbox_client_auth_mode, update_account. update_account: קביעת new_mailbox_client_auth_mode לתיבות עתידיות; תיבות קיימות שומרות על המצב שלהן. נדרשים mailboxes:write, אסימון או מחבר של בעל החשבון ללא מגבלות משאבים, ו-TREKMAIL_ALLOW_DESTRUCTIVE=true ב-stdio באירוח עצמי.

גישת Drive לתיבות דואר

לכל תיבת דואר יש רמת drive_access שקובעת לאילו חלקים של Drive יכול המשתמש בה להגיע ב-Webmail. היא מוחזרת במשאב תיבת הדואר וניתן להגדיר אותה עם PATCH /api/v1/mailboxes/{id}, או עבור תיבות דואר רבות יחד, עם POST /api/v1/mailboxes:drive-access.

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

השעיית כניסה לתיבת דואר

אפשר להשעות את הכניסה לתיבת דואר בזמן שהיא ממשיכה לקבל דואר: Webmail, ‏IMAP, ‏SMTP וסיסמאות מכשירים נדחים והפעלות פתוחות מסתיימות, אך המסירה אינה נפגעת, כך ששום דבר לא חוזר וכל ההודעות ממתינות כאשר הכניסה משוחזרת. הגדירו זאת עם POST /api/v1/mailboxes/{id}:suspend-login (ועם :resume-login), או עבור תיבות דואר רבות עם POST /api/v1/mailboxes:login-access.

משאב תיבת הדואר מדווח על כך בתור login_suspended, ‏login_suspended_at ו-login_suspended_reason. קראו את login_suspended כדי לדעת אם האדם יכול להיכנס, ואת status כדי לדעת אם תיבת הדואר עצמה פועלת. תיבת דואר שהכניסה אליה מושעית נשארת active, משום שהיא עדיין מקבלת דואר. :pause הוא מצב אחר: הוא מגדיר את status ל-disabled וגם עוצר את המסירה.

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

ראו השעיית כניסה לתיבת דואר באמצעות API.

נקודת הקצה בכמות גדולה מקבלת בורר אחד בדיוק, mailbox_ids, ‏domain_id או all, ומחזירה את הפעולה שביצעה:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

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

תיבות דואר משותפות נדחות בנקודת הקצה היחידה עם 422 drive_access_not_applicable ומדולגות (ונספרות) בנקודת הקצה בכמות גדולה: אין להן משתמש Webmail משלהן, ולכן חברים פותחים אותן עם הרמה שלהם וערך שנשמר בשורה המשותפת לא ישנה דבר.

ההגבלה חלה על ה-API וגם על הממשק. מרחב ה-Drive של תיבת דואר מוגבלת אינו מופיע ב-GET /api/v1/drive/spaces, הקבצים שלה משיבים 404 לפי מזהה, ואי אפשר ליצור עבורה מכשיר סנכרון.

כתובות העברה

GET /api/v1/domains/{id}/forwarding-addresses מחזיר יותר מהרשימה, מפני ששני פרטים על כתובת העברה אינם נראים בכתובת עצמה:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max הוא לכל דומיין ותלוי בתוכנית: 100 ב-Pro, ‏300 ב-Agency ו-25 כללים שמורים אך לא פעילים ב-Nano או Starter.
• delivery.active מציין אם הכללים האלה מעבירים דואר ברגע זה. הוא false בתוכנית שמתחת ל-requires_plan, ו-false כל עוד paused_until מוגדר (החשבון עבר את קצב השליחה השעתי שלו; ראו מגבלות שליחה לפי תוכנית). כלל יכול להיות is_active: true ועדיין לא למסור, לכן קראו את delivery, ולא רק את is_active, לפני שתדווחו שההעברה פועלת.

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

דחיות חוזרות בתור 422 כאשר error.code מוגדר ל-validation_error או ל-limit_exceeded: כתובת שכבר נמצאת בשימוש בדומיין, נמען באותו דומיין (שייצור לולאה), דומיין נמען ללא MX תקין, או תקציב מלא לכל דומיין.

פעולות POST ו-DELETE בנקודות קצה אלה דורשות Idempotency-Key; ‏PATCH אינה דורשת אותו.

היסטוריית מסירה

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log מחזיר את מה שקרה בפועל לדואר אחרון, מהחדש לישן:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome הוא אחד מתוך delivered, ‏deferred (כשל זמני, עדיין מנסה שוב), failed (שרת הנמען דחה אותו) ו-blocked. האחרון מציין שמסנן ה-spam שלנו עצר את ההודעה לפני ההעברה, כך שהיא כלל לא הגיעה לנמען. טיפול ב-blocked כהחזרה יגרום למישהו לחפש בעיה בשרת המקבל אף שהיא התרחשה אצלנו.

limit (מ-1 עד 200, ברירת מחדל 100) הוא הפרמטר היחיד. החלון הוא תקופת השמירה של התוכנית, 30 יום ב-Agency ו-7 בשאר התוכניות, ואין נתונים ישנים יותר שאפשר לבקש משום שאירועי העברה נמחקים.

תיבות דואר משותפות (צוות)

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

GET /api/v1/mailboxes ו-GET /api/v1/mailboxes/{id} מחזירים כעת mailbox_type ("user" או "shared") וערך בוליאני is_shared; תיבות דואר משותפות כוללות גם shared_member_count. השתמשו בשדות האלה כדי להבחין בין תיבת צוות לתיבה רגילה לפני קריאה לנקודות הקצה של חברים.

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

שינוי הרשאות עשוי להחזיר 422 no_access_left אם שתיהן יהיו כבויות, 422 send_only_disabled אם השינוי המבוקש בהרשאת קריאה אינו זמין, או 422 last_reader אם הקורא הפעיל האחרון יאבד גישה. השתמשו ב־הסר להסרת כל הגישה ותנו הרשאת קריאה לחבר פעיל אחר לפני הסרת הקורא האחרון. כל אחת מהשגיאות האלה מחזירה גם shared_mailbox_id, את member_id עבור חבר קיים, ו־hint שמציין את הבקשה שמתקנת את הבעיה.

נקודות הקצה של חברים משתמשות מחדש בהיקפים הקיימים mailboxes:read / mailboxes:write. אין היקף נפרד לתיבת דואר משותפת.

כדי לגלות גישה מקורית מאפליקציות דואר, קראו ל-GET /api/v1/mailboxes/{member_mailbox_id}/client-setup עבור תיבת דואר רגילה של חבר. האובייקט shared_mailboxes שלה מדווח על מוכנות מקורית מתמשכת, מוכנות וסיבה בפועל של שליחה בשם, נתיבים מדויקים של Inbox/Sent/Archive/Junk ופעולות מותרות. can_send היא הרשאת שליחה בשם שהוקצתה, ולא הוכחה לכך ש-SMTP מוכן כעת. נקודת הקצה לעולם אינה מחזירה סיסמה. קריאה עם מזהה תיבת הדואר המשותפת מחזירה 422 direct_login_unavailable, משום שהכתובת המשותפת אינה יכולה לבצע אימות ישיר.

shared_mailboxes.items[] כוללת רק חברויות עם הרשאת קריאה כאשר הגישה לתיקיות ביישומי דואר מופעלת. delegated_send_addresses היא רשימה נפרדת של כתובות זמינות לצוות בשדה מאת עם id, email ו־display_name; היא יכולה להיות ריקה. היא אינה נותנת גישה לתיקיות ואינה בדיקת מוכנות לשליחה. כתובות אלה אינן זהויות Message API. השתמשו בשרתים שהוחזרו, גם ב־White Label, במקום להעתיק שם שרת של הפלטפורמה.

הסרת חבר, שינוי can_read / can_send או המרת תיבת דואר משותפת לרגילה מסנכרנים הרשאות שרת דואר כאשר גישה מקורית מופעלת. תגובת 503 native_access_sync_failed ניתנת לניסיון חוזר ומבטיחה שהחברות, ההרשאה או סוג תיבת הדואר נשארו ללא שינוי במקום להחיל את הפעולה באופן חלקי.

נקודות קצה זמינות

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

נקודות הקצה של Cloudflare משתמשות באותו תהליך כמו לוח הבקרה: מאמתים אסימון, מציגים אזורים, מחברים דומיינים, מציגים תצוגה מקדימה של שינויי ה-DNS ואז מחילים אותם. גם /cloudflare/preview וגם /cloudflare/apply מקבלות שתי בקרות אופציונליות לכל דומיין:

• included_records, רשימת היתרים של הרשומות שבהן מותר לגעת, לפי מזהה דומיין: { "123": ["mx_primary", "spf_record"] }. רשומות שלא נכללות מדולגות, כך שאפשר להחיל רק MX ו-SPF ולחזור ל-DKIM מאוחר יותר. השמיטו את השדה כדי להחיל כל רשומה.
• confirmed_conflicts, כאשר התצוגה המקדימה מסמנת רשומה שכבר קיימת עם ערך אחר, ציינו כאן את מזהה הרשומה שלה (באותה תבנית { domain_id: [record_ids] }) כדי לאשר את החלפתה.

מזהי הרשומות (mx_primary, ‏spf_record, ‏dkim_primary, ‏dmarc_main, ‏…) מגיעים ישירות מתגובת התצוגה המקדימה, ולכן סוכן טיפוסי קורא תחילה לתצוגה המקדימה ומעביר ל-apply את המזהים הרצויים:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

ניתוב SMTP לכל דומיין וברירת המחדל של החשבון

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

נקודות קצה לכל דומיין (smtp:read / smtp:write):

כמה הערות על גוף הנתיב:

• smtp_mode=platform בוחר שליחה מנוהלת; smtp_mode=profile דורש smtp_connection_id; ‏not_configured מנקה את הנתיב.
• smtp_mode=inherit גורם לדומיין לעקוב בזמן אמת אחר ברירת המחדל של החשבון. בכל שינוי של ברירת המחדל, גם דומיין זה משתנה איתה. ממשק ה-Web תמיד כותב נתיבים מפורשים, אך צד השרת עדיין תומך ב-inherit, ולכן GET מחזיר את effective_smtp_mode שמראה למה inherit נפתר כעת.
• הנתיב הזה משנה רק את הדומיין שלו. כדי להפוך נתיב לברירת המחדל של החשבון (הגדרה כברירת המחדל של החשבון בלוח הבקרה), השתמשו ב-PUT /api/v1/smtp/default שבהמשך; הוסיפו apply_to_all: true כדי להעביר אליו גם את כל הדומיינים (החלה על כל הדומיינים).

נקודות קצה לברירת המחדל של כל החשבון (smtp:read / smtp:write):

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

מפתח שמוגבל לחלק מהדומיינים או מתיבות הדואר מקבל 403 token_resource_constrained מ-PUT /api/v1/smtp/default, מה-PUT וה-DELETE /api/v1/smtp הישנים ובמחיקת פרופיל שמור, כי כל אחת מהפעולות האלה משנה את הנתיב של דומיינים שייתכן שאין לו גישה אליהם. מפתח שמוגבל לחלק מהדומיינים מקבל את אותה תשובה כשהוא עורך פרופיל שגם דומיין מחוץ לרשימה שלו משתמש בו.

נקודות קצה ישנות. פעולות GET/PUT /api/v1/smtp ברמת החשבון (וכן DELETE /api/v1/smtp/{id}, ‏POST /api/v1/smtp:test, ‏GET /api/v1/smtp:test-status/{jobId}) נשארות לתאימות לאחור אך אינן שולטות עוד בניתוב לכל דומיין: השתמשו בנקודות הקצה לכל דומיין ובנקודות הקצה של /smtp/default שלמעלה. כלי ה-MCP הישנים get_smtp_config / update_smtp_config הוצאו משימוש מאותה סיבה.

מיתוג מותג לבן, לקוחות וגישה לצוות

המיתוג מוגדר לכל דומיין באמצעות branding:read / branding:write. דומיין מפעיל מותג משלו (mode=custom), יורש את ברירת המחדל של החשבון (mode=inherit), או מושבת. נדרשת תקופת ניסיון פעילה של מותג לבן או תוסף בתשלום. לאחר ביטול, הבעלים שומר גישת שחזור לקריאה בלבד במהלך חלון החסד המוצג. קראו את dns_records של הדומיין ופרסמו בדיוק את הרשומות שהוחזרו. אל תסיקו שמות מארחים או יעדי CNAME מדוגמה.

PATCH הוא מיזוג חלקי, ולכן שדות שהושמטו נשמרים. אם המיתוג כרגע מושבת, העבירו mode כדי להפעילו שוב. sender_email מותאם אישית חייב להיות בדומיין עם מפתח DKIM מאומת. mail_zone_enabled משרת אפליקציות דואר וסנכרון DAV תחת הדומיין של המותג עצמו. הוא שייך למותג ולא לדומיין יחיד, ולכן דרוש mode=custom או scope=account_default; דומיין inherit מחזיר 422 inherited_brand. קראו את mail_zone.dns_status, ‏mail_zone.client_hosts_status, ‏mail_zone.records, ‏mail_zone.dav_url ו-mail_zone.dav_ready כדי לעקוב אחר ההקצאה ולהשתמש רק בכתובת DAV מוכנה. לתהליך העבודה המלא של הסוכן, ראו מדריך API ו-MCP למיתוג מותג לבן.

ממשק המותג הלבן ברמת החשבון מוסיף 18 נתיבים תחת /api/v1/white-label: מצב והתקדמות הגדרה, קטלוג גישה פעיל, רשימת חברים ופעולות מחזור חיים, מגבלות אחסון של לקוחות, פעילות חשבון והיסטוריית פעולות וכניסות לכל חבר. הוא משתמש ב-members:read, ‏members:write ו-activity:read. הגישה היא תמיד החיתוך בין זכאות החשבון, החברות הנוכחית של האדם, ההרשאה של פרטי האימות וכל מגבלת דומיין. ראו ניהול צוותי מותג לבן באמצעות API ו-MCP לטבלת הנתיבים ולמעברי המצבים.

מפרט OpenAPI זמין ב-/api/openapi.json לייבוא אל Postman, ‏Insomnia או מחוללי קוד.

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

• 401 "unauthenticated": ודאו שהכותרת Authorization: Bearer <token> קיימת ושהאסימון לא בוטל ולא פג תוקף.
• 403 "plan_api_disabled": ההיקף המבוקש אינו כלול בתוכנית שלכם. Nano כוללת את Email Verifier (ואת Drive אם רכשתם את תוסף Drive Storage). שדרגו ל-Starter ומעלה עבור שאר ה-API.
• 403 "token_scope_blocked_by_plan": לאסימון יש היקפים שאינם זמינים בתוכנית הנוכחית. בטלו את האסימון וצרו אסימון חדש עם היקפים מותרים.
• 403 "scope_blocked_by_entitlement": הרשאת מותג לבן שמורה אינה זמינה משום שהתוסף אינו פעיל או משום שזו פעולת כתיבה בתקופת חסד. הפעילו מחדש את המותג הלבן ואז הנפיקו מחדש או אשרו שוב את פרטי האימות.
• 403 "scope_blocked_by_membership": תפקיד החבר הנוכחי מצומצם יותר מהפעולה המבוקשת. בקשו מהבעלים לשנות אותו; אישור מחדש לבדו אינו יכול להרחיב את החברות.
• 422 "missing_idempotency_key": הוסיפו כותרת Idempotency-Key לפעולת הכתיבה שמצוינת בתיעוד נקודת הקצה.
• 403 "mailbox_sending_paused": השליחה מתיבת הדואר נעצרה משום שהדואר היוצא כבר לא נראה כאילו נשלח בידי בעליה, בדרך כלל מפני שסיסמה הגיעה לידיים הלא נכונות. קריאה, הצגת רשימות וכל שאר נקודות הקצה עדיין פועלות; רק השליחה נדחית, וניסיון חוזר לא יבטל את העצירה. יש לשנות את סיסמת תיבת הדואר, ולאחר מכן התמיכה מפעילה מחדש את השליחה. ראו למה איני יכול לשלוח דואר?.
• 403 "account_sending_on_hold": השליחה מכל החשבון מושהית בזמן ש-TrekMail בודקת אותו. קבלת דואר וכל שאר נקודות הקצה ממשיכות לפעול; ניסיון חוזר לא יבטל את ההשהיה. פנו לתמיכה כדי שההשהיה תיבדק.
• 403 "mailbox_send_disabled": השליחה כבויה רק עבור תיבת הדואר הזו. קריאה וכל שאר נקודות הקצה ממשיכות לפעול; ניסיון חוזר לא ישנה זאת. בדרך כלל תיבת הדואר חורגת מהתוכנית: הדומיין שלה חורג ממספר הדומיינים שהתוכנית כוללת, או שהתיבה חורגת ממספר תיבות הדואר לדומיין בתוכנית (הדומיינים והתיבות הוותיקים ביותר ממשיכים לשלוח). זה קורה לאחר מעבר לתוכנית קטנה יותר. זו יכולה להיות גם תיבה שנוצרה לפני שהגדרת הדומיין שלה הסתיימה. שדרוג מחזיר את השליחה מיד; לאחר הסרת הדומיינים או התיבות העודפים, או כשהגדרת הדומיין מסתיימת, השליחה חוזרת תוך יום. אם אף אחד מאלה לא מתאים, פנו לתמיכה.
• 403 "account_email_unverified": השליחה חסומה עד שבעלי החשבון יאמתו את כתובת הכניסה שלהם. לחשבונות שנרשמו ב-19 בפברואר 2026 ואילך יש 7 ימים לעשות זאת, ואותם 7 ימים מתחילים מחדש כשמחליפים כתובת כניסה מאומתת בכתובת חדשה. קריאה וכל שאר נקודות הקצה ממשיכות לפעול; ניסיון חוזר לא יבטל את החסימה. פתחו את הקישור בהודעת האימות, או לחצו על שליחה מחדש של הודעת האימות בכרזה בלוח הבקרה; השליחה חוזרת לפעול מיד לאחר שהכתובת מאומתת. ראו למה איני יכול לשלוח דואר?.
• 429 הגבלת קצב: המתינו למשך הזמן שבכותרת Retry-After לפני ניסיון חוזר. גם כשמגיעים למגבלה היומית של ה-API לכל תיבת דואר, התשובה היא rate_limited, אבל עם retryable בערך false, ‏dimension בערך api_mailbox_daily ושעה ב-resets_at: ניסיון חוזר מוקדם יותר לא יעזור, ולכן המתינו עד אז.
• 429 "sending_limit_exceeded": אחת ממכסות השליחה נוצלה עד הסוף. dimension מציין איזו מהן, ו-resets_at מציין מתי היא מתחדשת. ניסיון חוזר לפני כן לא יכול להצליח, ולכן retryable הוא false. השדה remaining_today ב-GET /api/v1/messages/sending-limits מציין לכמה נמענים נוספים תיבת הדואר יכולה לשלוח היום. כשהמכסה הנמוכה ביותר היא הסך היומי של החשבון, limit_today הוא null, וגם remaining_today הוא null עד שהסך הזה נוצל (ואז 0); אסימון ops קורא את הסך דרך GET /api/v1/sending-limits. אם dimension הוא recipients_per_message, פצלו את ההודעה לכמה הודעות קטנות יותר. ב-24 השעות הראשונות אחרי התשלום הראשון של החשבון, הסיבות כוללות את new_payer, ו-GET /api/v1/sending-limits מחזיר ב-full_limits_at את המועד שבו המגבלות המלאות של התוכנית חלות. ראו מגבלות שליחה לפי תוכנית.

שליחת דואר: גוף, כותרות ועבירות משלוח

POST /api/v1/messages/send מקבל בקשה בתבנית {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• גם body.text וגם body.html הם אופציונליים, אך לפחות אחד נדרש. אם תספקו רק body.text, אנו יוצרים אוטומטית חלופת HTML באמצעות פסקאות <p> (שורות ריקות מפרידות בין פסקאות; מעבר שורה יחיד הופך ל-<br>) כדי שההודעה תוצג כדואר רגיל בכל לקוח מודרני. אם נדרש גופן ברוחב קבוע, שלחו את הערך המילולי <pre>...</pre> בתוך body.html.
• headers הוא אובייקט אופציונלי של כותרות יוצאות שסיפק המשתמש. רשימת ההיתרים היא List-Unsubscribe, ‏List-Unsubscribe-Post, ‏Reply-To וכל כותרת מעקב מותאמת אישית X-*. שמות אחרים (From, ‏Subject, ‏Message-Id, ‏Authentication-Results וכדומה) מנוהלים בידי הפלטפורמה ונדחים עם 422. גם ערכים שמכילים CR/LF נדחים (הגנה מפני הזרקת כותרות). הערכים מוגבלים ל-998 תווים לפי RFC 2822.
• למקרי שימוש בכמות גדולה או באוטומציה, ראו את הסעיף כותרות עבירות משלוח לשולחים בכמות גדולה להגדרת List-Unsubscribe ולמתג auto_list_unsubscribe ברמת החשבון.

תשובת 202 פירושה שההודעה התקבלה, אבל עדיין לא נשלחה. מכסות השליחה נבדקות שוב כשההודעה יוצאת מהתור, ולכן עקבו אחרי התוצאה עם GET /api/v1/messages/deliveries/{request_id}, בעזרת ה-request_id מתשובת ה-202. כל אסימון message של אותה תיבת דואר יכול לבדוק זאת, ולא רק האסימון ששלח את ההודעה; request_id לא מוכר מחזיר 404. אם מגבלה עצרה את ההודעה, status הוא failed, ו-failure מציין את המגבלה (dimension) ומתי היא מתחדשת (resets_at). הודעה ששליחתה נכשלה אפשר לשלוח שוב מאוחר יותר עם אותו תוכן. אם אתם מעבירים מזהה משלכם ב-X-Request-Id, השתמשו במזהה חדש, כי המזהה הישן מחזיר רק את המסירה המקורית. הודעה מתוזמנת שמגיעה למגבלה בזמן השליחה מוחזקת במצב limit_reached ונשמרת 7 ימים: הציגו את ההודעות האלה עם GET /api/v1/messages/scheduled?status=limit_reached, שלחו אחת מהן מאוחר יותר על ידי קביעת scheduled_for חדש עם PATCH /api/v1/messages/scheduled/{id}, או מחקו אותה עם DELETE.