שליחה דרך ה-API היא קריאת POST אחת עם טוקן, נמען, מזהה שליחה וגוף הודעה. התשובה חוזרת מיד עם מזהה הודעה וסטטוס, והמסירה נבדקת בקריאה נפרדת. אין webhook - בודקים סטטוס ב-polling.
כתובת הבסיס: https://sendy.co.il/api/v1
הטוקן
נכנסים למפתחים ולוחצים על יצירת טוקן. שלושה דברים לדעת:
- יש טוקן אחד לכל סביבת עבודה. לא רשימה, לא טוקן לכל אינטגרציה.
- הוא מוצג פעם אחת בלבד. אין דרך לראות אותו שוב, רק להחליף אותו.
- החלפה מבטלת את הקודם מיד. כל אינטגרציה שמשתמשת בו תתחיל להיכשל עד שתעדכנו אותה.
רק בעלים של סביבת העבודה יכול ליצור, להחליף או לבטל טוקן.
הטוקן נשלח ב-header:
Authorization: Bearer sk_live_...השליחה
curl -X POST https://sendy.co.il/api/v1/messages \
-H "Authorization: Bearer $SENDY_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4821-confirm" \
-d '{
"to": "+972501234567",
"from": "MyBrand",
"body": "ההזמנה שלך התקבלה"
}'from חייב להיות מזהה שליחה מאושר של סביבת העבודה. את הרשימה המאושרת אפשר למשוך מ-GET /senders.
התשובה:
{
"id": "cmsi520wo000pp501vm5wtwia",
"status": "queued",
"to": "+972501234567",
"from": "MyBrand",
"credits_charged": 1,
"credits_refunded": 0,
"refunded": false,
"created_at": "2026-08-07T09:12:04.221Z"
}202 על שליחה חדשה, 200 על חזרה על בקשה שכבר בוצעה.
Idempotency: הטעות היקרה
Idempotency-Key הוא header, לא שדה בגוף הבקשה. זו ההבחנה החשובה ביותר במדריך הזה.
הסיבה: שדות שאינם מוכרים בגוף הבקשה נזרקים בשקט. אם תשלחו את המפתח בתוך ה-JSON, לא תקבלו שגיאה, לא תקבלו אזהרה - פשוט לא תהיה לכם הגנה מפני כפילויות. שליחה חוזרת אחרי timeout תשלח הודעה שנייה ותחייב שוב.
עם ה-header במקום הנכון, בקשה חוזרת עם אותו מפתח מחזירה 200 עם אותו מזהה הודעה, ולא מחייבת פעם שנייה.
המפתח קשור לתוכן: אותו מפתח עם נמען אחר או גוף אחר מחזיר 409 IDEMPOTENCY_CONFLICT. זו הגנה מפני מפתח שממוחזר בטעות.
בדיקת מסירה
אין webhook יוצא. בודקים בקריאה:
curl https://sendy.co.il/api/v1/messages/{id} \
-H "Authorization: Bearer $SENDY_TOKEN"הסטטוסים האפשריים: queued, sending, sent, delivered, undelivered, failed.
sent ו-delivered הם לא אותו דבר, וזה מקור רוב הבלבול:
sentאומר שההודעה התקבלה לשליחה. זה לא אישור מסירה.deliveredאומר שהתקבל אישור מהרשת שההודעה הגיעה למכשיר.
הודעה יכולה להישאר ב-sent לאורך זמן אם אישור המסירה לא חוזר. שלושה סטטוסים סופיים בלבד: delivered, undelivered, failed. את השאר כדאי להמשיך לבדוק.
מצב שליחה: שיווקי מול תפעולי
זו הגדרה עם משמעות משפטית, ולא רק טכנית.
| מצב | התנהגות |
|---|---|
marketing | שליחה למי שביקש להסיר את עצמו נדחית ב-403, בלי חיוב |
transactional | עוברת. אין בדיקת הסרות בכלל |
ברירת המחדל לסביבת עבודה חדשה היא marketing, כלומר בדיקת ההסרות פעילה. אפשר לדרוס לכל בקשה בשדה mode, וההגדרה בבקשה תמיד גוברת.
שתי נקודות שאסור לטעות בהן:
בדיקת ההסרות אינה רשימה שחורה גורפת. היא מזהה רק מספרים שקיימים כאיש קשר בסביבת העבודה שלכם ומסומנים כמוסרים. מספר שמעולם לא נכנס לרשימה שלכם לא ייחסם, בשום מצב.
transactional לא נותן שום הגנה. הוא נועד לקודי אימות ועדכוני הזמנה. שליחת תוכן שיווקי במצב הזה מפרה את החוק ואת תנאי השימוש, והאחריות עליכם.
קודי שגיאה
מעטפת אחידה לכל שגיאה:
{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "..." } }| קוד | HTTP | מתי |
|---|---|---|
VALIDATION | 400 | גוף בקשה לא תקין |
INVALID_RECIPIENT | 400 | נמען לא תקין |
MESSAGE_TOO_LONG | 400 | גוף ההודעה חורג |
INVALID_API_KEY | 401 | טוקן חסר, שגוי או שהוחלף |
INSUFFICIENT_CREDITS | 402 | אין מספיק יתרה |
SENDER_NOT_APPROVED | 403 | from אינו מזהה מאושר |
RECIPIENT_UNSUBSCRIBED | 403 | הנמען הסיר את עצמו, במצב שיווקי |
IDEMPOTENCY_CONFLICT | 409 | אותו מפתח עם תוכן אחר |
RATE_LIMITED | 429 | חריגה מקצב הבקשות |
הקצב המותר הוא 60 בקשות לדקה לכל טוקן. התשובה כוללת Retry-After, וכדאי לכבד אותו במקום לנסות מיד.
שאר הנקודות
| קריאה | מה מחזירה |
|---|---|
GET /credits | יתרת הקרדיטים |
GET /senders | מזהי השליחה המאושרים |
GET /segments | הקבוצות וגודל כל אחת |
GET /contacts | רשימה או חיפוש לפי מספר |
POST /contacts | יצירה או עדכון לפי טלפון |
GET /custom-fields | השדות המותאמים אישית |
POST /contacts לעולם לא מחזיר לרשימה מישהו שהסיר את עצמו, ולא מוחק שדה שלא נשלח. איש קשר חדש חייב לקבל קבוצה אחת לפחות.
עלות
זהה לשליחה מהממשק: קרדיט אחד להודעה עד 201 תווים. הפירוט: קרדיטים - איך נספר החיוב.
בלי קוד
אם אתם כאן רק כדי לחבר חנות או אוטומציה, יש דרך קצרה יותר: לחבר את החנות או האוטומציה בלי קוד.
מדריכים נוספים במפתחים ואינטגרציות
30 הודעות חינם בפתיחת חשבון עסקי. בלי כרטיס אשראי, בלי התחייבות.
התחילו בחינם