webhook לדואר נכנס
כתובת נכנסת יכולה לדחוף כל הודעה שהתקבלה לכתובת webhook שלכם: השולח, הנושא, הגוף והקבצים המצורפים, כדי שמערכת שלכם תגיב למייל בלי לקרוא תיבה.
למפתחים
לשלוח מייל בקריאת HTTP אחת
API לשליחת מייל שולח הודעה בבקשת HTTP אחת ומחזיר מזהה. בניגוד ל-SMTP, הקוד שלכם יודע שההודעה התקבלה, יכול לנסות שוב בלי לשלוח פעמיים, ומקבל שגיאה שאומרת אם הכתובת לא קיימת או אם פשוט לנסות שוב.
מפתח נפרד לכל סביבה, ומפתח אידמפוטנטיות חובה, כי ריטריי בלי מפתח הוא חשבונית כפולה
הקריאה
שליחה אחת, וזה כל מה שצריך
מפתח ה-API בכותרת, גוף JSON, ומזהה בתשובה. שדה `idempotency_key` הוא חובה: סוכן או שרת שאיבד תשובה ינסה שוב, ובלי המפתח זה מייל כפול לאדם אמיתי.
curl -X POST https://api.brandmyinbox.com/v1/send \
-H "Authorization: Bearer $BMI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "orders@yourdomain.co.il",
"to": "customer@example.com",
"subject": "אישור הזמנה 48219",
"html": "<p>ההזמנה התקבלה</p>",
"idempotency_key": "order-48219-receipt"
}'- 1 יוצרים מפתח במסך המפתחים. מפתח נפרד לפיתוח ולייצור, ומפתח שדלף מבוטל בלחיצה בלי לגעת בשני
- 2 שולחים עם מפתח אידמפוטנטיות אותו מפתח פעמיים מחזיר את אותה תשובה ולא שולח שוב. ריטריי אחרי timeout לא מייצר שתי חשבוניות
- 3 קוראים את התשובה מזהה הודעה, או שגיאה שמבדילה בין כתובת שלא קיימת לבין נסו שוב עוד רגע
מה מונע כפילות
מה קורה כשהקריאה נכשלת באמצע
התרחיש הנפוץ ביותר בייצור, ומה ה-API עושה איתו.
קריאה ראשונהidempotency_key: order-48219
timeoutהתשובה אבדה בדרך. ההודעה כבר יצאה
ניסיון שניאותו מפתח בדיוק
אותה תשובהאותו מזהה הודעה. שום דבר לא נשלח פעמיים
מה שמונע תקלות בייצור
ארבע החלטות שנעשו כאן במקומכם
אלה הדברים שכל צוות מגלה בעצמו אחרי האירוע הראשון בייצור, ולכן הם ברירת מחדל:
- אידמפוטנטיות חובה: קריאה בלי מפתח נדחית, כדי שריטריי לעולם לא ייצר הודעה שנייה ללקוח
- כתובת שחזרה נכנסת לרשימת חסימה, וניסיון נוסף אליה נענה בשגיאה במקום להישלח
- שגיאות שמבדילות בין „הכתובת לא קיימת״ ל„נסו שוב עוד רגע״, כי ריטריי על הראשונה שורף מוניטין
- מפתח לכל סביבה, כדי שבדיקה בפיתוח לא תשלח ללקוח אמיתי
- קצב של 30 הודעות בדקה וחימום אוטומטי לדומיין חדש, כדי שבאג בלולאה לא יחסום את הדומיין
מה עוד יש
מעבר לשליחה עצמה
יומן פעילות
כל שליחה, כל מפתח שנוצר או בוטל, וכל שינוי בדומיין נרשמים ביומן החשבון. כשלקוח אומר „לא קיבלתי חשבונית״, יש מזהה ורישום ולא ניחוש.
MCP לסוכני AI
אותן פעולות קיימות גם ככלים לעוזר AI, עם אותן הרשאות בדיוק. סוכן יכול לבדוק מצב דומיין ולהכין הודעה, ולא יכול לעקוף אישור.
שאלות על ה-API
מה ההבדל בין שליחה ב-API לשליחה ב-SMTP
SMTP הוא שיחה בין שרתים ומחזיר „קיבלתי״ בלבד. API מחזיר מזהה להודעה, מקבל מפתח אידמפוטנטיות שמונע כפילות, ומחזיר שגיאה שאומרת אם לנסות שוב. אם הקוד שלכם צריך להחליט מה לעשות אחרי שליחה, זה ההבדל המעשי שמשנה.
מה קורה אם הקריאה נכשלת באמצע ואנחנו מנסים שוב
אם שלחתם את אותו idempotency_key, הניסיון השני מחזיר את התשובה של הראשון ולא שולח הודעה נוספת. השדה הזה הוא חובה בדיוק בגלל זה: ריטריי אחרי timeout הוא הדרך הנפוצה ביותר שלקוח מקבל את אותה חשבונית פעמיים.
איך יודעים שהודעה נמסרה בפועל
המזהה שחוזר מהקריאה מופיע ביומן הפעילות של החשבון, וכתובת שחזרה נכנסת אוטומטית לרשימת החסימה כך שניסיון נוסף אליה נענה בשגיאה. אירועי מסירה בזמן אמת דרך webhook אינם קיימים היום עבור דואר יוצא, ואנחנו לא כותבים כאן שהם קיימים.
יש ספריות מוכנות
ה-API הוא HTTP ו-JSON רגילים, ולכן כל שפה יודעת לדבר איתו בלי ספרייה. מסך המפתחים מייצר את המפתח ומראה את פקודת ה-curl המלאה, ומי שעובד עם עוזר AI יכול לחבר אותו דרך שרת ה-MCP ולתת לו לבצע את הקריאות.