Suppressions API

Suppressions API מנהל, לכל סביבת עבודה, את רשימות החסימה של כתובות אימייל ומספרי טלפון שאליהם Joryio לא תשלח. חסימה היא שער קשיח: כל עוד מזהה מסוים חסום בערוץ, כל הודעה אליו באותו ערוץ תדולג - ללא תלות בקמפיין או במסע שמנסה להגיע אליו.

ה־API הזה משקף את המסך Audience → Suppression Lists בלוח הבקרה. השתמשו בו כדי לבדוק אילו נמענים חסומים, לייבא רשימה קיימת של כתובות לא תקינות מפלטפורמה אחרת, לכבד בקשות הסכמה מהמערכות שלכם או להסיר חסימה לאחר פתרון החזרה קשה.

כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com/api - ראו סקירת API.

אימות

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

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

הרשאות לכל נקודת קצה

הערוץ קובע איזו הרשאה נדרשת. נקודות קצה של אימייל דורשות email_suppression:*; נקודות קצה של SMS ושל WhatsApp דורשות sms_suppression:*.

Endpoint	ערוץ אימייל	ערוץ SMS / WhatsApp
`GET /suppressions`	`email_suppression:read`	`sms_suppression:read`
`GET /suppressions/{identifier}`	`email_suppression:read`	`sms_suppression:read`
`POST /suppressions`	`email_suppression:write`	`sms_suppression:write`
`POST /suppressions/hard-bounce`	`email_suppression:write`	- (אימייל בלבד)
`POST /suppressions/import`	`email_suppression:write`	`sms_suppression:write`
`DELETE /suppressions/{identifier}`	`email_suppression:write`	`sms_suppression:write`

מושגי יסוד

קראו את החלק הזה לפני שאתם קוראים לנקודות הקצה לכתיבה - שאר ה־API מובן רק לאחר שההבחנה בין reason ל־source ברורה.

`reason` (למה) מול `source` (מאיפה זה הגיע)

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

reason - למה המזהה חסום. אחד מ־unsubscribe, hard_bounce, complaint, manual.
source - מהיכן הגיעה החסימה (המקור שלה). אחד מ־delivery, api, import או מקור הסכמה כגון unsubscribe_link.

השדות בלתי תלויים זה בזה. אותו reason יכול להגיע ממקורות שונים - hard_bounce שנצפה בצינור השליחה שלנו נושא source: "delivery", ואילו hard_bounce שאתם מדווחים עליו דרך ה־API הזה נושא source: "api". השדה reason מגדיר את המשמעות מבחינת יכולת מסירה או הסכמה; source מגדיר עד כמה אפשר לסמוך על המקור והאם הוא נספר במדדי המוניטין שלכם.

סיבות הסכמה לעומת סיבות של יכולת מסירה

ארבעת ערכי reason מתחלקים לשתי משפחות שמתנהגות אחרת:

משפחה	Reasons	משמעות	שורד re-subscribe?
הסכמה (Consent)	`unsubscribe`, `manual`	הנמען (או אתם, בשמו) ביקש לא לקבל פנייה.	לא - הרשמה מחדש מאפשרת לאיש הקשר הזה בלבד לעבור (אנשי קשר אחרים עם הכתובת נשארים חסומים); `DELETE /suppressions` מסיר אותה.
יכולת מסירה	`hard_bounce`, `complaint`	הכתובת או המספר אינם פעילים, או שהנמען סימן אותנו כספאם.	כן - נשמר גם אם הנמען מצטרף מחדש.

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

אי אפשר להמציא החזרה

נתיבי הכתיבה הרגילים - POST /suppressions ו־POST /suppressions/import - מגבילים את reason ל־manual או unsubscribe. הם אינם יכולים ליצור שורת hard_bounce או complaint. החזרה היא אירוע שהפלטפורמה צופה בו, ולא טענה שלקוח יכול למסור ללא בקרה.

הנתיב היחיד שמאפשר לדווח על החזרה הוא POST /suppressions/hard-bounce; גם אז השורה מסומנת source: "api", כדי שלא תתבלבל עם החזרה שצפינו בה בעצמנו.

רק החזרות אמיתיות משפיעות על המוניטין שלכם

שיעור ההחזרות המדווח של החשבון ומדדי יכולת המסירה והמוניטין סופרים רק החזרות עם source: "delivery" - אלה שצינור השליחה שלנו צפה בהן בשכבת SMTP. חסימה שדווחה דרך ה־API (source: "api") או יובאה (source: "import") חוסמת שליחה למזהה, אך אינה מנפחת את שיעור ההחזרות המדווח. כך אפשר לטעון מראש כתובות שידוע שאינן פעילות ולהגן על מוניטין השולח בלי לעוות את המדד שמנסים להגן עליו.

החסימה חלה לפי הכתובת או המספר

חסימה ממופה לפי כתובת האימייל המנורמלת או מספר הטלפון בכל סביבת עבודה - לא לפי רשומת איש קשר. לכן חסימה של כתובת אחת מכסה כל איש קשר כפול שחולק אותה. חסמו את [email protected] פעם אחת, וכל אנשי הקשר עם הכתובת הזו ייחסמו באימייל בכל סביבת העבודה.

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

מספר דו-משמעי (תקין גם כמספר מקומי של מדינת ברירת המחדל וגם כמספר של מדינה אחרת) נדחה (400) בהוספה או בהסרה, ומדולג (נספר ב-ambiguous) בייבוא מרובה, כי אחת הקריאות עשויה להיות מספר של מישהו אחר: שלחו אותו עם קידומת המדינה (+...).

טבלת עזר ל־reason / source

ערכי `reason`

`reason`	משפחה	נוצר על ידי
`unsubscribe`	הסכמה	קישור opt-out של נמען, `POST /suppressions`, `POST /suppressions/import`
`manual`	הסכמה	פעולת מפעיל, `POST /suppressions`, `POST /suppressions/import`
`hard_bounce`	יכולת מסירה	צינור השליחה שלנו, `POST /suppressions/hard-bounce`
`complaint`	יכולת מסירה	צינור השליחה שלנו (לולאות משוב)

ערכי `source`

`source`	משמעות	נספר למוניטין?
`delivery`	נצפה בצינור השליחה או הקבלה שלנו (החזרה או תלונה אמיתית).	כן
`api`	הוצהר דרך ה־REST API הזה.	לא
`import`	נטען דרך `POST /suppressions/import` (הגירה באצווה).	לא
`unsubscribe_link` (ומקורות הסכמה אחרים)	שינוי הסכמה ביוזמת הנמען.	לא

הצגת חסימות

מחזיר רשימה עם עימוד של מזהים חסומים בערוץ.

Endpoint

GET /suppressions

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

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	`email`, `sms`, או `whatsapp`. חובה.
`reason`	string	-	מסנן אופציונלי: `unsubscribe`, `hard_bounce`, `complaint` או `manual`.
`limit`	number	`100`	שורות לעמוד (לכל היותר `1000`).
`offset`	number	`0`	היסט לעימוד.

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/api/suppressions?channel=email&reason=hard_bounce&limit=50" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "items": [
    {
      "identifier": "[email protected]",
      "channel": "email",
      "identifierType": "email",
      "reason": "hard_bounce",
      "source": "delivery",
      "scope": "channel",
      "listId": null,
      "createdAt": "2026-06-30T12:04:11.000Z"
    },
    {
      "identifier": "[email protected]",
      "channel": "email",
      "identifierType": "email",
      "reason": "unsubscribe",
      "source": "unsubscribe_link",
      "scope": "group",
      "listId": "grp_newsletter",
      "createdAt": "2026-07-02T09:20:00.000Z"
    }
  ],
  "total": 214,
  "limit": 50,
  "offset": 0
}

בדיקת מזהה בודד

בודק אם מזהה בודד חסום בערוץ.

Endpoint

GET /suppressions/{identifier}

פרמטר הנתיב {identifier} הוא כתובת האימייל או מספר הטלפון, מקודדים ל־URL.

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

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	`email`, `sms`, או `whatsapp`. חובה.

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/api/suppressions/[email protected]?channel=email" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה - חסום

{
  "suppressed": true,
  "identifier": "[email protected]",
  "reason": "hard_bounce",
  "source": "delivery",
  "scope": "channel",
  "listId": null,
  "createdAt": "2026-06-30T12:04:11.000Z"
}

תגובה - לא חסום

{
  "suppressed": false
}

הוספת חסימה

מוסיף חסימה מטעמי הסכמה או חסימה ידנית. השתמשו בכך כדי לכבד opt-out שהגיע אליכם דרך המערכות שלכם (פנייה לתמיכה, דגל ב־CRM או שינוי במרכז ההעדפות שלכם).

Endpoint

POST /suppressions

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	`email`, `sms`, או `whatsapp`.
`identifier`	string	כן	כתובת אימייל או מספר טלפון לחסימה.
`reason`	string	לא	`manual` (ברירת מחדל) או `unsubscribe`. מוגבל - כל ערך אחר נדחה.
`scope`	string	לא	`channel` (ברירת מחדל) - כל הרשימות בערוץ - או `group` עם `listId` לרשימה אחת.

למה אין כאן היקף ארגוני

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

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

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

| listId | string | לא | חובה כאשר scope הוא group: הקבוצה או הרשימה שעליה החסימה חלה. היא חייבת להיות רשימה במרחב העבודה הזה - listId חסר, או של מרחב עבודה אחר, מחזיר 400. |

ה־source של שורה שנוצרת כאן נרשם תמיד כ־api. נקודת הקצה הזו אינה יכולה ליצור hard_bounce או complaint.

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/api/suppressions \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "identifier": "[email protected]",
    "reason": "unsubscribe",
    "scope": "group",
    "listId": "grp_newsletter"
  }'

תגובה

{
  "identifier": "[email protected]",
  "channel": "email",
  "identifierType": "email",
  "reason": "unsubscribe",
  "source": "api",
  "scope": "group",
  "listId": "grp_newsletter",
  "createdAt": "2026-07-11T08:15:00.000Z"
}

reason: "unsubscribe" מעדכן גם את אנשי הקשר

עם reason: "unsubscribe", כל איש קשר בסביבת העבודה עם אותו אימייל או טלפון מוגדר גם הוא ל־unsubscribed בערוץ (או, עם scope: "group", ברשימה הזו), עם רשומת היסטוריה. חסימה מסוג manual חוסמת שליחה בלי לשנות את הסטטוס של אנשי הקשר עצמם.

דיווח על החזרה קשה

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

למה נקודת הקצה הזו נפרדת

בדרך כלל Joryio צופה בהחזרה בזמן השליחה; הקורא אינו אמור להכריז עליה. הפרדת הדיווח על החזרה מנתיבי ההוספה והייבוא הרגילים מונעת יצירה שגויה או רשלנית של נתונים כאלה.
מכיוון שאתם מדווחים על ההחזרה במקום שאנחנו נצפה בה, השורה מסומנת source: "api". היא חוסמת שליחה בדיוק כמו החזרה אמיתית, אך אינה מתבלבלת עם החזרה שראינו בעצמנו ואינה נספרת בשיעור ההחזרות המדווח או במדדי מוניטין השולח.
הוא אימייל בלבד. אין מקבילה לטלפון - אי־מסירה ב־SMS/WhatsApp ממודלת אחרת.

Endpoint

POST /suppressions/hard-bounce

גוף הבקשה

שדה	סוג	חובה	תיאור
`identifier`	string	כן	כתובת האימייל שחזרה בהחזרה קשה.

הערוץ הוא email באופן משתמע. השורה נרשמת עם reason: "hard_bounce" ו־source: "api".

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/api/suppressions/hard-bounce \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "[email protected]"
  }'

תגובה

{
  "identifier": "[email protected]",
  "channel": "email",
  "identifierType": "email",
  "reason": "hard_bounce",
  "source": "api",
  "scope": "channel",
  "listId": null,
  "createdAt": "2026-07-11T08:20:00.000Z"
}

ייבוא באצווה

טוען רשימת חסימה קיימת - למשל בעת הגירה מפלטפורמה אחרת.

Endpoint

POST /suppressions/import

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	`email`, `sms`, או `whatsapp`.
`entries`	array	כן	עד `5000` אובייקטים, כל אחד `{ identifier, reason? }`.

ה־reason של כל רשומה מוגבל ל־manual (ברירת מחדל) או unsubscribe; כל ערך אחר מומר ל־manual. כל שורה מיובאת נרשמת עם source: "import". כמו בנקודת הקצה להוספה, הייבוא אינו יכול ליצור החזרה או תלונה.

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/api/suppressions/import \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "entries": [
      { "identifier": "[email protected]" },
      { "identifier": "[email protected]", "reason": "unsubscribe" },
      { "identifier": "[email protected]" }
    ]
  }'

תגובה

{
  "channel": "email",
  "received": 3,
  "imported": 3,
  "skipped": 0,
  "source": "import"
}

הסרת חסימה (unsuppress)

מסיר חסימה כדי ש־Joryio תוכל לשלוח שוב למזהה.

Endpoint

DELETE /suppressions/{identifier}

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

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	`email`, `sms`, או `whatsapp`. חובה.

אזהרה

פעולה זו מסירה את שורות חסימת ההסכמה (unsubscribe, manual) של המזהה בערוץ בסביבת העבודה הזו בלבד. היא לעולם אינה מסירה ביטול ממילת STOP או שורת hard_bounce / complaint - אלו מדווחות ב־kept. אנשי קשר שהסטטוס שלהם הוגדר ל־unsubscribed נשארים מבוטלים; רשמו איש קשר מחדש דרך Subscriptions API.

דוגמת בקשה

curl -X DELETE "https://api-eu1.joryio.com/api/suppressions/[email protected]?channel=email" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "identifier": "[email protected]",
  "removed": 1,
  "kept": { "deliverability": 1 }
}

removed הוא מספר שורות החסימה שנמחקו (מזהה יחיד יכול לשאת בו־זמנית שורת הסכמה ברמת group ושורת יכולת מסירה ברמת global).

kept (מופיע רק כשמשהו נשמר) סופר את השורות שה־API הזה אינו רשאי להסיר: stop_keyword (הסרתו הייתה מסירה את החסימה של המספר עבור כל איש קשר שחולק אותו - רשמו מחדש את איש הקשר האחד דרך Subscriptions API, או שהאדם ישלח START) ו־deliverability (החזרה קשה או תלונת ספאם - רק התמיכה של Joryio מסירה אותן).

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

הגירת רשימת חסימה קיימת

כשאתם עוברים ל־Joryio מפלטפורמת אימייל או SMS אחרת, הביאו איתכם את רשימת החסימה כבר ביום הראשון, כדי שהשליחה הראשונה לא תגיע שוב לכתובות שאתם כבר יודעים שאינן פעילות או שביקשו opt-out.

ייבאו את כל הרשימה דרך POST /suppressions/import. הרשומות מגיעות כ־manual (או unsubscribe אם תתייגו אותן), עם source: "import". הן חוסמות שליחה ומגינות על מוניטין השולח כבר בשליחה הראשונה - בלי לנפח את שיעור ההחזרות המדווח, מפני ששורות מיובאות לעולם אינן נספרות למוניטין.
רק אם אתם צריכים שהכתובות האלה ידווחו כהחזרות - למשל כדי לשמור על רציפות אנליטיקת ההחזרות לאורך ההגירה - דווחו עליהן אחת־אחת באמצעות POST /suppressions/hard-bounce. הן עדיין יסומנו source: "api", ולכן יחסמו שליחה ויופיעו כהחזרות ברשימת החסימה בלי להיספר כהחזרות שאנחנו צפינו בהן.

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

תגובות שגיאה

כל השגיאות משתמשות במבנה הסטנדרטי - אין אוסף נפרד של קודי שגיאה לקריאה ממוכנת; השתמשו בקוד המצב של HTTP יחד עם השדה message. ראו תגובת שגיאה בסקירת ה־API. כשלי תיקוף (400) מוסיפים מערך errors עם הודעה לכל שדה שנכשל:

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/suppressions",
  "errors": [
    "reason must be one of the following values: manual, unsubscribe"
  ]
}

שימו לב: ה־API הזה אוכף הרשאות מדויקות לפי ערוץ. מפתח API שמחזיק רק בהרשאת ה־SMS יקבל 403 כשהוא ניגש לחסימות אימייל (ולהפך):

{
  "statusCode": 403,
  "message": "API key missing required scope 'email_suppression:write' for channel 'email'",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/suppressions"
}

אימות​

הרשאות לכל נקודת קצה​

מושגי יסוד​

reason (למה) מול source (מאיפה זה הגיע)​

סיבות הסכמה לעומת סיבות של יכולת מסירה​

אי אפשר להמציא החזרה​

רק החזרות אמיתיות משפיעות על המוניטין שלכם​

החסימה חלה לפי הכתובת או המספר​

טבלת עזר ל־reason / source​

ערכי reason​

ערכי source​

הצגת חסימות​

Endpoint​

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

דוגמת בקשה​

תגובה​

בדיקת מזהה בודד​

Endpoint​

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

דוגמת בקשה​

תגובה - חסום​

תגובה - לא חסום​

הוספת חסימה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

דיווח על החזרה קשה​

למה נקודת הקצה הזו נפרדת​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

ייבוא באצווה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

הסרת חסימה (unsuppress)​

Endpoint​

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

דוגמת בקשה​

תגובה​

הגירת רשימת חסימה קיימת​

תגובות שגיאה​

הצעדים הבאים​

אימות

הרשאות לכל נקודת קצה

מושגי יסוד

`reason` (למה) מול `source` (מאיפה זה הגיע)

סיבות הסכמה לעומת סיבות של יכולת מסירה

אי אפשר להמציא החזרה

רק החזרות אמיתיות משפיעות על המוניטין שלכם

החסימה חלה לפי הכתובת או המספר

טבלת עזר ל־reason / source

ערכי `reason`

ערכי `source`

הצגת חסימות

Endpoint

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

דוגמת בקשה

תגובה

בדיקת מזהה בודד

Endpoint

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

דוגמת בקשה

תגובה - חסום

תגובה - לא חסום

הוספת חסימה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

דיווח על החזרה קשה

למה נקודת הקצה הזו נפרדת

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

ייבוא באצווה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

הסרת חסימה (unsuppress)

Endpoint

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

דוגמת בקשה

תגובה

הגירת רשימת חסימה קיימת

תגובות שגיאה

הצעדים הבאים