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

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

מה מקבלים

• REST API v1 עם תבנית בקשה ותגובה של JSON.
• אימות באמצעות אסימון Bearer: ללא קובצי Cookie או הפעלות עבור קריאות API מאומתות.
• מפתחות אידמפוטנטיות בפעולות הכתיבה שדורשות אותם, למניעת עבודה כפולה במהלך ניסיונות חוזרים.
• הגבלת קצב לכל אסימון עם כותרות Retry-After.
• יומן ביקורת שמוצג בלוח הבקרה תחת AI Agents & API → Audit Log.
• שרת MCP עם קטלוג שמסונן לפי פרטי האימות, התעבורה והגדרות הבטיחות של החיבור הנוכחי. לכן חיבור פרויקט מצומצם רואה רק את הכלים שבהם הוא יכול להשתמש.
• כינויי דומיין: חברו כתובות לקבלה בלבד בדומיין משני לאותם חלקים מקומיים בדומיין ראשי, עם מצבי מסירה שמורים לעומת פעילים והסרה בטוחה. ראו כינויי דומיין באמצעות API ו-MCP.
• ארכיטקטורה של שני אסימונים: אסימוני ops נפרדים לתשתית ואסימוני message לפעולות דואר מלאות כגון קריאה, שליחה, יצירת טיוטות, תזמון, אנשי קשר, לוחות שנה, זהויות, תבניות ותיקיות.
• תובנות על עבירות משלוח והחזרות: משכו מלוח הבקרה את הסיכום של הודעות שנשלחו, נמסרו, חזרו בהחזרה קשיחה או רכה, יחד עם קודי SMTP ותגובות לכל נמען. ראו עבירות משלוח והחזרות.
• שימוש באחסון תיבת הדואר: 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 Agents & API → Tokens → Create token ושלחו אותו בתור Authorization: Bearer …. ראו יצירה וניהול של אסימוני API.
• חדשים ב-API? לחצו על Start tour בחלק העליון של דף AI Agents & API לסיור קצר בשיטות החיבור, ניהול אסימונים, יישומים מחוברים ויומן הביקורת.

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

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

Authorization: Bearer tm_live_abc123...

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

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

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

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

https://trekmail.net/api/v1

כתובת ה-URL הבסיסית מוצגת בלוח הבקרה AI Agents & API תחת Quick Reference. הגרסה נמצאת בנתיב ה-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 ישחזר את התגובה המקורית בלי ליצור כפילויות.

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.

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

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

גישת 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.

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

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

תיבת דואר משותפת היא תיבת צוות כגון support@ או sales@, שחברים פותחים דרך חשבון תיבת הדואר הרגיל שלהם, ב-Webmail וכאשר גישה מקורית מופעלת גם כתיקיית IMAP מואצלת. אין סיסמה משותפת או כניסה נפרדת. הגישה אחידה: כל חבר יכול לקרוא, ודגל יחיד can_send קובע אם הוא יכול להשיב מהכתובת (true) או לקרוא בלבד (false). אין תפקידי חברים.

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

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

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

הסרת חבר, שינוי 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 נפתר כעת.
• set_account_default: true הוא המקביל ב-API למתג Make this the account default בלוח הבקרה (דומיינים חדשים מתחילים בנתיב הזה). apply_to_all: true הוא כפתור Apply to all domains (החלפה חד פעמית של כל הדומיינים לנתיב הזה).

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

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

נקודות קצה ישנות. פעולות 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 למיתוג מותג לבן.

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

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

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 ברמת החשבון.