מסירת דואר והחזרות דרך API ו-MCP

לוח הבקרה של TrekMail מציג שני סוגים של נתוני החזרה בכרטיסייה נתונים סטטיסטיים של כל דומיין:

1. סיכום של 30 יום: מספר ההודעות שנשלחו ונמסרו, מספר ההחזרות הזמניות והקבועות ושיעורי המסירה וההחזרה.
2. רשימה לפי נמען: 50 ההחזרות האחרונות של דואר יוצא, עם קוד מצב SMTP והתשובה של השרת המקבל, כדי שתוכלו להבין מדוע הודעה מסוימת נכשלה.

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

הנתונים הזמינים

שלושתן דורשות domains:read (או mailboxes:read עבור הרשימה המוגבלת לתיבת דואר). הפעולות הן לקריאה בלבד. אין צורך במפתח אידמפוטנטיות.

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

REST API: דוגמאות מהירות

סיכום דומיין

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status הוא אותו אות בן שלושת המצבים שמוצג בלוח הבקרה:

• good: שיעור החזרה נמוך מ-2%.
• warning: שיעור החזרה בין 2% ל-5%.
• poor: שיעור החזרה של 5% ומעלה. בדקו ונקו את רשימת השליחה.

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

רשימת החזרות לפי נמען

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

פרמטרים של השאילתה

רשימה המוגבלת לתיבת דואר

כדי לבדוק מוניטין לפי שולח, הגבילו את התחום לתיבת דואר אחת:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

מבנה התשובה זהה לזה של נקודת הקצה לדומיין.

פרטיות של תשובות SMTP

TrekMail מסירה מידע פנימי לאבחון לפני שהיא מחזירה תשובת SMTP. ההודעה שנותרת זהה לזו שמוצגת לבעל החשבון בלוח הבקרה, והיא נועדה לעזור באבחון המסירה ולא לחשוף מידע פנימי על השרת.

כלי MCP

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

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

כותרות מסירה לשולחים בכמות גדולה

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

לכל הודעה (שליטה מפורטת). העבירו אותן דרך השדה headers של POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

השדה headers מקבל רשימת ערכים מורשים קצרה: List-Unsubscribe,‏ List-Unsubscribe-Post,‏ Reply-To וכל כותרת מעקב מותאמת אישית מסוג X-*. הזרקת כותרת (CR/LF) וכותרות מנוהלות (From,‏ Subject,‏ Date,‏ Message-Id,‏ Authentication-Results,‏ DKIM-Signature ועוד) נדחות עם 422.

לכל החשבון (הגדרה חד-פעמית). אם כל ההודעות היוצאות מחשבון זה נשלחות באופן אוטומטי, אפשר להפעיל בחשבון את auto_list_unsubscribe. כאשר האפשרות פעילה, הפלטפורמה מוסיפה כותרת List-Unsubscribe עם כתובת mailto בלבד לכל הודעה יוצאת שעדיין אינה כוללת אותה. היא אינה מוסיפה List-Unsubscribe-Post, ולכן אפשרות חלופית זו אינה מספקת ביטול הרשמה בלחיצה אחת לפי RFC 8058. כדי לספק ביטול הרשמה בלחיצה אחת שתואם לדרישות הספקים, הוסיפו את שתי הכותרות לכל הודעה בעזרת נקודת קצה HTTPS משלכם לביטול הרשמה, כמו בדוגמה שלמעלה. כותרות שסופקו בידי הקורא תמיד מקבלות קדימות. האפשרות כבויה כברירת מחדל וחשבונות קיימים אינם משתנים.

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

דפוסים לסוכני בינה מלאכותית

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

• סיכום מוניטין שבועי. בכל יום שני, קראו ל-get_domain_deliverability עבור כל דומיין בחשבון ופרסמו סיכום ב-Slack או ב-Teams. הציגו רק דומיינים שבהם status הוא warning או poor.
• ניקוי רשימה לפי החזרות. קראו ל-list_domain_bounces?type=hard&days=14, הסירו כפילויות של recipient_email ולאחר מכן חסמו כתובות אלה ברשימת השליחה. החזרות קבועות מעידות בדרך כלל שכתובת הנמען כבר אינה קיימת, ושליחה חוזרת מבזבזת את תקציב המסירה.
• בדיקה לפי שולח. כאשר bounce_rate של תיבת דואר אחת מזנק, קראו עבורה ל-list_mailbox_bounces וקבצו לפי smtp_status_code. זינוק בקודי 550 עשוי להצביע על רשימת כתובות מיושנת; זינוק בקודי 421 עשוי להצביע על כך ששרת הדואר המקבל הגביל את קצב השליחה שלכם.
• בדיקה של תמיכת הלקוחות. כשמשתמש מדווח שהודעת דואר לא הגיעה, בקשו מהסוכן לקרוא ל-list_domain_bounces?recipient=<their-address>. תשובת SMTP עשויה להצביע על הפעולה הבאה, כגון פינוי תיבת דואר מלאה של הנמען, הסרת חסימה אצל הנמען או תיקון דחייה של DMARC.

ניהול גרסאות

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

נושאים קשורים

• מדדי דואר זבל: נתוני הגנה מפני דואר זבל נכנס (get_spam_metrics,‏ get_spam_summary).
• אימות דואר אלקטרוני: ניקוי הרשימה לפני השליחה כדי למנוע החזרות מראש.
• סקירת API: אימות, היקפים, מגבלות קצב ואידמפוטנטיות.